Professional Documents
Culture Documents
Developer's Guide
11g Release 1 (11.1.3)
E15524-03
March 2012
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.
Oracle Fusion Applications Developer's Guide 11g Release 1 (11.1.3)
E15524-03
Primary Author: Shelly Butcher, Richard Gugeler, Karen Ram, Karen Summerly, Chris Kutler, Vickie
Laughlin, Ralph Gordon, Peter Jew
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of
the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software
License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your
access to or use of third-party content, products, or services.
Contents
Preface .................................................................................................................................................................. li
Audience........................................................................................................................................................ li
Documentation Accessibility ...................................................................................................................... li
Related Documents ...................................................................................................................................... li
Conventions ................................................................................................................................................. lii
iii
2.2.3.1 Managing Integrated WebLogic Server ................................................................. 2-44
2.3 Setting Up the Personal Environment for Standalone WebLogic Server ........................ 2-44
2.3.1 How to Create a Domain for Standalone WebLogic Server ....................................... 2-45
2.3.1.1 Creating a Special SOAINFRA Schema.................................................................. 2-45
2.3.1.2 Setting Up the Environment for Standalone WebLogic Server .......................... 2-46
2.3.1.3 Managing the Standalone WebLogic Server Lifecycle......................................... 2-48
2.4 Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion Middleware Control
2-49
2.4.1 How to Use the Application Logging Service .............................................................. 2-49
2.4.2 How to Use Alternate Database Schemas ..................................................................... 2-51
2.5 Using Deployment Profiles Settings ..................................................................................... 2-51
2.5.1 How to Use Service Deployments.................................................................................. 2-52
2.5.2 How to Update the Standard .......................................................................................... 2-53
2.6 Configuring the Oracle Enterprise Scheduler (ESS) ........................................................... 2-53
2.6.1 How to Provision the Runtime Environment............................................................... 2-54
2.6.2 How to Create Supporting Database Schema .............................................................. 2-54
2.6.3 Post-Installation Checks................................................................................................... 2-55
2.6.3.1 Verifying the Temp Directory Location and Write Permissions ........................ 2-55
2.6.3.2 Verifying ESS Artifacts Deployment Targets ........................................................ 2-55
2.6.3.3 Checking ESS Health................................................................................................. 2-55
2.7 Testing Your Installation......................................................................................................... 2-56
2.8 Using Best Practices for Setting Up the Development Environment ............................... 2-64
2.8.1 How to Implement Best Practices for JDeveloper........................................................ 2-64
2.8.2 How to Refresh the Oracle ADF Library Dependencies Library............................... 2-65
2.8.3 How to Create the Integrated WebLogic Server Domain........................................... 2-66
2.8.4 How to Manage OutOfMemory Exceptions (PermGen) ............................................ 2-66
2.8.5 How to Work with Oracle ADF Libraries at Design Time ......................................... 2-67
2.9 Configuring Hierarchy Providers for Approval Management (AMX)............................ 2-68
iv
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 Workspace for Project-level MAR Deployment ....... 3-11
3.10.2.2 Building the EAR Profile .......................................................................................... 3-13
3.10.2.3 Deploying an Oracle Enterprise Scheduler Service Hosting Application......... 3-13
3.11 Implementing Oracle Application Development Framework UI Workspace and Projects ....
3-14
3.11.1 How to Set Up Your Web Project ................................................................................... 3-14
3.11.1.1 Configuring Your User Interface Project................................................................ 3-14
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 How to Identify Business Objects...................................................................................... 5-2
5.2.2 How to Identify Service Operations on the Business Objects ....................................... 5-2
5.2.2.1 Types of Operations ..................................................................................................... 5-2
5.2.2.2 Identifying Operations................................................................................................. 5-3
5.2.2.3 Defining Service Operations - General Guidelines.................................................. 5-4
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
v
5.3.1 How to Create Service Data Objects ................................................................................. 5-9
5.3.2 How to Create Services .................................................................................................... 5-10
5.3.2.1 What You May Need to Know About Design Time............................................. 5-10
5.3.3 How to Generate Synchronous and Asynchronous Service Methods...................... 5-11
5.4 Invoking Services ..................................................................................................................... 5-12
5.4.1 How to Invoke a Synchronous Service.......................................................................... 5-12
5.4.2 How to Invoke an Asynchronous Service..................................................................... 5-13
vi
7.11 Integrating Messages Task Flows into Oracle Fusion Functional Setup Manager ........ 7-18
10 Implementing Lookups
10.1 Introduction to Lookups ......................................................................................................... 10-1
10.1.1 Overview of Lookups....................................................................................................... 10-2
vii
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
14.1.2.1 Global Area Standard Links..................................................................................... 14-3
14.2 Populating a UI Shell............................................................................................................... 14-5
14.2.1 How to Create a JSF Page ................................................................................................ 14-5
14.2.1.1 Working with the Applications Menu Model ....................................................... 14-8
14.2.1.1.1 How to Create an Applications Menu ............................................................ 14-8
14.2.2 How to Add Default Main Area Task Flows to a Page............................................. 14-10
14.2.3 How to Add Dynamic Main Area and Regional Area Task Flows to a Page........ 14-19
14.2.3.1 Adding the Tasks List Menu to the Page ............................................................. 14-20
14.2.3.2 Grouping Tasks in the Tasks Pane into a Category............................................ 14-20
14.2.3.3 Linking to a Task Flow in a Different Page ......................................................... 14-21
14.2.3.4 Supporting No-Tab Workareas ............................................................................ 14-21
14.2.3.5 Implementing the Task Popup .............................................................................. 14-22
14.2.4 How to Pass Parameters into Task Flows from Tasks List ....................................... 14-23
14.2.5 How to Open Data Files from a Tasks List Link ........................................................ 14-25
14.3 Implementing Application Menu Security ........................................................................ 14-25
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 Menu............................................................................ 14-38
14.5.1.3 Implementing a Global Menu................................................................................ 14-39
14.5.2 How to Set Up Global Menu Security ......................................................................... 14-40
14.5.2.1 Enforcing User Privileges and Restrictions ......................................................... 14-40
14.5.3 How to Create the Navigator Menu ............................................................................ 14-41
14.5.3.1 Rendering the Navigator Menu as Pull-down Buttons ..................................... 14-42
14.6 Using the Personalization Menu.......................................................................................... 14-42
14.7 Implementing End User Preferences .................................................................................. 14-43
14.7.1 How to Use Preferences Link Navigation................................................................... 14-44
14.7.2 How to Use the Preferences Workarea Page .............................................................. 14-44
14.7.3 How to Deploy Preferences Pages and Design General Preferences Content....... 14-46
14.7.4 How to Configure and Implement End-User Preferences........................................ 14-46
14.7.4.1 Using the Preferences Menu Model...................................................................... 14-47
14.7.4.2 Configuring User Session and ADF Security ...................................................... 14-48
14.7.4.3 Retrieving Preference Values and Checking Accessibility Mode by Using an
Expression Language Expression 14-48
14.7.4.4 Implementing the Password Management Page ................................................ 14-48
14.7.5 How to Use the Most Common Preferences............................................................... 14-48
14.7.5.1 Configuring the Language Preference.................................................................. 14-48
14.7.5.2 Configuring the Accessibility Preference............................................................. 14-49
14.7.5.3 Configuring the Regional Preferences.................................................................. 14-49
14.8 Using the Administration Menu.......................................................................................... 14-50
ix
14.8.1 How to Secure the Administration Menu ................................................................... 14-51
14.9 Using the Help Menu ............................................................................................................ 14-52
x
15.3.4.12.1 Saved Search ..................................................................................................... 15-39
15.3.4.13 Import Watchlist UI JAR File in User Interface Project...................................... 15-40
15.3.4.14 Additional Entries for Standalone Deployment ................................................. 15-40
15.4 Implementing Group Spaces................................................................................................ 15-40
15.4.1 Assumptions.................................................................................................................... 15-40
15.4.2 How to Implement Group Spaces ................................................................................ 15-40
15.4.3 Overview of Group Spaces Functionality ................................................................... 15-41
15.4.4 How to Pass a Chromeless Template........................................................................... 15-41
15.5 Implementing Activity Streams and Business Events...................................................... 15-41
15.5.1 Introduction to WebCenter Portal Activities .............................................................. 15-42
15.5.2 How to Publish Business Events to Activities ............................................................ 15-42
15.5.3 How to Publish Activities Using a Programmatic API ............................................. 15-43
15.5.4 How to Implement Activity Streams ........................................................................... 15-46
15.5.4.1 Defining and Publishing Business Events in JDeveloper .................................. 15-46
15.5.4.2 Overriding isActivityPublishingEnabled() to Enable Activity Publishing..... 15-47
15.5.4.3 Defining Activity Attributes Declaratively.......................................................... 15-48
15.5.5 How to Define Activities ............................................................................................... 15-49
15.5.5.1 Adding the ActivityStream UI Task Flow ........................................................... 15-49
15.5.5.2 Defining Activities in the service-definition.xml File ........................................ 15-50
15.5.6 How to Implement Comments and Likes ................................................................... 15-54
15.5.7 How to Implement Follow for an Object..................................................................... 15-54
15.5.7.1 Defining the Service Category ............................................................................... 15-55
15.5.7.2 Adding ActivityTypes for Follow and Unfollow ............................................... 15-55
15.5.8 How to Render Contextual Actions in Activity Streams .......................................... 15-56
15.6 Implementing the Oracle Fusion Applications Search Results UI ................................. 15-57
15.6.1 How to Disable Oracle Fusion Applications Search.................................................. 15-57
15.6.2 How to Use Basic Search ............................................................................................... 15-57
15.6.2.1 Search Results .......................................................................................................... 15-59
15.6.3 How to Implement the GlobalSearchUtil API............................................................ 15-64
15.6.3.1 Using the Search API .............................................................................................. 15-65
15.6.3.2 Running the Oracle Fusion Applications Search UI Under Oracle WebLogic Server
15-65
15.6.4 Introduction to the Crawled Objects Project .............................................................. 15-65
15.6.5 How to Implement Tags in Oracle Fusion Applications Search.............................. 15-66
15.6.6 How to Use the Actionable Results API with Oracle Fusion Applications Search............
15-70
15.6.6.1 Implementing the URL Action Type .................................................................... 15-71
15.6.6.2 Implementing the Task Action Type .................................................................... 15-72
15.6.6.2.1 How to Implement Preferred Navigation .................................................... 15-74
15.6.6.3 Passing Parameters in Oracle Fusion Applications Search ............................... 15-76
15.6.6.4 Ordering the Other Actions ................................................................................... 15-77
15.6.6.5 Using Click Path and the Saved Search................................................................ 15-77
15.6.7 How to Integrate Non-Applications Data into Oracle Fusion Applications Search..........
15-78
15.6.7.1 Oracle Business Intelligence Integration.............................................................. 15-78
15.6.7.2 Integrating Oracle WebCenter Portal .................................................................. 15-80
15.6.7.3 Ensuring Parity of Users......................................................................................... 15-80
xi
16 Implementing Additional Functions in the UI Shell
16.1 Introducing the Navigate API................................................................................................ 16-1
16.1.1 How to Use the Navigate API Data Control Method.................................................. 16-2
16.1.2 How to Implement Navigation Across Web Applications......................................... 16-6
16.2 Warning of Pending Changes in the UI Shell ...................................................................... 16-7
16.2.1 How to Implement Warning of Pending Changes ...................................................... 16-7
16.2.2 How to Suppress Warning of Pending Changes ......................................................... 16-8
16.3 Implementing the Oracle Fusion Home Page UI ................................................................ 16-9
16.3.1 Supported Behavior.......................................................................................................... 16-9
16.3.2 How to Create a Home Page........................................................................................... 16-9
16.3.3 Getting the URL .............................................................................................................. 16-10
16.4 Using the Single Object Context Workarea........................................................................ 16-10
16.4.1 Implementation Notes ................................................................................................... 16-11
16.4.1.1 Developer Implementation .................................................................................... 16-12
16.5 Implementing the Third-Party Component Area ............................................................. 16-13
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-14
16.7 Troubleshooting UI Shell Issues .......................................................................................... 16-20
16.7.1 ApplSession Is Not Created .......................................................................................... 16-21
16.7.2 Navigator Shows a Little White Box............................................................................ 16-22
16.7.3 Navigator Shows Unfiltered Entries ............................................................................ 16-23
16.7.4 Other Navigation Issues ................................................................................................ 16-23
xii
17.2.1.2 Applications Tree Create Wizard.......................................................................... 17-32
17.2.1.3 Working with the Applications Tree .................................................................... 17-36
17.3 Implementing Applications Tree Tables ............................................................................ 17-37
17.3.1 How to Add an Applications Tree Table .................................................................... 17-45
17.3.1.1 Applications Tree Table Create Wizard ............................................................... 17-46
17.3.1.2 Working with the Applications Tree Table ......................................................... 17-50
17.3.1.2.1 Adding a Data Source...................................................................................... 17-51
17.3.1.2.2 Adding UI Content .......................................................................................... 17-51
17.3.1.2.3 Increasing Tree Table Width to Fill 100% of Its Container......................... 17-51
17.3.1.2.4 Toggle Click to Edit / Edit All in Applications Tree Table........................ 17-51
17.4 Using the Custom Wizard with Applications Popups ..................................................... 17-51
17.4.1 Creating a Popup ............................................................................................................ 17-52
17.4.1.1 How to Add Applications Popups to JSF Pages or Page Fragments ............... 17-52
17.4.1.2 How to Add Applications Popup Components Using the Wizard ................. 17-53
17.4.2 How to Modify Popup Components and Properties ................................................ 17-58
17.4.2.1 Accessing the Popup on a JSF Page ...................................................................... 17-58
17.4.2.2 Adding a Data Source to an Existing Popup ....................................................... 17-58
17.4.2.3 Adding User-Interface Content to an Existing Popup ....................................... 17-58
17.4.2.4 Adding action and actionListener Methods to the Popup Buttons.................. 17-59
xiii
18.4.1.1 Adding Applications Dialog Details .................................................................... 18-34
18.4.1.2 Working with the Applications Dialog Details................................................... 18-40
18.4.1.3 Implementing OK and Cancel Buttons in a Popup ............................................ 18-41
19 Implementing Attachments
19.1 Introduction to Attachments .................................................................................................. 19-1
19.2 Creating Attachments.............................................................................................................. 19-5
19.2.1 How to Set Up Your Model Project for Attachments .................................................. 19-7
19.2.2 How to Create Attachment View Links ........................................................................ 19-8
19.2.3 What Happens When You Create an Attachment View Link ................................. 19-13
19.2.4 How to Delete the Business Object .............................................................................. 19-14
19.2.5 How to Assign Categories to the Attachment Entity ................................................ 19-15
19.2.6 How to Create an Attachments Field or an Attachments Table .............................. 19-15
19.2.7 What Happens When You Implement Attachments................................................. 19-16
19.2.8 How to Create an Attachments Column in an Applications Table......................... 19-16
19.2.9 How to Set Up Required Properties............................................................................. 19-17
19.2.10 What Happens at Runtime ............................................................................................ 19-18
19.3 Displaying Attachments for Multiple Entities in the Same Table .................................. 19-19
19.3.1 How to Configure the Attachments Component to Display Attachments for Multiple
Entities 19-19
19.4 Configuring the Attachments Component UI ................................................................... 19-21
19.5 Working with Attachments Programmatically ................................................................. 19-25
19.5.1 Creating New Attachment Types................................................................................. 19-25
19.5.2 Retrieving Attachments ................................................................................................. 19-27
19.5.3 Using Attachment Utilities............................................................................................ 19-28
19.6 Setting Up Miscellaneous Attachments Features.............................................................. 19-29
19.6.1 Custom Actions............................................................................................................... 19-29
19.6.2 Approvals ........................................................................................................................ 19-29
19.7 Integrating Attachments Task Flows into Oracle Fusion Functional Setup Manager. 19-30
19.8 Securing Attachments ........................................................................................................... 19-30
19.8.1 Attachment Category Data Security ............................................................................ 19-31
19.8.1.1 How to Set Up Category Data Security................................................................ 19-31
19.8.2 File Sharing ...................................................................................................................... 19-32
19.8.3 Attachments SaaS ........................................................................................................... 19-32
19.9 Using Attachments (Runtime) ............................................................................................. 19-32
19.9.1 How to Use Attachments File-Level Security............................................................. 19-32
19.9.2 How to Update Attachments ........................................................................................ 19-33
19.9.2.1 Attachments Update Functions............................................................................. 19-34
19.9.2.2 Determining the Checked Out Status of File and Text-Type Attachments .... 19-35
19.9.2.3 Enabling or Disabling Attachments Update Functions ..................................... 19-35
19.9.3 How to Check Out and Check In File Attachments .................................................. 19-36
xiv
20.3.1 How to Manage Tree Structure Data Sources .............................................................. 20-7
20.3.2 How to Specify Data Source Parameters....................................................................... 20-8
20.3.2.1 Implementing Use Cases .......................................................................................... 20-9
20.3.2.1.1 Example Use Case .............................................................................................. 20-9
20.3.2.1.2 Basic Use Cases and Their Settings.................................................................. 20-9
20.3.3 How to Search for a Tree Structure.............................................................................. 20-13
20.3.4 How to Use the Search Field ......................................................................................... 20-14
20.3.5 How to Create a Tree Structure .................................................................................... 20-15
20.3.6 How to Duplicate a Tree Structure .............................................................................. 20-24
20.3.7 How to Edit a Tree Structure ........................................................................................ 20-24
20.3.8 How to Delete a Tree Structure .................................................................................... 20-25
20.3.9 How to Set Tree Structure Status.................................................................................. 20-26
20.3.10 How to Audit a Tree Structure ..................................................................................... 20-26
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-36
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.3 How to Create a Record for a Data Source ................................................................. 20-45
20.5.4 How to Duplicate a Tree Version ................................................................................. 20-47
20.5.5 How to Edit a Tree Version ........................................................................................... 20-47
20.5.6 How to Delete a Tree Version ....................................................................................... 20-48
20.5.7 How to Set Tree Version Status .................................................................................... 20-49
20.5.8 How to Audit Trees and Tree Versions....................................................................... 20-49
20.5.9 How to Flatten Rows and Columns ............................................................................. 20-55
20.6 Managing Labels in the Generic Label Data Source ......................................................... 20-57
20.6.1 How to Search for a Label ............................................................................................. 20-57
20.6.2 How to Create a Label.................................................................................................... 20-58
20.6.3 How to Edit a Label........................................................................................................ 20-59
20.6.4 How to Delete a Label.................................................................................................... 20-59
20.7 Using the Applications Hierarchy Component to Develop Applications..................... 20-60
20.7.1 How to Create a Tree Application................................................................................ 20-61
20.7.2 How to Create a Tree Table Application..................................................................... 20-63
20.8 Integrating Custom Task Flows into the Applications Hierarchy Component............ 20-65
20.8.1 Registering Custom Task Flows ................................................................................... 20-65
20.8.2 Creating Custom Task Flows ........................................................................................ 20-67
20.8.2.1 How to Create a Search Task Flow for the Add Node Operation.................... 20-67
xv
20.8.2.2 How to Create a Create Task Flow ....................................................................... 20-68
20.8.2.3 How to Create a Duplicate Task Flow.................................................................. 20-69
20.8.2.4 How to Create an Edit Task Flow ......................................................................... 20-71
20.8.2.5 How to Create a Delete Task Flow........................................................................ 20-72
20.9 Using the fnd:hierarchy Property Inspector to Specify Tree Versions........................... 20-73
20.10 Using the Expression Builder to Bind TreeCode, TreeStructureCode, and TreeVersionId
Properties 20-76
20.11 Embedding the Tree Picker Component in a User Interface .......................................... 20-76
20.12 Setting Bind Variables and View Criteria........................................................................... 20-78
20.12.1 How to Set Bind Variables and View Criteria ............................................................ 20-78
20.13 Using Service APIs to Manage Trees .................................................................................. 20-79
20.13.1 How to Use TreeStructureService ................................................................................ 20-79
20.13.2 How to Use TreeService................................................................................................. 20-80
20.13.3 How to Use TreeNodeService....................................................................................... 20-82
20.14 Advanced Topics.................................................................................................................... 20-84
20.14.1 Using the Tree Data Model ........................................................................................... 20-84
20.14.2 Using PL/SQL APIs ....................................................................................................... 20-85
20.14.3 Using Incremental Flattening........................................................................................ 20-85
20.14.3.1 How to Use FND_TREE_FLATTENING_HISTORY ......................................... 20-86
20.14.3.2 How to Use FND_TREE_LOG............................................................................... 20-86
20.14.3.3 How to Use FND_TREE_LOG_PARAMS............................................................ 20-87
20.14.3.4 Flattening Rows ....................................................................................................... 20-87
20.14.3.4.1 IS_LEAF ............................................................................................................. 20-88
20.14.3.4.2 DISTANCE ........................................................................................................ 20-88
20.14.3.5 Flattening Columns ................................................................................................. 20-89
20.14.4 Using Trees Business Events ......................................................................................... 20-90
xvi
21.4.1.3 Formatting Timestamp Values .............................................................................. 21-15
21.4.2 What Happens When You Format Dates and Timestamps ..................................... 21-16
21.4.3 What Happens at Runtime: How Dates and Timestamps Are Formatted ............ 21-17
21.4.4 Standards and Guidelines for Formatting Dates and Timestamps ......................... 21-17
21.5 Formatting Time Zones......................................................................................................... 21-17
21.5.1 How to Format Time Zones .......................................................................................... 21-17
21.5.2 How to Format Invariant Time Zone Values.............................................................. 21-21
21.5.3 What Happens When You Format Time Zones ......................................................... 21-21
21.5.4 What Happens at Runtime: How Time Zones Are Formatted ................................ 21-22
21.5.5 Standards and Guidelines ............................................................................................. 21-22
21.6 Formatting Numbers, Currency and Dates Using Localization Expression Language
Functions 21-22
21.6.1 How to Format Numbers, Currency and Dates Using Expression Language Functions .
21-22
21.6.1.1 Formatting Numbers Using Expression Language Functions.......................... 21-23
21.6.1.2 Formatting Currency Using Expression Language Functions.......................... 21-24
21.6.1.3 Formatting Dates Using Expression Language Functions ................................ 21-24
21.6.2 What Happens When You Format Numbers, Currency and Dates Using Expression
Language Functions 21-25
21.6.3 What Happens at Runtime: How Currency, Dates and Numbers and Time Zones are
Formatted Using Expression Language Functions 21-25
21.7 Implementing Bi-directional Support ................................................................................. 21-25
21.7.1 How to Implement Bi-directional Support ................................................................. 21-26
21.7.1.1 Making Panels and Columns Provide Bi-directional Support.......................... 21-26
21.7.1.2 Making Images Provide Bi-directional Support ................................................. 21-27
21.8 Supporting Mnemonic Keys................................................................................................. 21-28
21.8.1 How to Implement Mnemonic Key Support .............................................................. 21-28
21.9 Implementing Localization Formatting in ADF Desktop Integration ........................... 21-30
21.9.1 How to Format Numbers ............................................................................................. 21-30
21.9.1.1 Formatting Numbers............................................................................................... 21-31
21.9.1.2 What Happens When You Format Numbers ...................................................... 21-33
21.9.1.3 What Happens at Runtime: How Numbers Are Formatted ............................. 21-33
21.9.2 How to Format Currency Values ................................................................................. 21-33
21.9.2.1 Formatting Currency Values ................................................................................. 21-33
21.9.2.2 What Happens When You Format Currencies ................................................... 21-34
21.9.2.3 What Happens at Runtime: How Currency Values Are Formatted ................ 21-34
21.9.3 How to Format Dates and Timestamp Values ........................................................... 21-34
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-36
21.9.3.3 What Happens at Runtime: How Date and Timestamp Are Formatted......... 21-36
21.9.3.4 Honoring Time Zones............................................................................................. 21-37
21.10 Implementing Localization Formatting in Oracle BI Publisher Reports ....................... 21-37
21.10.1 How to Format Numbers in a BI Publisher Report ................................................... 21-37
21.10.2 How to Format Currency Values in BI Publisher ...................................................... 21-39
21.10.3 How to Format Dates and Timestamps in BI Publisher ........................................... 21-42
21.10.4 How to Honor Time Zones in BI Publisher ................................................................ 21-45
21.11 Implementing Localization Formatting in ADF Data Visualization Components ...... 21-45
21.11.1 How to Format Numbers on a Graph.......................................................................... 21-45
xvii
21.11.2 Standards and Guidelines for Formatting Numbers in Graphs .............................. 21-47
21.11.3 How to Format Currency Values in ADF Data Visualization.................................. 21-48
21.11.3.1 Formatting Currency Values on a Graph............................................................. 21-48
21.11.3.2 Standards and Guidelines for Formatting Currency Values in Graphs .......... 21-49
21.11.4 How to Format Dates and Timestamp Values in ADF Data Visualization ........... 21-50
21.11.4.1 Formatting Dates and Timestamp Values on a Graph ...................................... 21-50
21.12 Configuring National Language Support Attributes ....................................................... 21-51
21.12.1 Session National Language Support Attributes......................................................... 21-52
21.12.2 Database Session Attributes .......................................................................................... 21-55
21.13 Standards and Guidelines for Localization Formatting ................................................... 21-57
xviii
23.2.6.2 Registering a Flexfield Parameter Using the Setup APIs .................................. 23-15
23.3 Creating Descriptive Flexfield Business Components ..................................................... 23-15
23.3.1 How to Create Descriptive Flexfield Business Components.................................... 23-16
23.4 Creating Descriptive Flexfield View Links ........................................................................ 23-21
23.4.1 How to Create Descriptive Flexfield View Links....................................................... 23-21
23.5 Nesting the Descriptive Flexfield Application Module Instance in the Application Module.
23-23
23.5.1 How to Nest the Descriptive Flexfield Application Module Instance in the Application
Module 23-24
23.6 Adding a Descriptive Flexfield View Object to the Application Module...................... 23-25
23.6.1 How to Add a Descriptive Flexfield View Object Instance to the Application Module ...
23-25
23.7 Adding Descriptive Flexfield UI Components to a Page................................................. 23-26
23.7.1 How to Add a Descriptive Flexfield UI Component to a Form............................... 23-26
23.7.2 How to Add an Unrestricted Descriptive Flexfield UI Component to a Table ..... 23-28
23.7.3 How to Add Descriptive Flexfield Context-Sensitive Segments to a Table as Columns ..
23-30
23.7.4 How to Add Create Row and Delete Row Functionality to the Page..................... 23-32
23.7.5 How to Add a Row to an Empty Table in a Custom createInsert Method ............ 23-33
23.7.6 How to Dynamically Refresh a Descriptive Flexfield ............................................... 23-34
23.7.7 What Happens When You Add a Descriptive Flexfield to a Page .......................... 23-34
23.8 Configuring Descriptive Flexfield UI Components.......................................................... 23-35
23.8.1 How to Configure Flexfield-Level UI Properties ....................................................... 23-35
23.8.2 How to Configure Segment-Level UI Properties ....................................................... 23-37
23.8.2.1 Configuring a Context Segment ............................................................................ 23-38
23.8.2.2 Configuring All Global Segments ......................................................................... 23-38
23.8.2.3 Configuring Individual Global Segments............................................................ 23-39
23.8.2.4 Configuring All Context-Sensitive Segments...................................................... 23-39
23.8.2.5 Configuring Individual Context-Sensitive Segments ........................................ 23-39
23.8.3 How to Configure Descriptive Flexfield Parameters ................................................ 23-40
23.9 Loading Seed Data ................................................................................................................. 23-40
23.10 Working with Descriptive Flexfield UI Programmatically.............................................. 23-41
23.10.1 How to Update a Descriptive Flexfield Programmatically ...................................... 23-41
23.10.2 How to Determine Whether Descriptive Flexfield Segments Have Been Defined 23-41
23.10.3 How to Configure a Descriptive Flexfield to Handle Value Change Events......... 23-41
23.11 Incorporating Descriptive Flexfield into a Search Form .................................................. 23-42
23.11.1 How to Incorporate Descriptive Flexfields Into a Search Form............................... 23-42
23.12 Preparing Descriptive Flexfield Business Components for Oracle Business Intelligence........
23-44
23.12.1 How to Enable a Descriptive Flexfield for Oracle Business Intelligence................ 23-45
23.12.2 How to Flatten the Descriptive Flexfield Model for a Business Intelligence–Enabled
Descriptive Flexfield 23-46
23.13 Publishing Descriptive Flexfields as Web Services........................................................... 23-48
23.13.1 How to Expose a Descriptive Flexfield as a Web Service ......................................... 23-49
23.13.2 How to Test the Web Service ........................................................................................ 23-53
23.14 Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook ...........
23-58
xix
23.14.1 How to Configure ADF Desktop Integration with a Dynamic Column Descriptive
Flexfield 23-59
23.14.2 How to Handle User-Initiated Context Value Changes in a Dynamic Column
Descriptive Flexfield 23-60
23.14.3 How to Configure ADF Desktop Integration with a Static Column Descriptive
Flexfield 23-61
23.14.4 How to Handle Updating or Inserting of a Descriptive Flexfield Data Row ........ 23-61
xx
24.6.2.3 Using the Task Flows in the Page ......................................................................... 24-28
24.6.3 How to Expose One Logical Page and Its Contexts................................................... 24-29
24.6.4 How to Expose One Extensible Flexfield Context ..................................................... 24-29
24.7 Loading Seed Data ................................................................................................................. 24-30
24.8 Customizing the Extensible Flexfield Modelers................................................................ 24-31
24.8.1 How to Customize the Runtime Business Component Modeler for Extensible
Flexfields 24-31
24.8.2 How to Customize the Runtime User Interface Modeler for Extensible Flexfields...........
24-32
24.8.2.1 Creating the Customizer Wrapper Class ............................................................. 24-32
24.8.2.1.1 How to Customize the Context JSF Page Fragment.................................... 24-33
24.8.2.1.2 How to Customize the Segment Components in the Generated Context Task
Flow 24-33
24.8.2.1.3 How to Customize the Page Links in the Generated Links Task Flow.... 24-33
24.8.2.1.4 How to Customize the Page Task Flow ........................................................ 24-33
24.8.2.1.5 How to Customize the Search Task Flow ..................................................... 24-33
24.8.2.1.6 How to Create a Metadata Provider Implementation ................................ 24-35
24.8.2.1.7 How to Register the Metadata Provider Class for the Business Component.......
24-35
24.9 Testing the Flexfield .............................................................................................................. 24-35
24.10 Accessing Information About Extensible Flexfield Business Components................... 24-36
24.10.1 How to Access Information About Extensible Flexfield Business Components... 24-36
xxi
25.2.2 How to Implement Key Flexfield Segment Labels .................................................... 25-13
25.2.2.1 Defining Key Flexfield Segment Labels ............................................................... 25-13
25.2.2.2 Using Value Attributes ........................................................................................... 25-14
25.2.3 How to Implement Cross Validation Rules and Custom Validation...................... 25-15
25.2.3.1 Implementing Cross Validation Rules ................................................................. 25-15
25.2.3.2 Implementing Custom Validation ........................................................................ 25-17
25.2.4 How to Create Key Flexfield Business Components ................................................. 25-18
25.2.4.1 Building a Writable Maintenance Model ............................................................. 25-20
25.2.4.1.1 How to Create Key Flexfield Business Components for a Maintenance Model ..
25-20
25.2.4.1.2 How to Link Your Maintenance Model Key Flexfield Business Components to
Your Code Combination Master View Object 25-24
25.2.4.1.3 How to Create the Maintenance Application Module................................ 25-25
25.2.4.1.4 How to Manage Combination Locking......................................................... 25-27
25.2.4.2 Enabling Dynamic Combination Insertion .......................................................... 25-28
25.2.4.2.1 Enabling Dynamic Combination Insertion................................................... 25-28
25.2.4.2.2 Inserting a Code Combination — the Simplest Case .................................. 25-28
25.2.4.2.3 Inserting a Code Combination with Added Combination Attributes...... 25-29
25.2.4.2.4 Inserting a Code Combination that Uses Custom Validation Procedures or
Cross Validation Rules 25-33
25.2.4.3 Building a Read-Only Reference Model............................................................... 25-34
25.2.5 How to Share Key Flexfield Business Components................................................... 25-34
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.7 What Happens at Runtime: Creating New Combinations ....................................... 25-36
25.3 Completing the Consumer Tasks for Key Flexfields in Reference Mode ...................... 25-36
25.3.1 How to Create Key Flexfield View Links.................................................................... 25-37
25.3.2 How to Nest an Instance of the Key Flexfield Application Module in the Product
Application Module 25-39
25.3.3 How to Add an Instance of a Key Flexfield View Object to the Product Application
Module 25-39
25.3.4 How to Employ Key Flexfield UI Components on a Page ....................................... 25-40
25.3.4.1 Adding Key Flexfield UI Components to a Form or a Table ............................ 25-42
25.3.4.2 Ensuring Proper Handling of New Rows............................................................ 25-43
25.3.4.3 Ensuring Proper Updating of Reference Mode SIN values in an ADF Form or ADF
Applications Table 25-44
25.3.4.4 Ensuring Proper Updating of Partial Mode SIN Values in an ADF Form...... 25-45
25.3.4.5 Dynamically Refreshing Partial Flexfield Segments and Segments on a
Combinations Page 25-45
25.3.4.6 What Happens When You Add a Key Flexfield to a Page ................................ 25-46
25.3.5 How to Configure Key Flexfield UI Components ..................................................... 25-47
25.3.5.1 Configuring Flexfield-Level User Interface Properties ...................................... 25-48
25.3.5.2 Configuring Label-Based Segment UI Properties............................................... 25-51
25.3.5.3 Configuring Partial Usage UI Properties ............................................................. 25-52
25.3.6 How to Incorporate Key Flexfields Into a Query Search Form................................ 25-53
25.3.6.1 Setting Up the Business Component Model Layer............................................. 25-53
25.3.6.2 Creating the Query Search Form........................................................................... 25-55
xxii
25.4 Using Key Flexfield Advanced Features in Reference Mode .......................................... 25-58
25.4.1 How to Define Code Combination Constraints ......................................................... 25-58
25.4.1.1 Creating a View Accessor to Define a Code Combination Constraint ............ 25-59
25.4.1.2 Constraining Code Combinations by an Extra WHERE Clause....................... 25-62
25.4.1.3 Constraining Code Combinations by Validation Date ...................................... 25-62
25.4.1.4 Constraining Code Combinations by Validation Rules..................................... 25-63
25.4.1.4.1 How to Create Validation Rules .................................................................... 25-63
25.4.1.4.2 How to Set the Bind_ValidationRules Parameter........................................ 25-65
25.4.1.5 Enabling or Disabling Dynamic Combination Creation for a Specific Usage 25-65
25.4.2 How to Access Segment Labels Using the Java API.................................................. 25-66
25.4.3 How to Prepare Key Flexfield Business Components for Oracle Business Intelligence ...
25-67
25.4.3.1 Enabling a Key Flexfield for Oracle Business Intelligence ................................ 25-67
25.4.3.2 Producing a Business Intelligence–Enabled Flattened Key Flexfield Model.. 25-68
25.4.4 How to Publish Key Flexfield Application Modules as Web Services ................... 25-70
25.4.4.1 Exposing a Key Flexfield Application Module as a Web Service..................... 25-72
25.4.4.2 Testing the Web Service.......................................................................................... 25-80
25.4.5 How to Access Key Flexfields from an ADF Desktop Integration Excel Workbook.........
25-82
25.4.5.1 Configuring ADF Desktop Integration with a Dynamic Column Key Flexfield ........
25-84
25.4.5.2 Handling User-Initiated Structure Code Value Changes in a Dynamic Column Key
Flexfield 25-85
25.4.5.3 Configuring ADF Desktop Integration with a Static Column Key Flexfield.. 25-85
25.4.5.4 Handling Update or Insert of a Key Flexfield Data Row .................................. 25-86
25.5 Completing the Development Tasks for Key Flexfields in Partial Mode ...................... 25-89
25.5.1 How to Register a Key Flexfield All-Segment Partial Usage ................................... 25-90
25.5.2 How to Register a Key Flexfield Single-Segment Partial Usage.............................. 25-91
25.5.3 How to Create Partial Mode Key Flexfield Business Components ......................... 25-91
25.5.4 How to Create Partial Mode Key Flexfield View Links............................................ 25-96
25.6 Working with Combination Filters for Key Flexfields ..................................................... 25-98
25.6.1 How to Prepare the Database for Standard Key Flexfield Combination Filters . 25-101
25.6.2 How to Add Combination Filters to Your Application .......................................... 25-101
25.6.2.1 Creating a Filter Entity Object for a Standard Filter......................................... 25-101
25.6.2.2 Creating a Filter View Object............................................................................... 25-105
25.6.2.3 Associating Combination Filters with Key Flexfields...................................... 25-105
25.6.2.4 Configuring, Deploying and Testing Combination Filters ............................. 25-106
25.6.3 How to Employ Combination Filters on an Application Page .............................. 25-107
25.6.3.1 Adding Your Key Flexfield Filter to an Application Page .............................. 25-107
25.6.3.2 What Happens When You Add a Filter Repository Filter to an Application Page ....
25-110
25.6.4 How to Create Combination Filter Definitions for Testing .................................... 25-111
25.6.5 How to Apply Combination Filters Using the PL/SQL Filter APIs ..................... 25-113
25.6.5.1 Applying Standard Filters Using the WHERE Clause API ............................. 25-113
25.6.5.2 Applying Repository Filters for Oracle Enterprise Scheduler Service .......... 25-117
25.6.6 How to Remove Combination Filters from Your Application............................... 25-118
25.6.7 How to Remove Filters from the Filter Repository.................................................. 25-119
xxiii
26 Testing and Deploying Flexfields
26.1 Testing Flexfields ..................................................................................................................... 26-1
26.1.1 How to Make Flexfields Available for Testing............................................................. 26-1
26.1.2 How to Test Flexfields ..................................................................................................... 26-2
26.2 Deploying Flexfields in a Standalone WebLogic Server Environment............................ 26-4
26.2.1 How to Package a Flexfield Application for Deployment.......................................... 26-4
26.2.1.1 Enabling the Flexfield Packaging Plugin ............................................................... 26-4
26.2.1.2 Generating an EAR File for the Application.......................................................... 26-4
26.2.2 How to Deploy a Flexfield Application......................................................................... 26-5
26.2.2.1 Creating an MDS Partition ....................................................................................... 26-6
26.2.2.2 Mapping the EAR File to the MDS Partition ......................................................... 26-7
26.2.2.3 Mapping the ApplCore Setup Application to the MDS Partition ...................... 26-8
26.2.2.4 Including Product Application Model Libraries in the ApplCore Setup EAR File ....
26-9
26.2.2.5 Deploying the Product and Setup Applications to the Server Domains........... 26-9
26.2.2.6 Priming the MDS Partition with Configured Flexfield Artifacts ..................... 26-10
26.2.3 How to Configure Flexfields......................................................................................... 26-10
26.3 Using the WLST Flexfield Commands ............................................................................... 26-10
26.3.1 How to Prepare Your Environment to Use the WLST Flexfield Commands ........ 26-11
26.3.2 How to Prepare Your Environment to Use the deployFlexForApp Command.... 26-11
26.4 Regenerating Flexfield Business Components Programmatically.................................. 26-11
26.5 Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager ........ 26-13
xxiv
27.2.3.2 Setting the Connection Information in Linux...................................................... 27-10
27.2.4 How to Manually Connect to the Oracle Fusion Applications Database............... 27-10
27.2.5 How to Provide the Path of the JPS Config File ......................................................... 27-12
27.2.6 How to Configure the Log Settings.............................................................................. 27-12
27.2.7 How to Automate the ECSF Command Line Administration Utility..................... 27-12
27.3 Setting Up Oracle Enterprise Manager and Discovering ECSF ...................................... 27-13
27.3.1 How to Register the ECSF Runtime MBean to the Integrated WebLogic Server.. 27-14
27.3.1.1 Adding the MBean listener to web.xml................................................................ 27-14
27.3.1.2 Creating the Application EAR File for Deployment .......................................... 27-14
27.3.1.3 Configuring Data Sources in Oracle WebLogic Server...................................... 27-14
27.3.1.4 Deploying the ECSF Application Using the EAR File ....................................... 27-15
27.3.1.5 Starting the Oracle WebLogic Server Instance .................................................... 27-15
27.3.2 How to Install Oracle Enterprise Manager ................................................................. 27-15
27.3.3 How to Discover ECSF in Oracle Enterprise Manager ............................................. 27-15
27.3.4 How to Add Users to the Administrators Group ...................................................... 27-16
xxv
28.4.1 How to Define Search Result Actions.......................................................................... 28-25
28.4.1.1 Access URL............................................................................................................... 28-26
28.4.1.2 Redirect Service........................................................................................................ 28-26
28.4.1.3 Adding Search Result Actions ............................................................................... 28-27
28.4.1.4 Defining Properties for Bounded Task Flows ..................................................... 28-29
28.4.1.5 Modifying Search Result Actions.......................................................................... 28-29
28.4.1.6 Deleting Search Result Actions.............................................................................. 28-30
28.4.2 What Happens When You Define Search Result Actions......................................... 28-30
28.4.3 What You May Need to Know About Defining Search Result Actions ................. 28-30
28.4.4 How to Implement Faceted Navigation ...................................................................... 28-30
28.4.4.1 Defining Lists of Values.......................................................................................... 28-31
28.4.4.2 Constraining View Objects by Stored Attributes................................................ 28-32
28.4.4.3 Creating Search Facets ............................................................................................ 28-33
28.4.4.4 Defining a Facet to Use a Child View Object Attribute ..................................... 28-35
28.4.4.5 Using the Select Text Resource Dialog to Select a Matching Text Resource... 28-36
28.4.4.6 Using the Select Text Resource Dialog to Create and Select a New Text Resource....
28-37
28.4.4.7 Modifying Search Facets......................................................................................... 28-37
28.4.4.8 Deleting Root Search Facets ................................................................................... 28-38
28.4.4.9 Deleting Child Search Facets ................................................................................. 28-38
28.4.4.10 Defining Facets That Support Ranges .................................................................. 28-38
28.4.4.11 Defining Derived Facets ......................................................................................... 28-39
28.4.5 What Happens When You Implement Faceted Navigation..................................... 28-39
28.4.6 What You May Need to Know About Implementing Faceted Navigation............ 28-39
28.5 Configuring Custom Properties for Searchable Objects................................................... 28-40
28.5.1 How to Modify Default Runtime Behavior of Searchable Objects .......................... 28-40
28.5.2 How to Make Searchable Objects Public..................................................................... 28-40
xxvi
30.3.3 How to Test the Control Feed ......................................................................................... 30-5
30.3.4 How to Test the Data Feed .............................................................................................. 30-6
30.3.5 How to Reset the State of the Feeds ............................................................................... 30-8
xxvii
32.5.2 How Recent Searches Are Processed ........................................................................... 32-29
32.6 Setting Up Federated Search ................................................................................................ 32-32
32.6.1 How to Create the SearchDB Connection on Oracle WebLogic Server Instance .. 32-32
32.6.2 How to Update the Application Deployment Profile with the Target Directory for
Searchable Objects 32-33
32.6.3 How to Update the Application to Reference the ECSF Service Shared Library .. 32-33
32.6.4 How to Add the ECSF Runtime Library ..................................................................... 32-34
32.6.5 How to Set the System Parameter for Web Service ................................................... 32-34
32.6.5.1 Setting the System Parameter in Java System Properties .................................. 32-34
32.6.5.2 Setting the System Parameter in the ecsf.properties File................................... 32-34
32.6.6 How to Package and Deploy the Search Application ............................................... 32-35
32.6.6.1 Running the ant Targets from the Command Line ............................................ 32-35
32.6.6.2 Running the ant Targets from Oracle JDeveloper .............................................. 32-35
32.6.7 How to Update the Search Application with New Searchable Objects or Dependencies
32-35
32.6.8 How to Set Up the ECSF Client Application for Federation .................................... 32-36
32.6.8.1 Adding Encryption Keys to cwallet.sso and default-keystore.jks.................... 32-36
32.6.8.2 Adding the Keystore to jps-config.xml ................................................................ 32-36
32.6.8.3 Creating the Proxy User ......................................................................................... 32-37
32.6.8.4 Updating connections.xml ..................................................................................... 32-37
32.6.9 How to Set the SearchContext Scope to GLOBAL ..................................................... 32-39
32.6.10 How to Integrate Federation Across Oracle Fusion Applications Product Families.........
32-39
32.7 Federating Oracle SES Instances.......................................................................................... 32-40
32.8 Raising Change Events Synchronously .............................................................................. 32-41
32.9 Using the External ECSF Web Service for Integration ..................................................... 32-42
32.9.1 Web Service Methods..................................................................................................... 32-42
32.9.2 ECSF Web Service WSDL and XSD.............................................................................. 32-42
32.9.3 Web Service Request XSDs and XMLs ........................................................................ 32-49
32.9.3.1 SavedSearch Request XSD...................................................................................... 32-49
32.9.3.2 QueryMetaData Request XSD ............................................................................... 32-53
32.9.3.3 engineInstanceRequest Request XSD ................................................................... 32-55
32.9.4 Web Service Response XSDs ......................................................................................... 32-55
32.9.4.1 getSavedSearch()...................................................................................................... 32-56
32.9.4.2 getSavedSearches() .................................................................................................. 32-58
32.9.4.3 saveSearch().............................................................................................................. 32-58
32.9.4.4 deleteSearch() ........................................................................................................... 32-58
32.9.4.5 getSavedSearchDetails............................................................................................ 32-58
32.9.4.6 search() ...................................................................................................................... 32-60
32.9.4.7 getEngineInstances() ............................................................................................... 32-63
32.9.5 How to Invoke the ECSF Web Service......................................................................... 32-66
32.9.5.1 Creating a JAX-WS Web Service Proxy................................................................ 32-66
32.9.5.2 Modifying the AppModuleSearchServiceSoapHttpPortClient Class.............. 32-66
32.10 Localizing ECSF Artifacts ..................................................................................................... 32-72
32.10.1 How to Translate Strings in Groovy Expressions ...................................................... 32-72
32.10.1.1 Associating Resource Bundles to View Objects .................................................. 32-72
32.10.1.2 Using the format() Function in Groovy Expressions.......................................... 32-73
32.10.1.3 Associating Translated Labels to Attributes........................................................ 32-73
xxviii
32.10.1.4 Using the getLabel() function in Groovy Expressions ....................................... 32-74
32.10.2 How to Localize Facet Display Names........................................................................ 32-74
32.10.2.1 Configuring LOVs for Localization Using the VL Table ................................... 32-75
32.10.2.2 Configuring LOVs for Localization Using the Resource Bundles.................... 32-76
32.10.3 How to Localize Crawl Management Display Names.............................................. 32-77
32.10.4 How to Localize Crawlable Dynamic Content........................................................... 32-78
32.10.5 How to Localize Crawlable Template Content .......................................................... 32-78
32.10.6 How to Determine Locale.............................................................................................. 32-79
32.10.6.1 Search Page............................................................................................................... 32-79
32.10.6.2 ECSF Command Line Administration Utility ..................................................... 32-79
32.10.6.3 Crawl ......................................................................................................................... 32-80
32.10.6.4 Query......................................................................................................................... 32-80
32.11 Using ECSF Diagnostics........................................................................................................ 32-80
32.11.1 Query Tests ...................................................................................................................... 32-80
32.11.1.1 Simple Query............................................................................................................ 32-80
32.11.1.2 Searchable Object Metadata ................................................................................... 32-81
32.11.1.3 Searchable Groups................................................................................................... 32-81
32.11.1.4 Advanced Query (Protected) ................................................................................. 32-82
32.11.2 Crawl Tests ...................................................................................................................... 32-82
32.11.2.1 Crawl Searchable Object......................................................................................... 32-82
32.11.2.2 SES Instance.............................................................................................................. 32-83
32.11.2.3 Control Feed ............................................................................................................. 32-83
32.11.2.4 Data Feed (Protected).............................................................................................. 32-84
32.11.3 Environment and Configuration Information............................................................ 32-84
32.11.3.1 Configuration Parameters ...................................................................................... 32-84
32.11.3.2 Environment Information ...................................................................................... 32-84
32.11.3.3 Data Source............................................................................................................... 32-84
32.11.3.4 Application Extension/ApplCore Session Locale (Protected).......................... 32-85
32.11.4 Security............................................................................................................................. 32-85
32.11.4.1 Security (Protected) ................................................................................................. 32-85
32.11.4.2 Credential Store ....................................................................................................... 32-85
32.11.4.3 Security Plugin (Protected) .................................................................................... 32-86
32.12 Troubleshooting ECSF........................................................................................................... 32-86
32.12.1 Problems and Solutions ................................................................................................. 32-86
32.12.1.1 Cannot Remove the ECSF Runtime Server Library............................................ 32-86
32.12.1.2 Cannot See Data in Data Feeds.............................................................................. 32-87
32.12.1.3 Configuration or Data Feed Execution Thread Is Busy for Longer than the
Configured Warning Timeout 32-87
32.12.1.4 Class Not Found Errors When Running the ECSF Servlet................................ 32-87
32.12.1.5 Out of Memory Error when Deploying the ECSF Application to Oracle WebLogic
Server or Running the Application 32-88
32.12.1.6 Blank Oracle ADF/UI Shell Pages ........................................................................ 32-88
32.12.1.7 Memory Leak on ThreadLocal Variable (SearchContext) ................................. 32-88
32.12.1.8 How to Check the Space Availability for SES Crawls in the Database ........... 32-89
32.12.1.9 How to Crawl with a Different User .................................................................... 32-89
32.12.1.10 "FND-6601 Search categories are not available" ................................................. 32-90
32.12.1.11 "FND-6603 Search is not currently available"...................................................... 32-90
xxix
32.12.1.12 "FND-6606 An application error occurred with this search" ............................ 32-91
32.12.1.13 Query Does Not Return Search Results but No Errors Are Displayed on the UI.......
32-91
32.12.1.14 FUSION_RUNTIME.FND_TABLE_OF_VARCHAR2_4000 Exception on Schedules
32-91
32.12.1.15 Where Can I Find the SES-ESS Crawler Logs?.................................................... 32-92
32.12.1.16 My Crawls Are Failing............................................................................................ 32-92
32.12.1.17 How to Get the Password for the SES Administration Page ............................ 32-92
32.12.2 Diagnosing ECSF Problems........................................................................................... 32-92
32.12.3 Need More Help?............................................................................................................ 32-93
xxx
34.7 Troubleshooting the Use Case ............................................................................................... 34-5
34.8 What You May Need to Know About Initiating a SOA Composite from a PL/SQL Stored
Procedure 34-5
34.9 Known Issues and Workarounds .......................................................................................... 34-6
xxxi
38.7 Troubleshooting the Use Case ............................................................................................... 38-3
38.8 What You May Need to Know About Invoking Custom Java Code from a SOA Composite
38-3
xxxii
41.5 Securing the Design Pattern ................................................................................................. 41-12
41.6 Verifying the Deployment .................................................................................................... 41-12
41.7 Troubleshooting the Use Case ............................................................................................. 41-13
41.7.1 Deployment ..................................................................................................................... 41-13
41.7.2 Runtime ............................................................................................................................ 41-13
41.8 What You May Need to Know About Invoking an Asynchronous Service from Another
SOA Composite 41-13
xxxiii
44.4.2.1 Import Libraries into the Java Project..................................................................... 44-3
44.4.2.2 Import Code Packages into the Java Project.......................................................... 44-3
44.4.2.3 Declare and Obtain Task Service Object References ............................................ 44-4
44.4.2.4 Obtain the Workflow Service Context Object ....................................................... 44-5
44.4.2.5 Obtain the Single Task Object and Set Task Outcome ......................................... 44-5
44.4.3 How to Use the Single Server Task Query Service API .............................................. 44-5
44.4.3.1 Import Libraries into the Java Project..................................................................... 44-6
44.4.3.2 Import Code Packages into the Java Project.......................................................... 44-6
44.4.3.3 Declare and Obtain Task Query Service Object References ................................ 44-6
44.4.3.4 Manage Query and Task Outcome States.............................................................. 44-7
44.4.4 How to Use the Federated Server Task Query Service API ....................................... 44-7
44.4.4.1 Import Libraries into the Java Project..................................................................... 44-7
44.4.4.2 Import Code Packages into the Java Project.......................................................... 44-7
44.4.4.3 Create a List of Servers for a Parallel Federated Query....................................... 44-7
44.4.4.4 Declare Task and Query Service References and Create the Workflow Client
Service Object 44-8
44.4.4.5 Obtain the Workflow Service Context.................................................................... 44-8
44.4.4.6 Implement Exception Handling for Federated Queries ...................................... 44-8
44.4.4.7 Manage Query and Task Outcome States.............................................................. 44-9
44.4.5 How to Query and Traverse Federated and Non-federated Query Result Sets ..... 44-9
44.4.5.1 Determine Query Service Search Criteria .............................................................. 44-9
44.4.5.2 Construct the Predicate for queryTasks() ............................................................ 44-11
44.4.5.3 Arrange the Order of Results Returned by the queryTasks() Method ............ 44-12
44.4.5.4 Construct the List of Display Columns for the queryTasks() Method ............ 44-12
44.4.5.5 Construct a List of OptionalInfo Items to be Returned from queryTasks() .... 44-12
44.4.5.6 Invoke queryTasks() with the Attribute Lists ..................................................... 44-13
44.4.5.7 Iterate through the Result Set ................................................................................ 44-13
44.4.5.8 Programmatically Set the Task Outcome............................................................. 44-14
44.5 Other Approaches.................................................................................................................. 44-15
44.6 Securing the Design Pattern ................................................................................................. 44-15
44.7 Verifying the Deployment .................................................................................................... 44-15
44.7.1 Deploying the Human Task .......................................................................................... 44-15
44.7.2 Deploying Programmatic Task Functionality ............................................................ 44-15
44.7.3 Invoking Programmatic Task Functionality ............................................................... 44-16
44.8 Troubleshooting the Use Case ............................................................................................. 44-16
44.8.1 Troubleshooting Task Data ........................................................................................... 44-16
44.8.2 Troubleshooting Java Code ........................................................................................... 44-16
44.9 What You May Need to Know About Implementing Email Notification for an Oracle ADF
Task Flow for a Human Task 44-16
xxxiv
45.4.3 Implementing Product-Specific Sections....................................................................... 45-7
45.4.3.1 How to Add Instructions.......................................................................................... 45-7
45.4.3.2 How to Modify Details ............................................................................................. 45-8
45.4.3.3 How to Modify Recommended Actions ................................................................ 45-9
45.4.3.4 How to Modify <PLACE APPLICATION SPECIFIC CONTENT HERE> ..... 45-10
45.4.3.5 How to Implement Links ....................................................................................... 45-11
45.4.3.6 How to Modify Comments and Attachments ..................................................... 45-11
45.4.3.7 How to Modify Related Links ............................................................................... 45-12
45.4.3.8 How to Modify History .......................................................................................... 45-13
45.4.4 Implementing a Task Detail with Contextual Area................................................... 45-13
45.4.5 Implementing Email Notification................................................................................. 45-13
45.4.5.1 Before You Begin ..................................................................................................... 45-13
45.4.5.2 Determining the Implementation Approach....................................................... 45-14
45.4.5.3 Using a Switcher Component ................................................................................ 45-15
45.4.5.4 Using a Separate View for Online and Email Versions ..................................... 45-15
45.4.5.5 Fine-Tuning the Emailable Page ........................................................................... 45-16
45.4.6 Displaying Localized Translated Data ........................................................................ 45-17
45.4.7 Displaying Rows in the Approval Task ...................................................................... 45-17
45.4.8 Configuring a Deployment Profile............................................................................... 45-18
45.5 Securing the Design Pattern ................................................................................................. 45-19
45.6 Verifying the Deployment .................................................................................................... 45-19
45.7 Troubleshooting the Use Case ............................................................................................. 45-21
45.7.1 Specify oracle.soa.workflow.wc in weblogic-application.xml ................................. 45-22
45.7.2 Set the FRAME_BUSTING Attribute in web.xml ...................................................... 45-22
45.7.3 Migrate from an Earlier Version of the Drop Handler Template ............................ 45-22
45.7.4 Override the EL for the Create Button......................................................................... 45-23
xxxv
47 Getting Started with Security
47.1 Introduction to Securing Oracle Fusion Applications........................................................ 47-1
47.1.1 Architecture ....................................................................................................................... 47-1
47.1.1.1 Oracle Platform Security Services (OPSS) Security Framework......................... 47-3
47.1.1.2 Oracle Web Services Manager ................................................................................. 47-4
47.1.1.3 Oracle ADF Security.................................................................................................. 47-5
47.1.1.4 Application User Sessions ........................................................................................ 47-5
47.1.1.5 Oracle Fusion Data Security..................................................................................... 47-6
47.1.1.6 Oracle Virtual Private Database .............................................................................. 47-6
47.1.1.7 Oracle Data Integrator .............................................................................................. 47-6
47.1.2 Authentication................................................................................................................... 47-6
47.1.2.1 Oracle Identity Management Repository............................................................... 47-7
47.1.2.1.1 Users..................................................................................................................... 47-7
47.1.2.1.2 Roles ..................................................................................................................... 47-7
47.1.2.1.3 Segregation of Duties......................................................................................... 47-7
47.1.2.1.4 File-Based Identity Store ................................................................................... 47-7
47.1.2.1.5 File-Based Policy Store....................................................................................... 47-8
47.1.2.1.6 ODI ....................................................................................................................... 47-8
47.1.2.2 Identity Propagation ................................................................................................. 47-8
47.1.2.3 Application User Session Propagation................................................................. 47-10
47.1.3 Authorization .................................................................................................................. 47-10
47.1.3.1 OPSS Application Security Repository ................................................................ 47-10
47.1.3.2 Oracle Fusion Data Security Repository .............................................................. 47-11
47.2 Authentication Techniques and Best Practices.................................................................. 47-11
47.2.1 APIs................................................................................................................................... 47-12
47.2.2 Expression Language ..................................................................................................... 47-12
47.2.3 Non-browser Based Login............................................................................................. 47-12
47.3 Authorization Techniques and Best Practices ................................................................... 47-12
47.3.1 Function Security ............................................................................................................ 47-12
47.3.1.1 Resource Entitlements and Permissions .............................................................. 47-13
47.3.1.2 Expression Language .............................................................................................. 47-13
47.3.2 Data Security ................................................................................................................... 47-14
47.3.2.1 APIs and Expression Language............................................................................. 47-14
47.3.2.2 Oracle Virtual Private Database ............................................................................ 47-14
47.3.2.3 Personally Identifiable Information...................................................................... 47-14
47.3.2.4 Data Role Templates ............................................................................................... 47-14
xxxvi
48.3.1.3 Setting Context Attributes........................................................................................ 48-7
48.3.1.4 Accessing the Connection ........................................................................................ 48-7
48.3.1.5 Accessing Session Context Using the Java API..................................................... 48-8
48.3.2 How to Access Sessions Using PL/SQL APIs .............................................................. 48-9
48.3.2.1 Initializing Sessions ................................................................................................... 48-9
48.3.2.2 Getting Context Attributes....................................................................................... 48-9
48.3.2.3 Setting Context Attributes........................................................................................ 48-9
xxxvii
49.8.2.2 Initializing the Data Security Task Flow Using a Managed Bean .................... 49-40
49.8.2.3 Registering the Managed Bean with Your Application's Task Flow ............... 49-43
49.8.3 How to Configure the Object Instance Task Flow to Display in a Dialog.............. 49-44
49.8.3.1 Creating the Task Flow Executable in the Region Page Definition FIle .......... 49-45
49.8.3.2 Initializing the Object-Instance Task Flow Using a Managed Bean................. 49-47
49.8.3.3 Registering the Managed Bean with Your Application's Task Flow ............... 49-49
49.8.4 How to Grant the End User Access to the Data Security Task Flows..................... 49-49
49.8.5 How to Grant the Application Access to the Application Policy Store .................. 49-50
49.8.6 How to Map the Application to an Existing Application Stripe.............................. 49-51
xxxviii
52.2.2 How to Configure the Key Store and Credential Store............................................... 52-3
52.2.3 How to Authorize the Service......................................................................................... 52-4
52.3 Securing the Portlet Client...................................................................................................... 52-7
52.4 Registering the Key Store and Writing to the Credential Store ........................................ 52-7
52.4.1 How to Register the Key Store and Write to the Credential Store ............................ 52-7
52.4.2 What Happens When You Register the Key Store and Write to the Credential Store ......
52-10
xxxix
55 Defining Profiles
55.1 Introduction to Profiles ........................................................................................................... 55-1
55.2 Integrating Profiles Task Flows into Oracle Fusion Functional Setup Manager ............ 55-2
55.3 Setting and Accessing Profile Values.................................................................................... 55-3
55.3.1 How to View and Set Profile Values Using the Setup UI ........................................... 55-4
55.3.2 How to Access Profile Values Programmatically ........................................................ 55-5
55.3.3 How to Access Profile Values Using Expression Language....................................... 55-5
55.4 Managing Profile Definitions ................................................................................................. 55-5
55.4.1 How to Edit Profile Definitions ...................................................................................... 55-6
55.4.2 Registering a New Profile Option .................................................................................. 55-8
55.5 Managing Profile Categories.................................................................................................. 55-8
55.5.1 How to Manage Profile Categories ................................................................................ 55-9
56 Initializing Oracle Fusion Application Data Using the Seed Data Loader
56.1 Introduction to the Seed Data Loader................................................................................... 56-1
56.2 Using the Seed Data Loader in JDeveloper.......................................................................... 56-2
56.2.1 Introduction to the Seed Data Framework.................................................................... 56-2
56.2.2 How to Set Up the Seed Data Environment ................................................................. 56-5
56.2.3 How to Use the Seed Data Extract Manager............................................................... 56-14
56.2.4 How to Use Seed Data Extract Processing .................................................................. 56-17
56.2.4.1 Understanding Extract Taxonomy Partition Selection Dialogs ........................ 56-17
56.2.4.2 Using the Extract Seed Data Command Line Interface...................................... 56-21
56.2.5 How to Use the Seed Data Upload Manager.............................................................. 56-24
56.2.5.1 Uploading Seed Data .............................................................................................. 56-25
56.2.5.1.1 How to Upload Seed Data Using the Command Line Interface ............... 56-27
56.2.5.1.2 How to Invoke Seed Loader Modes .............................................................. 56-28
56.2.6 How to Share Application Modules ............................................................................ 56-30
56.2.7 How to Update Seed Data ............................................................................................. 56-32
56.2.7.1 Using Incremental Updates ................................................................................... 56-32
56.2.7.2 Implementing Java Database Connectivity-based National Language Support
Updates 56-33
56.3 Translating Seed Data ........................................................................................................... 56-34
56.3.1 How to Extract Translation Data.................................................................................. 56-34
56.3.1.1 Treating Seed Data Base XML and Language XLIFF as a Single Entity.......... 56-34
56.3.2 How to Process Seed Data Translations ...................................................................... 56-34
56.3.3 How to Load Translation Seed Data ............................................................................ 56-34
56.3.4 Oracle Fusion Middleware Extensions for Applications Translation Support ..... 56-35
xl
57.2.5 Application User Defined Properties............................................................................. 57-5
57.2.5.1 User Defined Properties for Tables......................................................................... 57-5
57.2.5.2 User Defined Properties for Columns .................................................................... 57-9
57.2.5.3 User Defined Properties for Indexes..................................................................... 57-11
57.2.5.4 User Defined Properties for Constraints.............................................................. 57-12
57.2.5.5 User Defined Properties for Views ....................................................................... 57-13
57.2.5.6 User Defined Properties for Sequence.................................................................. 57-14
57.2.5.7 User Defined Properties for Materialized View.................................................. 57-15
57.2.5.8 User Defined Properties for Materialized View Log.......................................... 57-16
57.2.5.9 User Defined Properties for Trigger ..................................................................... 57-17
57.2.6 How to Create an Offline Database Object ................................................................. 57-17
57.2.7 How to Edit an Offline Database Object ..................................................................... 57-17
57.2.8 How to Import an Offline Database Object ................................................................ 57-18
57.2.9 How to Deploy the Offline Database Objects............................................................. 57-20
57.2.9.1 Deploying in SXML Persistence Format .............................................................. 57-20
57.2.9.1.1 How to Use the Database Object Deployment Wizard in JDeveloper ..... 57-20
57.2.9.1.2 How to Use the Database Object Deployment Command Line Interface 57-25
57.2.9.2 Setting the CLASSPATH Variable ........................................................................ 57-26
57.2.9.3 Using Bootstrap Mode ............................................................................................ 57-27
57.2.9.4 Deployment FAQ..................................................................................................... 57-27
57.2.9.5 Cleaning Database Objects ..................................................................................... 57-28
57.2.9.5.1 Making a Database Object Obsolete .............................................................. 57-28
57.2.9.5.2 How to Use the Force Mode Option in Schema Deployment ................... 57-29
57.2.9.5.3 How to Use fnd_cleanup_pkg and fnd_drop_obsolete_objects................ 57-29
57.2.9.5.4 Frequently Asked Questions .......................................................................... 57-31
57.3 Using Schema Separation to Provide Grants ..................................................................... 57-32
58 Improving Performance
58.1 Introduction to Improving the Performance of Applications ........................................... 58-1
58.2 ADF Business Components Guidelines................................................................................ 58-1
58.2.1 Working with Entity Objects........................................................................................... 58-2
58.2.1.1 Enable Batch Updates for your Entity Objects ...................................................... 58-2
58.2.1.2 Children Entity Objects in Composite Entity Associations Should not set the
Foreign Key Attribute Values of the Parent 58-2
58.2.1.3 Avoid Using List Validator Against Large Lists................................................... 58-2
58.2.1.4 Avoid Repeated Calls to the same Association Accessor .................................... 58-3
58.2.1.5 Close Unused RowSets ............................................................................................. 58-3
58.2.1.6 Use "Retain Association Accessor RowSet" when Appropriate ......................... 58-3
58.2.1.7 Mark the Change Indicator Column....................................................................... 58-4
58.2.2 Working with View Objects ............................................................................................ 58-4
58.2.2.1 Tune the View Object SQL Statement .................................................................... 58-4
58.2.2.2 Select the Correct Usage for View Objects............................................................. 58-5
58.2.2.3 Set Appropriate Fetch Size and Max Fetch Size.................................................... 58-5
58.2.2.4 Use Bind Variables .................................................................................................... 58-6
58.2.2.5 Include at Least One Required or Selectively Required View Criteria Item .... 58-6
58.2.2.6 Use Forward-Only Mode when Possible ............................................................... 58-6
58.2.2.7 Avoid Calling getRowCount ................................................................................... 58-7
xli
58.2.2.8 Avoid Entity Object Fault-in by Selecting Necessary Attributes Up-Front ...... 58-7
58.2.2.9 Reduce the Number of View Object Key Attributes to a Minimum.................. 58-7
58.2.2.10 Use Range Paging when Jumping to Different Row Ranges .............................. 58-7
58.2.2.11 Use setListenToEntityEvents(false) for Non-UI Scenarios .................................. 58-8
58.2.2.12 Use Appropriate Getter or Setter on View Row ................................................... 58-8
58.2.2.13 Use Appropriate Indexes with Case-Insensitive View Criteria Items ............... 58-8
58.2.2.14 Avoid View Object Leaks ......................................................................................... 58-9
58.2.2.15 Provide a "Smart" Filter when Using LOV Combobox ........................................ 58-9
58.2.2.16 Use Small ListRangeSize for LOVs ......................................................................... 58-9
58.2.2.17 Avoid Reference Entity Objects when not Needed .............................................. 58-9
58.2.2.18 Do Not Use the "All at Once" Fetch Mode in View Objects ................................ 58-9
58.2.2.19 Do Not Use the "Query List Automatically" List of Value Setting..................... 58-9
58.2.2.20 Avoid the "CONTAINS" or "ENDSWITH" Operator for Required or Selectively
Required View Criteria Items 58-9
58.2.3 Working with Application Modules............................................................................ 58-10
58.2.3.1 Enable Lazy Delivery .............................................................................................. 58-10
58.2.3.2 Make Application Code Passivation-Safe............................................................ 58-10
58.2.3.3 Avoid Passivating Read-Only View Objects ....................................................... 58-11
58.2.3.4 Avoid Passivating Certain Transient Attributes of a View Object................... 58-12
58.2.3.5 Maintain Application Session User Tables .......................................................... 58-12
58.2.3.6 Tune the Application Module Release Level....................................................... 58-14
58.2.3.7 Do Not Leave Uncommitted Database Updates Across Requests................... 58-17
58.2.3.8 Release Dynamically Created Root Application Modules ............................... 58-17
58.2.3.9 Do Not Destroy the Application Module when Calling Configuration.releaseRoot
ApplicationModule. 58-17
58.2.4 Working with Services ................................................................................................... 58-17
58.2.4.1 Set the Find Criteria to Fetch Only Attributes that are Needed ....................... 58-17
58.2.4.2 Expose Service for Frequently Used Logical Entities......................................... 58-18
58.2.4.3 Use Correct ChangeOperation when Calling a Service ..................................... 58-18
58.2.4.4 Set Only Changed Columns on Service Data Objects for Update.................... 58-18
58.3 ADF ViewController Layer Guidelines .............................................................................. 58-18
58.3.1 Working with Various ADF ViewController Components...................................... 58-18
58.3.1.1 Minimize the Number of Application Module Data Controls ......................... 58-18
58.3.1.2 Use the Visible and Rendered Attributes............................................................. 58-19
58.3.1.3 Remove Unused Items from Page Bindings ........................................................ 58-19
58.3.1.4 Disable Column Stretching .................................................................................... 58-19
58.3.1.5 Use Appropriate Values for Refresh and RefreshCondition............................. 58-19
58.3.1.6 Disable Estimated Row Count if Necessary ........................................................ 58-20
58.3.1.7 Use HTTPSession Hash Table in Moderation ..................................................... 58-20
58.3.1.8 Use Short Component IDs...................................................................................... 58-20
58.3.1.9 Follow UI Standards when Using Search ............................................................ 58-21
58.3.1.10 Avoid Executing Component Subtree by Adding a Condition Check............ 58-21
58.3.1.11 Do not set Client Component Property to True.................................................. 58-22
58.3.1.12 Set Immediate Property to True when Appropriate .......................................... 58-22
58.3.1.13 Use Appropriate ContentDelivery Mode for a Table or a Tree Table ............. 58-22
58.3.1.14 Set the Appropriate Fetch Size for a Table........................................................... 58-22
58.3.1.15 Avoid Frozen Columns and Header Columns if Possible ................................ 58-23
58.3.1.16 Avoid Unnecessary Regions .................................................................................. 58-23
xlii
58.3.1.17 Set the Data Control Scope to "Shared" ................................................................ 58-23
58.3.1.18 Select the No Save Point Option on a Task Flow when Appropriate.............. 58-23
58.3.1.19 Use Click-To-Edit Tables when Appropriate ...................................................... 58-23
58.3.1.20 Avoid Unnecessary Task Flow Activation for Regions Under Popups .......... 58-23
58.3.1.21 Delay Creation of Popup Child Components ..................................................... 58-24
58.3.1.22 Avoid Unnecessary Task Flow Activation for Regions Under Switchers....... 58-24
58.3.1.23 Avoid Unnecessary Root Application Module Creation from UI-layer Code 58-25
58.3.1.24 Avoid Unnecessary Savepoints on Task Flow Entry ......................................... 58-25
58.3.1.25 Cache Return Values in Backing Bean Getters.................................................... 58-25
58.3.1.26 Do Not Maintain References to UI Components in Managed Beans............... 58-26
58.3.2 Enable ADF Rich Client Geometry Management ...................................................... 58-26
58.3.3 Use Page Templates........................................................................................................ 58-26
58.3.4 Use ADF Rich Client Partial Page Rendering (PPR).................................................. 58-26
58.4 SOA Guidelines for Human Workflow and Approval Management Extensions........ 58-26
58.5 Oracle Fusion Middleware Extensions for Applications Guidelines ............................. 58-26
58.5.1 Use Profile.get to Get Profile Option Values .............................................................. 58-26
58.5.2 Release any Application Modules Returned from getInstance Calls...................... 58-27
58.5.3 Avoid Unnecessary Activation of Attachments Taskflow ....................................... 58-27
58.5.4 Use Static APIs on Message Get Message Text .......................................................... 58-27
58.5.5 Set the Data Control Scope to Isolated for Page Level Item Nodes ........................ 58-27
58.6 General Java Guidelines........................................................................................................ 58-28
58.6.1 Working with Strings and StringBuilder .................................................................... 58-28
58.6.1.1 Use StringBuilder Rather than the String Concatenation Operator (+)........... 58-28
58.6.1.2 Check the Log Level Before Making a Logging Call.......................................... 58-29
58.6.1.3 Use Proper Logging APIs for Debug Logging .................................................... 58-29
58.6.1.4 Lazy Instantiation .................................................................................................... 58-29
58.6.2 Configure Collections..................................................................................................... 58-30
58.6.3 Manage Synchronization ............................................................................................... 58-30
58.6.4 Work with Other Java Features .................................................................................... 58-30
58.6.4.1 Avoid Autoboxing................................................................................................... 58-30
58.6.4.2 Do not use Exceptions for Code Path Execution................................................. 58-31
58.6.4.3 Reuse Pattern Object for Regular Expression Matches ...................................... 58-31
58.6.4.4 Avoid Repeated Calls to the same APIs that have Non-Trivial Costs............. 58-31
58.6.4.5 Close Unused JDBC Statements to Avoid Memory Leaks ................................ 58-31
58.6.4.6 Use registerOutParameter to Specify Bind Types and Precisions.................... 58-33
58.6.4.7 Avoid JDBC Connection Leaks.............................................................................. 58-33
58.7 Caching Data .......................................................................................................................... 58-33
58.7.1 Identifying Data to Cache.............................................................................................. 58-33
58.7.2 How to Add Data to Cache ........................................................................................... 58-34
58.7.3 How to Cache Multi-Language Support Data............................................................ 58-35
58.7.3.1 Creating ADF Business Components objects for shared MLS data ................. 58-35
58.7.3.1.1 How to create objects if only the data from the base table needs to be shared....
58-35
58.7.3.1.2 How to create objects if only the data from the _TL table needs to be shared.....
58-35
58.7.3.1.3 How to create objects if both the data from the base table and the _TL table
needs to be shared 58-35
xliii
58.7.3.2 Creating ADF Business Components Objects that Join to MLS tables ............ 58-36
58.7.3.2.1 How to create objects if only the data from the base table is required..... 58-36
58.7.3.2.2 How to create objects if only data from the _TL table is required ............ 58-36
58.7.3.2.3 How to create objects if data from both the base table and the _TL table is
required 58-36
58.7.4 How to Consume Cached Data .................................................................................... 58-37
58.7.4.1 Consuming Shared Data Using a View Accessor ............................................... 58-37
58.7.4.2 Creating a shared application module programmatically ................................ 58-37
58.7.5 What Happens at Runtime: When Another Service Accesses the Shared Application
Module Cache 58-38
58.8 Profiling and Tracing Oracle Fusion Applications ........................................................... 58-38
58.8.1 How to Profile Oracle Fusion Applications with JDeveloper Profiler.................... 58-38
58.9 Set up a Debug Breakpoint ................................................................................................... 58-39
xliv
59.5.1.9 Missing ADF Component at Runtime in Oracle WebLogic Server.................. 59-12
59.5.1.10 Odd ADF Component Errors................................................................................. 59-13
59.5.1.11 Oracle WebLogic Server is Not Responding ....................................................... 59-13
59.5.1.12 Missing Base Class................................................................................................... 59-14
59.5.1.13 Unavailable FND Components ............................................................................. 59-14
59.5.1.14 JavaServer Pages Compilation Errors................................................................... 59-14
59.5.1.15 ApplicationDB Errors While Running the Integrated WebLogic Server ........ 59-14
59.5.1.16 Metadata Services Runtime Exception ................................................................. 59-15
59.5.1.17 Application Cannot Fetch Data from Oracle Fusion Applications Database . 59-15
59.5.1.18 "The task cannot be processed further" Message Appears................................ 59-15
59.5.1.19 TimedOut Exception Occurs.................................................................................. 59-16
59.6 Testing and Troubleshooting Oracle SOA Suite ............................................................... 59-16
xlv
60.5.4 Using Multi-Valued Dimension Attributes ................................................................ 60-14
60.5.5 Using Junk Dimensions and Mini Dimensions .......................................................... 60-15
60.5.6 Using Secured and Unsecured Dimension View Objects ......................................... 60-15
60.6 Designing Date Dimensions ................................................................................................. 60-15
60.6.1 Using the Gregorian Calendar...................................................................................... 60-15
60.6.2 Using the Fiscal Calendar .............................................................................................. 60-16
60.6.3 Using the Projects Calendar .......................................................................................... 60-16
60.6.4 Using Timestamp Columns........................................................................................... 60-16
60.6.5 Using Role-Playing Date Dimensions.......................................................................... 60-16
60.7 Designing Lookups as Dimensions ..................................................................................... 60-16
60.7.1 Securing Data on Lookups ............................................................................................ 60-17
60.8 Designing and Securing Tree Data...................................................................................... 60-17
60.8.1 Designing a Column-Flattened View Object for Oracle Business Intelligence...... 60-17
60.8.1.1 How to Generate a BICVO Automatically Using Tree Management .............. 60-20
60.8.2 Customizing the FND Table Structure and Indexes.................................................. 60-22
60.8.3 Using Declarative SQL Mode to Design View Objects for Oracle Business Intelligence
Applications 60-22
60.8.3.1 Using Single Data Source View Object Design Pattern .................................... 60-22
60.8.3.2 Using Multiple Data Source View Objects Design Pattern .............................. 60-23
60.8.3.3 Setting the Declarative-Mode BICVO Properties................................................ 60-25
60.8.4 Guidelines for ATG-Registration and BICVO Generation ....................................... 60-25
60.8.5 Guidelines for Hierarchy Depth and Conformance .................................................. 60-26
60.8.5.1 Resolving Problems................................................................................................. 60-28
60.8.6 Securing ADF Business Components View Objects for Trees ................................. 60-28
60.8.6.1 Security Implementation ........................................................................................ 60-29
60.9 Supporting Flexfields for Oracle Business Intelligence.................................................... 60-30
60.10 Supporting SetID.................................................................................................................... 60-30
60.10.1 How to Expose the SetID Attribute for Set-Enabled Lookups................................. 60-30
60.10.2 How to Expose the SetID Attribute for Set-Enabled Reference Tables................... 60-31
60.11 Supporting Multi-Currency.................................................................................................. 60-31
xlvi
62.2.4 How to Add Composer Technology Scope to Your Project ....................................... 62-6
62.2.5 How to Enable the User Customization of the UI Shell Template ............................ 62-7
62.2.6 How to Create a Database Connection at the IDE Level ............................................ 62-8
62.3 Enabling Runtime Customization of Pages and Components .......................................... 62-9
62.3.1 How to Enable Pages for Runtime Customization .................................................... 62-11
62.3.1.1 Ensuring Customizable Pages Have Page Definitions ...................................... 62-12
62.3.1.2 Making a JSPX Document Editable at Runtime .................................................. 62-12
62.3.1.3 Setting Up a Resource Catalog .............................................................................. 62-12
62.3.1.4 Using the Default Catalog Definition File for Testing ....................................... 62-12
62.3.2 How to Enable End-User Personalizations for a Page .............................................. 62-13
62.3.3 How to Restrict Customization of a Page, Page Fragment, or Component .......... 62-13
62.3.4 How to Authorize the Runtime Customization of Pages and Task Flows ............ 62-14
62.3.5 How to Persist Implicit Runtime Customizations ..................................................... 62-15
xlvii
63.9.2 What Happens When You Implement a Perl Scheduled Job ................................... 63-21
63.10 Implementing a C Scheduled Job ........................................................................................ 63-23
63.10.1 How to Define Metadata for a C Scheduled Job ........................................................ 63-23
63.10.2 How to Implement a C Scheduled Job ........................................................................ 63-23
63.10.3 Scheduled C Job API ...................................................................................................... 63-23
63.10.4 How to Test a C Scheduled Job..................................................................................... 63-25
63.10.5 What Happens When You Implement a C Scheduled Job ....................................... 63-26
63.10.6 What Happens at Runtime: How a C Scheduled Job Is Implemented ................... 63-29
63.11 Implementing a Host Script Scheduled Job ....................................................................... 63-29
63.12 Implementing a Java Scheduled Job ................................................................................... 63-30
63.12.1 How to Define Metadata for a Scheduled Java Job.................................................... 63-30
63.12.2 How to Use the Java Runtime API............................................................................... 63-30
63.12.3 How to Cancel a Scheduled Java Job ........................................................................... 63-30
63.12.4 What Happens at Runtime: How a Java Scheduled Job Is Implemented .............. 63-31
63.13 Elevating Access Privileges for a Scheduled Job............................................................... 63-31
63.13.1 How to Elevate Access Privileges for a Scheduled Job ............................................. 63-32
63.13.2 How Access Privileges Are Elevated for a Scheduled Job........................................ 63-33
63.13.3 What Happens When Access Privileges Are Elevated for a Scheduled Job .......... 63-34
63.14 Creating an Oracle ADF User Interface for Submitting Job Requests............................ 63-34
63.14.1 How to Create an Oracle ADF User Interface for Submitting Job Requests.......... 63-34
63.14.2 How to Add a Custom Task Flow to an Oracle ADF User Interface for Submitting Job
Requests 63-41
63.14.3 How to Enable Support for Context-Sensitive Parameters in an Oracle ADF User
Interface for Submitting Job Requests 63-42
63.14.4 How to Save and Schedule a Job Request Using an Oracle ADF UI....................... 63-43
63.14.5 How to Submit a Job Using a Saved Schedule in an Oracle ADF UI...................... 63-44
63.14.6 How to Notify Users or Groups of the Status of Executed Jobs .............................. 63-44
63.14.7 What Happens When You Create an Oracle ADF User Interface for Submitting Job
Requests 63-46
63.14.8 What Happens at Runtime: How an Oracle ADF User Interface for Submitting Job
Requests Is Created 63-46
63.15 Submitting Job Requests Using the Request Submission API......................................... 63-47
63.16 Defining Oracle Business Intelligence Publisher Post-Processing Actions for a Scheduled
Job 63-47
63.16.1 How to Define Oracle BI Publisher Post-Processing for a Scheduled Job.............. 63-48
63.16.2 How to Define Oracle BI Publisher Post-Processing Actions for a Scheduled PL/SQL
Job 63-52
63.16.3 What Happens When You Define Oracle BI Publisher Post-Processing Actions for a
Scheduled Job 63-52
63.16.4 What Happens at Runtime: How Oracle BI Publisher Post-Processing Actions are
Defined for a Scheduled Job 63-53
63.16.5 Invoking Post-Processing Actions Programmatically ............................................... 63-53
63.17 Monitoring Scheduled Job Requests Using an Oracle ADF UI....................................... 63-56
63.17.1 How to Monitor Scheduled Job Requests ................................................................... 63-56
63.17.2 How to Embed a Table of Search Results as a Region on a Page ............................ 63-57
63.17.3 How to Log Scheduled Job Requests in an Oracle ADF UI...................................... 63-59
63.17.4 How to Troubleshoot an Oracle ADF UI Used to Monitor Scheduled Job Requests ........
63-59
xlviii
63.18 Using a Task Flow Template for Submitting Scheduled Requests through an Oracle ADF
UI 63-61
63.18.1 How to Use a Task Flow Template for Submitting Scheduled Requests through an
Oracle ADF UI 63-62
63.18.2 How to Extend the Task Flow Template for Submitting Scheduled Requests through
an Oracle ADF UI 63-63
63.18.3 What Happens When you Use a Task Flow Template for Submitting Scheduled
Requests through an Oracle ADF UI 63-64
63.18.4 What Happens at Runtime: How a Task Flow Template Is Used to Submit Scheduled
Requests through an Oracle ADF UI 63-64
63.19 Securing Oracle ADF UIs...................................................................................................... 63-64
63.20 Integrating Scheduled Job Logging with Fusion Applications ....................................... 63-65
63.21 Logging Scheduled Jobs........................................................................................................ 63-65
63.21.1 Using the Request Log ................................................................................................... 63-65
63.21.2 Using the Output File..................................................................................................... 63-66
63.21.3 Debugging and Error Logging...................................................................................... 63-66
Part IX Appendices
xlix
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
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
l
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:
■ Java and SQL
■ Java EE, JavaServlets, and JavaServer Pages
■ Oracle Application Development Framework
■ 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.
Related Documents
For more information, see the following documents in the Oracle 11g Fusion
Middleware documentation set:
■ Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework
■ Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle
Application Development Framework
li
■ 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 Applications Edition)
■ Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence
Publisher (Oracle Fusion Applications Edition)
■ 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 Developer's Guide for Oracle SOA Suite
■ Oracle Fusion Middleware User's Guide for Oracle Business Rules
■ Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules
■ Oracle Fusion Middleware User's Guide for Technology Adapters
■ Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring
■ Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal
■ Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces
■ Oracle WebLogic Communication Services Developer's Guide
■ Oracle Fusion Middleware Application Security Guide
■ Oracle Fusion Applications Security Guide
■ Oracle Fusion Applications Security Hardening Guide
Conventions
The following text conventions are used in this document:
lii
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
liii
liv
What's New in This Guide for Release 11.1.3
This chapter provides information about what is new in the Oracle Fusion
Applications Developer's Guide 11g Release 1 (11.1.3) since Release 1 (11.1.2) was
released in September 2011.
lv
Sections Changes Made
Section 15.2.5, "How to Implement Data Security Added section describing how to add security to child pages so
for Recent Items and Favorites" a user cannot use the Recent Items or Favorites features to
bypass the security of the parent page.
Section 15.6.2, "How to Use Basic Search" Added these new features:
■ Recent Search
■ UI support to support SES alternate word feature
■ Order by and Universal Facet on LastModifiedDate
■ Hide facet values with zero hit count
Chapter 19, "Implementing Attachments"
Section 19.2, "Creating Attachments" "Before you begin:" section revised to include information about
controlling the upload size of Attachments.
Section 19.2.4, "How to Delete the Business Section added describing how to delete a business object and its
Object" Attachments.
Section 19.5, "Working with Attachments Section added that describes how to add new Attachment types
Programmatically" programmatically; specifically, the TMURI (ManagedURL)
type.
Chapter 21, "Working with Localization
Formatting"
Section 21.3.1.1, "Formatting Decimal Numbers" Added section specific to formatting decimal values.
Section 21.3.1.2, "Formatting Integer Numbers" Added section specific to formatting integer values.
Section 21.3.1.3, "Formatting ID Numbers" Added section specific to formatting ID values.
Section 21.3.1.4, "How to Format Numbers in Added section on how to use af:commandLink and af:goLink to
Hyperlinks" format numbers in hyperlinks in Oracle Fusion
applications.
Section 21.3.1.5, "How to Format Percentage Added section on how to present percentage values in a
Values" locale-sensitive format in Oracle Fusion applications.
Section 21.4, "Formatting Date and Timestamp Added section devoted to formatting date and timestamp
Values" values.
Section 21.7, "Implementing Bi-directional Added section describing how to implement support for
Support" bi-directional languages, such as Arabic and Hebrew, in Oracle
Fusion applications.
Section 21.8, "Supporting Mnemonic Keys" Added section describing how to implement mnemonic, or soft,
keys in Oracle Fusion applications.
Section 21.9, "Implementing Localization Added section on how to implement localization formatting in
Formatting in ADF Desktop Integration" Excel spreadsheets in ADF Desktop Integration in Oracle
Fusion applications.
Section 21.10, "Implementing Localization Added section on how to implement localization formatting in
Formatting in Oracle BI Publisher Reports" Oracle BI Publisher reports in Oracle Fusion applications.
Section 21.11, "Implementing Localization Added section on how to implement localization formatting in
Formatting in ADF Data Visualization Data Visualization Tools in Oracle Fusion applications.
Components"
Chapter 24, "Using Extensible Flexfields"
Section 24.3, "Creating Extensible Flexfield Data Section modified to include the CATEGORY_CODE column
Tables" and to remove nonrequired columns from the extension table
specifications.
Section 24.8.2, "How to Customize the Runtime Section added that describes how to customize the extensible
User Interface Modeler for Extensible Flexfields" flexfield runtime user interface modeler.
lvi
Sections Changes Made
Chapter 26, "Testing and Deploying Flexfields"
Section 26.3, "Using the WLST Flexfield Section revised to include new deleteFlexPatchingLabels
Commands" WLST command for inquiring about or deleting MDS flexfield
patching labels.
Chapter 28, "Creating Searchable Objects"
Section 28.4.4.4, "Defining a Facet to Use a Child Section added describing new feature of being able to search on
View Object Attribute" a child View Object.
Section 28.2.10.1, "Checking for Stored Attribute Section added describing how ECSF now checks for stored
Conflicts" attribute conflicts when defining a search.
Section 28.2.6.1, "Making View Object Attributes Section revised with expanded information of Crawl Date
Searchable" Column in Table 27-1 Searchable Attribute Properties to explain
that ECSF will pick the most recent Crawl Date column value to
use as the LastModifiedDate value.
Chapter 64, "Oracle Enterprise Scheduler New chapter explains how Oracle Enterprise Scheduler Security
Security" features provide access control for Oracle Enterprise Scheduler
resources and application identity propagation for job
execution.
lvii
lviii
Part I
Part I Getting Started Building Your Oracle
Fusion Applications
This part of the Developer's Guide discusses how to set up and configure your
development environment to build your Oracle Fusion Applications using Oracle
JDeveloper.
Getting Started with Oracle Fusion Applications describes how to design and build your
Oracle Fusion Applications using the Oracle standards and guidelines.
Setting Up Your Development Environment describes how to configure and test your 11g
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 Oracle Integrated WebLogic
Server and Oracle Standalone WebLogic Server, and the basic steps for setting up your
service-oriented architecture (SOA) development environment.
Setting Up Your JDeveloper Workspace and Projects describes how to create an application
so that the system automatically creates your Model and user interface projects. Also
included are instructions about how to set up your projects including manually
adding the Applications Core library to the data model project and the Applications Core
Tag library to the user interface project.
This part contains the following chapters:
■ Chapter 1, "Getting Started with Oracle Fusion Applications"
■ Chapter 2, "Setting Up Your Development Environment"
■ Chapter 3, "Setting Up Your JDeveloper Workspace and Projects"
1
Getting Started with Oracle Fusion
1
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.1, "Overview of Fusion Technologies"
■ Section 1.2, "Using Oracle ADF Functional Patterns and Best Practices"
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:
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.
■ Oracle Essbase: This is used to manage multi-dimensional data. Essbase provides
adaptable data storage mechanisms for specific types of analytic and performance
management applications. It is used to manage multi-dimensional data.
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).
In addition to customization, WebCenter provides many other services. For more
information about WebCenter technologies, see the Oracle Fusion Middleware
Developer's Guide for Oracle WebCenter Portal.
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 Scheduler Service: Oracle Enterprise Scheduler Service
provides the ability to run different Job Types, including: Java, PL/SQL, and
Binary Scripts, distributed across the nodes in an OracleAS Cluster. Oracle
Enterprise Scheduler Service runs these jobs securely, with high availability and
scalability, with load balancing and provides monitoring and management
through Oracle Enterprise Manager Fusion Middleware Control.
For more information about Oracle Enterprise Scheduler Service, see the Oracle
Fusion Middleware Developer's Guide for Oracle Enterprise Scheduling Service.
■ 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 27, "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.
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.1, "Introduction to the Development Environment"
■ Section 2.2, "Setting Up the JDeveloper-based Personal Environment"
■ Section 2.3, "Setting Up the Personal Environment for Standalone WebLogic
Server"
■ Section 2.4, "Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion
Middleware Control"
■ Section 2.5, "Using Deployment Profiles Settings"
■ Section 2.6, "Configuring the Oracle Enterprise Scheduler (ESS)"
■ Section 2.7, "Testing Your Installation"
■ Section 2.8, "Using Best Practices for Setting Up the Development Environment"
■ Section 2.9, "Configuring Hierarchy Providers for Approval Management (AMX)"
laptops. Like the exploded EAR directories of the deployed applications in the
Middleware home, these stores from the shared environment are not intended to
be modified by the personal environments that are using them.
Properties and features of the shared environment include:
■ 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 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.
For more information about provisioning an environment, see "Provisioning a New
Applications Environment" in the Oracle Fusion Applications Installation Guide, and the
Oracle Fusion Applications release notes.
2.1.1.1.1 How to Create the OWSM_MDS Schema This section provides detailed snapshots
on how to create the OWSM_MDS schema using the Oracle Fusion Applications
Repository Creation Utility.
In a production environment, the OWSM_MDS schema is in the IDM database. The
IDM is typically locked down so information such as schema passwords are not
handed out. But, to configure the domain, the schema and the password are required
to set up the mds-owsm datasource. The starter transaction database correctly does not
contain the OWSM_MDS schema. This is correct and the base template to create the
starter transaction database should not be changed to include it. To avoid widely
disseminating the schema password of the IDM database, an extra MDS should be
added to the development's transaction database using the Oracle Fusion Applications
Repository Creation Utility with a prefix of OWSM.
You do not have to do anything else apart from adding this schema. The schema will
be correctly populated when your domain starts, if it does not already contain the
correct data.
There may be a number of Oracle Fusion Applications Repository Creation Utilities
available. To provision Oracle Fusion Applications, you will have created an installer
repository. In this repository, you will see the following:
installers/
apps_rcu/
linux/
rcuHome_fusionapps_linux.zip
windows/
rcuHome_fusionapps_win.zip
biapps_rcu/
fmw_rcu/
Copy the appropriate .zip file to your system from the installers/apps_rcu directory.
Once 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 2–1.
Select Create and click Next to display the Database Connection Details dialog, shown
in Figure 2–2.
Enter your database connection details and click Next to display the Checking Global
Prerequisites dialog, shown in Figure 2–3.
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 2–7.
Click Close.
The OWSM_MDS schema now can be used to configure the mds_owsm datasource in
the domain.
If you are using your own workstation, you probably have a process called SCIM
running. This process may prevent you from entering a password in the Oracle Fusion
Domain wizard or anywhere a JPasswordField occurs. You can remove SCIM from your
system by executing this command.
sudo yum remove scim
You also 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: The directions in this section assume that you are installing
from the disk.
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.5.3) disk.
For Windows, you can use the jdevstudio11115install.exe installer. For Linux, you can
use the jdevstudio11115install.bin installer. If you decide to use the generic
jdevstudio11115install.jar installer, you must first install JDK 6 Update 24 from the
Oracle Technical Network and then install JDeveloper using the generic installer.
The installation will let you specify the directory into which to install JDeveloper. 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.5.3) disk. See 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 (Oracle Fusion Applications Edition).
/path/to/customization/bundles/directory1:/path/to/customization/bundles/directory
2
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. You will have to get one or more
paths from an administrator. The administrator can use these steps to locate the JAR
files:
■ 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 to find it.
bash commands:
export PATH=/path/to/python/bin:$PATH
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
-XX:CompileThreshold=8000"
Note: For Windows, memory arguments should be set in the jdev.conf file. See
Table 2–1 for how to set them. Example: -Xms256m -Xmx1024m
-XX:MaxPermSize=512m -XX:CompileThreshold=8000
3. Change directory to $MW_HOME/jdeveloper/jdev/bin.
4. Open the jdev.conf file in a text editor and add this line:
AddVMOption -Djdev.wlst.env.vars=HOME,JDEV_USER_HOME
5. Start JDeveloper.
jdev &
If you require more details about the JDeveloper startup, you can set the
VERBOSE environment variable. If you are using csh, the command is setenv
VERBOSE TRUE. If you are using bash, the command is export VERBOSE=TRUE.
When prompted, select the Default Role, as shown in Figure 2–11.
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.
Table 2–2 provides a brief explanation of the available roles.
Click OK. As JDeveloper loads, the Migrate User Settings prompt may display. If
it does and you are not sure whether or not to migrate settings, you should click
No.
Ignore any error messages that might be displayed when you click the Test
Proxy button.
d. Click OK. The Source dialog, shown in Figure 2–13, displays.
g. Enter a name for the new Update Center, such as Oracle Fusion Applications
Update Center.
h. Click Browse to locate and select the fusion_apps_update_center.xml file, as
shown in Figure 2–15. The location of this file in on the Oracle Fusion
Applications Companion 11g (11.1.1.5.3) disk in the fusion_apps_extensions
directory, or on a shared directory provided by the administrator.
i. Click Open.
j. Click OK.
k. Select the newly-defined Update Center, as shown in Figure 2–16.
When the download finishes, the Summary dialog, similar to that shown in
Figure 2–19, displays automatically.
o. Click Finish. If you are using JDeveloper on a Linux system, the Confirm Exit
prompt shown in Figure 2–20 displays.
Once 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 administrator will use the Oracle Fusion Applications Repository Creation
Utility to create the MDS schema, described in Section 2.1.1.1.1, "How to Create 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.
Store. These values are captured in the fusion_apps_wls.properties file and the
passwords are stored in an encrypted form using the credential store. Both the fusion_
apps_wls.properties file and the cwallet.sso file, which is the credential store, are
created in the o.jdevimpl.rescat2 sub-folder under the $JDEV_USER_
HOME/system11.1.1.5.xx.yy.zz folder. The administrator can distribute the entire
o.jdevimpl.rescat2 sub-folder to the development team. The developers can install
JDeveloper and install the bundles. The developers then can copy the entire
o.jdevimpl.rescat2 sub-folder under their own $JDEV_USER_
HOME/system11.1.1.5.xx.yy.zz folder. This way, the administrator can enforce
uniformity and the developers will not have to go through the wizard to create the
properties file.
Now, if developers need to use their own SOAINFRA or MDS_SOA schemas, they can
manually launch the wizard and provide connect strings specifically for those
schemas.
The properties that can be captured in the wizard are shown in Table 2–3. The
properties are defined under section headers that are surrounded by [square brackets],
for example:
[domain]
domainType=adminall
Table 2–3 (Cont.) Properties to be Captured in the Oracle Fusion Domain Wizard
Standalone/
Property Name Integrated Required Default Comments
listenPort Standalone Yes Default based on
Standalone or
Integrated.
Default is 7011
for Standalone
Weblogic Server.
soaPort Standalone Yes, only Needed for adminsoa and adminall.
when
As this is on their own machines,
domainType
developers choose the values.
is
adminsoa/ad
minall.
essPort Standalone Yes, only As this is on their own machines,
when developers choose the values.
domainType
is adminess.
wlName Both Yes weblogic
wlPassword Both Yes weblogic1
ldapHost Both Yes This is a string value similar to:
ldaphostname.yourcompany.com.
ldapPort Both Yes Example: 3060
ldapUser Both Yes Example: cn=wlsproxyuser
ldapPass Both Yes Example: welcome1
Important: In the UI, the password will
display as the normal ******* mask. The
password is not saved in the fusion_
apps_wls.properties file. It is
encrypted and saved in the
cwallet.sso file maintained in the
system11.1.1.xx.yy.zz/o.jdevimpl.r
escat2/ directory.
ldapUserDN 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
opssHost Standalone No 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).
opssPort Standalone No Example: 3061
opssUser Standalone No Example: cn=wlsproxyuser
Table 2–3 (Cont.) Properties to be Captured in the Oracle Fusion Domain Wizard
Standalone/
Property Name Integrated Required Default Comments
opssPass Standalone No Example: welcome2
Important: In the UI, the password will
display as the standard ***** mask. The
password is not saved in the fusion_
apps_wls.properties file. It is
encrypted and saved in the
cwallet.sso file maintained in the
system11.1.1.xx.yy.zz/o.jdevimpl.r
escat2/ directory.
opssSSLEnabled Standalone No false true or false
jpsRootContext Standalone No Text field
Example: cn=FADevPolicies
biHostPort Standalone No Oracle Business Intelligence will only
be supported in the Standalone
WebLogic Server environment.
Specify a port to point to the BI server.
This generates a BIP configuration file
that gets added to the domain home.
The template then adds the location of
the configuration file as a system
property to be set when Oracle
WebLogic Server is started.
familyName Both Yes Family names are: COMMON, IC,
HCM, FIN, PRC, PRJ, SCM, and CRM.
fusionDb - connect Both Yes JDBC connect string.
string
Note: This is split into sub-fields:
■ fusionDbUser
■ fusionDbPassword
■ fusionDbHost
■ fusionDbPort
■ fusionDbSid
This is applicable to these schemas:
■ activityDb
■ apmDb
■ AppMasterDb
■ essMdsDb
■ fusionAq
■ fusionEdn
■ fusionMds
■ oraessDb
■ orasdpmDb
■ owsmMdsDb
■ portletDb
■ soadatasrcDb
■ soaMdsDb
■ wcDb
Table 2–3 (Cont.) Properties to be Captured in the Oracle Fusion Domain Wizard
Standalone/
Property Name Integrated Required Default Comments
activityDbUser - Both No You can connect to the fusionDB
connect string database as fusion_activities. Your
system administrator will provide the
connection details and schema
password to be used.
apmDbUser - connect Both No You can connect to the fusionDB
string database as fusion_apm. Your system
administrator will provide the
connection details and schema
password to be used.
AppMasterDbUser - Both No You can connect to the fusionDB
connect string database as fusion_runtime. Your
system administrator will provide the
connection details and schema
password to be used.
essMdsDbUser - connect Both No You can connect to the fusionDB
string database as fusion_mds_ess. Your
system administrator will provide the
connection details and schema
password to be used.
fusionAqUser - connect Both Yes, but the You can connect to the fusionDB
string database database as fusion_aq. Your system
connection is administrator will provide the
the same as connection details and schema
for fusionDb. password to be used.
fusionEdnUser - Both Yes, but the Note: CRM will be replaced with the
connect string database familyName that is passed in.
connection is
You can connect to the fusionDB
the same as
database as crm_fusion_soainfra.
for fusionDb.
Your system administrator will provide
the connection details and schema
password to be used.
fusionMdsUser - Both Yes, but the You can connect to the fusionDB
connect string database database as fusion_mds. Your system
connection is administrator will provide the
the same as connection details and schema
for fusionDb. password to be used.
oraEssDbUser - connect Both No You can connect to the fusionDB
string database as fusion_ora_ess. Your
system administrator will provide the
connection details and schema
password to be used.
orasdpmDbUser - Both No You can connect to the fusionDB
connect string database as fusion_orasdpm. Your
system administrator will provide the
connection details and schema
password to be used.
owsmMdsDbUser - Both No You can connect to the fusionDB
connect string database as owsm_mds. Your system
administrator will provide the
connection details and schema
password to be used.
Table 2–3 (Cont.) Properties to be Captured in the Oracle Fusion Domain Wizard
Standalone/
Property Name Integrated Required Default Comments
portletDbUser - Both No You can connect to the fusionDB
connect string database as fusion_portlet. Your
system administrator will provide the
connection details and schema
password to be used.
soadatasrcDbUser - Both No Family name used in prefix.
connect string
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.
soaMdsDbUser - connect Both No Family name used in prefix.
string
You can connect to the fusionDB
database as crm_fusion_mds_soa. Your
system administrator will provide the
connection details and schema
password to be used.
wcDbUser - connect Both No You can connect to the fusionDB
string database as fusion_webcenter. Your
system administrator will provide the
connection details and schema
password to be used.
Click Yes to launch the wizard and display the Usage page, as shown in Figure 2–26.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
■ WebLogic User Name
This value defaults to weblogic. Change it if necessary.
■ WebLogic Password / Confirm Password
The password requires at least one numeral. It defaults to weblogic1.You can
change it if necessary. Note that the password is not stored in the fusion_apps_
wls.properties file. It is encrypted and stored in the cwallet.sso file.
■ Fusion Family Name
The default is Common to signify the common domain. If necessary, from the drop
down list, select the Fusion Family Name, such as Customer Relationship
Management or Financials.
■ Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
Click Next to display the Database dialog, shown in Figure 2–28
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:
■ If a credential that is listed in the Database dialog does not have
the same password as the corresponding schema name itself, you
must provide the password using the fields to the right of the
credential list. For example, if the password of the Activities
credential happens to be fooBar812 instead of fusion_activities
(which is the schema name), you should select the Activities
credential from the list and provide the password for the fusion_
activities schema as fooBar812 in the Password field. The
Username field will contain fusion_activities. You do not have
to provide anything in the Connect String field for this schema, as
it will be in the same database.
■ If the credential that is listed in the Database dialog has to be
mapped to a schema other than the default schema, you should
provide the appropriate schema name and password using the
fields to the right of the credential list. For example, the OWSM MDS
credential is mapped to the owsm_mds schema by default. But, if it
has to be mapped to the hcm_fusion_mds_soa schema, you can
choose the OWSM MDS credential from the list and then enter hcm_
fusion_mds_soa in the Username field and specify the password
in the Password field on the right. Once again, the Connect String
field can be left blank if the schema is in the same database.
■ If each of the credentials in the Database dialog have the same
password as the corresponding schema name, you only need to
enter values in the Fusion Database field in the host:port:SID
format.
■ Make sure you have entered valid database connection details or
your WebLogic Servers will not start. The ApplicationDB data
source that is configured using these values is configured to
support global transaction type Logging Last Resource. If the
database is not available when you try to start WebLogic Server, it
will fail with a message similar to:
Server failed. Reason: JTAExceptions:119002A logging last
resource failed during initialization. The server cannot boot
unless all configured logging last resources (LLRs) initialize
A number of credentials are supplied with Oracle Fusion Applications and are
included in the fusion_apps_wls.properties file. When you click a credential, the
three fields to the right will display the default values. The Password field will
remain blank because any passwords are encrypted and stored in the cwallet.sso
file.
If OWSM_MDS is selected, and the administrator has chosen to open up the IDM
database in which the schema already exists, you will need to enter all the
necessary information in this dialog. However, if the administrator has created the
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.1.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.
Click Next to display the Security dialog, shown in Figure 2–29.
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 2–30.
– 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.
Click Next to display the Finish dialog shown in Figure 2–31.
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 2–32, 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.
■ Domain Type
This is the type of domain you wish to create. It can be:
– adfess: Configured for Oracle ADF and Oracle Enterprise Scheduler
technologies.
– adminsoa: Creates an Oracle SOA Suite domain with an AdminServer with
Oracle Enterprise Manager Fusion Middleware Control deployed, and a
managed server, named soa_server1, where SOA composites are deployed
and run.
– adminall: A combination of standalone and Oracle SOA Suite, AdminServer
for Oracle ADF/Oracle Enterprise Scheduler and managed server soa_server1
for Oracle SOA Suite.
– 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.
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:
■ If a credential that is listed in the Database dialog does not have
the same password as the corresponding schema name itself, you
must provide the password using the fields to the right of the
credential list. For example, if the password of the Activities
credential happens to be fooBar812 instead of fusion_activities
(which is the schema name), you should select the Activities
credential from the list and provide the password for the fusion_
activities schema as fooBar812 in the Password field. The
Username field will contain fusion_activities. You do not have
to provide anything in the Connect String field for this schema, as
it will be in the same database.
■ If the credential that is listed in the Database dialog has to be
mapped to a schema other than the default schema, you should
provide the appropriate schema name and password using the
fields to the right of the credential list. For example, the OWSM MDS
credential is mapped to the owsm_mds schema by default. But, if it
has to be mapped to the hcm_fusion_mds_soa schema, you can
choose the OWSM MDS credential from the list and then enter hcm_
fusion_mds_soa in the Username field and specify the password
in the Password field on the right. Once again, the Connect String
field can be left blank if the schema is in the same database.
■ If each of the credentials in the Database dialog have the same
password as the corresponding schema name, you only need to
enter values in the Fusion Database field in the host:port:SID
format.
■ Make sure you have entered valid database connection details or
your WebLogic Servers will not start. The ApplicationDB data
source that is configured using these values is configured to
support global transaction type Logging Last Resource. If the
database is not available when you try to start WebLogic Server, it
will fail with a message similar to:
Server failed. Reason: JTAExceptions:119002A logging last
resource failed during initialization. The server cannot boot
unless all configured logging last resources (LLRs) initialize
A number of credentials are supplied with Oracle Fusion Applications and are
included in the fusion_apps_wls.properties file. When you click a credential, the
three fields to the right will display the default values. The Password field will
remain blank because any passwords are encrypted and stored in the cwallet.sso
file.
If OWSM_MDS is selected, and the administrator has chosen to open up the IDM
database in which the schema already exists, you will need to enter all the
necessary information in this dialog. However, if the administrator has created the
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.1.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.
Click Next to display the Security dialog shown in Figure 2–34.
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 2–35.
– 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.
– 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.
– JPS Root Context
Enter the JPS Root Distinguished Name, which is the top-level (outermost)
node that contains OPSS data in an LDAP directory, such as cn=FAPolicies.
Click Next to display the Finish dialog shown in Figure 2–37.
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 2–40.
If you still do not see the Process Exited message when you terminate Integrated
WebLogic Server, you will have to manually kill the process.
2. Kill the process. For instance, if the process is 15846, you would execute this
command:
kill -9 15846
■ Configure the domain with the data sources and the Identity Store that are
available in the shared environment.
■ Configure the domain to either point to the LDAP-based Policy Store in the shared
environment or a local XML-based Policy Store.
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. As a result, 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 once 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 has 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.
Notes:
■ The installer repository on Windows must be a local or a mapped
drive.
■ Windows and Linux operating systems must be 64-bit.
This install also allows Oracle SOA Suite developers to create their domains without
extra installs or steps.
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.
bash commands:
export MW_HOME=/path_to/FAStandalone_MW_HOME.
export JDEV_MW_HOME=/path/to/JDeveloper/install_directory
export ANT_HOME=$JDEV_MW_HOME/jdeveloper/ant
■ mkdir /path_to/FAStandaloneWork
■ chmod +x $JDEV_MW_HOME/jdeveloper/fadev/bin/*.py
■ Create a lightweight MW_HOME directory by running the
FADevInstallMwHome.py script. This script is installed when you install the
Fusion Apps Development Environment extension bundle, described in Step 6
of Section 2.2.1.5, "Setting Up the JDeveloper-based Development
Environment." 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/FADevInstallMwHome.py
-m $MW_HOME
-i /path/to/installer_files
-w /path_to/FAStandaloneWork -v
Windows system
5. 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.5.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 2–2 will be
displayed.
When you stop the server, use the same xterm that was used to create the domain
and execute these commands:
ps
kill -9 <pid_of_startWebLogic.sh> <pid_of_java>
If you had started the ManagedServer, you should kill it, too.
■ Remove the domain
You may want to start over by removing the domain. Use the same xterm that was
used to create the Standalone WebLogic Server domain and execute these
commands:
rm -rf /path/to/FAStandaloneDomain
rm -rf /path/to/FAStandaloneWork/*
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.
1. Set up your environment to use the Oracle SOA Suite and Java Apps Logger.
2. Update the oracle.soa.bpel.jar, file as shown in Example 2–3.
2. Drop the Repository, as shown in Example 2–7. 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 2–6.
3. Recreate the Repository, as shown in Example 2–8. Enter the SYS password when
prompted.
Note: 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.
When creating an Oracle ADF library deployment profile, the default is to include all
connection details for every connection in the connections.xml, which is a workspace
level file. Subsequently, when the Oracle ADF library is attached to a project, all of the
connections are merged with the connections.xml for that project's workspace. This
causes a proliferation of the connections across Oracle Fusion Applications. While the
propagation of the connections is desirable, it is propagating much more than is really
needed.
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.
Important: The ESS and Fusion schema must be located in the same
database and must be linked to each other.
Example 2–9 Sample Showing Correctly-Configured Oracle ESS Database and Schema
Information, and ESS-related Settings
[domain]
domainType=adminessadf
domainName=fusion_domain
listenPort=7011
soaPort=7012
wlName=weblogic
wlPassword=weblogic1
useCentralLdap=no
...
[wlsconfig]
fusionDbHost=fpp-ta02.us.oracle.com
fusionDbPort=1522
fusionDbSid=fppta02
...
# leave oraessDbHost, oraessDbPort, oraessDbSid blank if using fusion database
oraessDbHost=
oraessDbPort=
oraessDbSid=
oraessDbUser=oraess_d8b2
oraessDbPassword=oraess_d8b2
#
essMdsDbHost=
essMdsDbPort=
essMdsDbSid=
essMdsDbUser=fusion_mds_ess
essMdsDbPassword=fusion_mds_ess
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."
Example 2–10 Configuring Oracle Enterprise Scheduler Schema Using the Oracle
Fusion Applications Repository Creation Utility Schema
cd $RCU_SHIPHOMELOC/bin
DB_HOST=localhost
DB_PORT=1521
DB_SID=XE
CONNECT_STRING=$DB_HOST:$DB_PORT:$DB_SID
Note: 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
You can enter a new name for your data model project or you can keep the default
name Model.
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 2–44.
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 2–45.
6. 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 2–46.
Figure 2–46 Configuring Java Settings for the Oracle ADF User Interface Project
a. Filter Types: Select only Tables to narrow your search for schema objects.
b. Filter Name: Enter a filter, such as %DEMO_EMP% to narrow your search to
tables.
c. Query: Click this button to perform your search.
d. Choose the required object, such as FND_DEMO_EMP and click > to shuttle it
over to the Selected column.
e. Click Next to go to the next step in the wizard.
13. Choose the required entity object located in the Available column and click > to
shuttle it over to the Selected column. See Figure 2–48.
Figure 2–48 Create Business Components from Tables — Updatable View Objects
14. Click Finish to create your updateable view object and to close the Business
Objects wizard.
15. 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. Go to the Application Navigator and select your application module.
Right-click and select Configurations from the menu.
b. Choose the configuration <AM Name>Local, then choose Edit.
c. Change the Connection Type to JDBC DataSource and Datasource Name to
java:comp/env/jdbc/ApplicationDBDS. Click OK.
16. 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 2–49.
If your installation is set up correctly, a dialog similar to that shown in Figure 2–50
displays. If an error message displays, you will need to re-check that the previous
steps have been performed correctly.
17. Choose Application Navigator > ViewController. Right-click and select New
from the menu to open the New Gallery.
18. Choose the Web Tier > JSF category. Select the JSF Page item and click OK to
open the Create JSF Page dialog.
19. Complete the following:
■ File Name: Enter Setup.jsp
■ Select to create jspx file.
■ Click OK.
20. Go to the Data Controls panel and drag the collection onto the open Setup.jspx
window. See Figure 2–52.
21. Select to create Forms > ADF read-only from the context menu that displays. See
Figure 2–53.
22. 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 2–54.
23. Click the Run button located on the toolbar to run your page.
Note: 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.
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.
The heap monitor shows the current size of the heap; not necessarily the maximum
size. The heap is originally 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.
If you delete the DefaultDomain directory from under the system directory, the next
time you start Integrated WebLogic Server, it will be recreated from the latest fusion_
apps_wls.properties.
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,
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>
to redeploy the Oracle ADF library and refresh the Oracle ADF library dependencies
for your user interface project. The same applies to one model project referencing from
another model project.
If you are developing or debugging code in a data model project while running the
referencing user interface project to test it, it may be easier to add the model project as
a build output dependency, so you do not have to go through the cycle of redeploying
the Oracle ADF library or refreshing Oracle ADF library references each time you
make a change.
Note: Integration with Oracle HCM is native. That is, you provide
the WSDL URL for each hierarchy provider.
allows you to retrieve the display names of a list of positions for a particular
language.
The sample Identity Service Configuration XML code shown in Example 2–12 specifies
a service extension, HCMIdentityServiceExtention, for JpsProvider. It then specifies
the providers in the service extension.
<serviceProvider type="jobLevelHierarchyProvider"
classname="oracle.bpel.services.identity.hierarchy.providers.hcm.HCMHierarchyProvider">
<initializationParameter name="wsdlUrl"
value="http://<host>/HierarchyProviderService?WSDL"/>
</serviceProvider>
</serviceExtension>
</serviceExtensions>
</ISConfiguration>
Projects
This chapter describes how to set up your JDeveloper 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.1, "Using Technology Scopes"
■ Section 3.2, "Provisioning the Workspace"
■ Section 3.3, "Adding the Applications Core Library to Your Data Model Project"
■ 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 a Database Connection"
■ Section 3.7, "Adding the Search Navigation Tab to the Overview Editor for Oracle
Enterprise Crawl and Search Framework (ECSF)"
■ Section 3.8, "Overriding the Default Resource Bundle"
■ Section 3.9, "Deploying Oracle SOA Suite"
■ Section 3.10, "Implementing Oracle Enterprise Scheduler Service Workspace and
Deployment"
■ Section 3.11, "Implementing Oracle Application Development Framework UI
Workspace and Projects"
3.3 Adding the Applications Core Library to Your Data Model Project
Use these directions to add the Applications Core and Applications Core (Attachments
Model) libraries to the data model project. The default name, provided by JDeveloper,
for this project is Model.
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 3–2.
Note: Even if you are only using the user interface project you must
still initialize the data model project as they are dependent on each
other.
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.
For example, a Human Resources application can register setup activities such as
"Create Employees" and "Manage Employee Tree Structure." See the Oracle Fusion
Applications Information Technology Management, Implement Applications 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.7, "Integrating Attachments Task Flows into Oracle Fusion Functional
Setup Manager"
■ Section 26.5, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup
Manager"
■ Section 55.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.
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 3–4.
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 28, "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.
3.7.2 What Happens When You Add the Search Navigation Tab to the Overview Editor
Once 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 28–3.
Use the Search navigation tab to configure the search-related properties.
For more information, see Chapter 28, "Creating Searchable Objects."
3.10.2.1.1 How to Enable Your 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 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 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. Prepare the Workspace EAR deployment profile.
a. Open your Oracle Enterprise Scheduler Service Workspace in JDeveloper.
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. Leave the remaining values at their defaults and click OK.
e. Select the Contributors heading beneath the new MAR Group file group and
click Add.
f. Browse to find the 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. Prepare each metadata project JAR(MAR) deployment profile.
These steps will need to be repeated if you have multiple projects containing
Oracle Enterprise Scheduler Service metadata.
a. Select the Oracle Enterprise Scheduler Service metadata containing project and
open the project properties.
b. Select the Deployment panel and click New.
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
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.
h. Click OK.
i. Deploy as JAR and verify.
3. Complete the Workspace EAR deployment profile.
These steps will need to be repeated if you have multiple EAR deployments for
test or development purposes.
a. Open the Application Properties.
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. Select the Application Assembly heading and de-select the workspace-level
MAR profile.
e. Click OK.
f. Select the Profile Dependencies in the left-hand side.
g. Check the boxes for each of the new JAR-based MAR profiles.
h. Click OK.
i. Deploy as EAR and verify.
For deployment from JDeveloper, you will need to create an Application Server
connection in the JDeveloper resources palette before or as part of the deployment
activity using the New Connection feature. Once your Oracle Enterprise Scheduler
Service application is ready for deployment, including all requisite project and
application-level profiles, you can initiate deployment by following these steps:
1. Click Deploy > <ear profile name> from the Application menu.
2. Choose Deploy to Application Server and click Next.
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. Choose the appropriate managed server and click Next.
7. Click Finish to begin deployment.
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.
Once 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
Scheduling Service.
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 Path: ADFm Sources dialog, as shown in Figure 3–7.
Figure 3–7 Project Properties — Project Source Paths: ADFm Sources Dialog
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 Path: Web Application dialog, as shown in Figure 3–8.
Figure 3–8 Project Properties — Project Source Paths: Web Application Dialog
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 3–9.
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. Choose the Deployment category to display the Deployment dialog.
8. Select New to open the Create Deployment Profile dialog, as shown in
Figure 3–10.
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.
11. Choose the JSP Tag Libraries category to display the JSP Tag Libraries dialog, as
shown in Figure 3–11.
Verify that you have the following tag libraries listed under the Distributed
libraries folder:
■ Applications Core (ViewController) 11.1.1.0.0
■ Trinidad HTML Components 1.2
Note: You may have to include additional tag libraries for other
features, such as Data Visualization Tools (DVT) and WebCenter. For
more information about adding tag libraries to your user interface
project, see Section 3.4, "Adding the Applications Core Tag Library to
Your User Interface Project.".
12. Choose the Libraries and Classpath category to display the Libraries and
Classpath dialog, as shown in Figure 3–12.
Verify that the libraries listed in Figure 3–12 have been attached to your user
interface project. As with tag libraries, you may have to add additional libraries.
13. Choose the Resource Bundle category to display the Resource Bundle dialog, as
shown in Figure 3–13.
Note: The default settings will be correct when you start JDeveloper
using the Oracle Fusion Applications Developer role.
14. Choose the Technology Scope category to display the Technology Scope dialog, as
shown in Figure 3–14.
Verify that the technology scopes that are selected in Figure 3–14 are selected for
your project.
Note: This section assumes that you are deploying a web project to
Standalone WebLogic Server. Creating deployment profiles is not
necessary if you are running the project in Integrated WebLogic Server
from within JDeveloper. In this case, JDeveloper, behind the scenes,
creates an in-memory deployment profile.
For other deployment options, see "Deployment Techniques for
Development or Production Environments" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
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 Oracle 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.
Oracle 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.
Unique ID generation provides a mechanism to manage the key-generation process
and to ensure that it runs without interruption. The process efficiently generates
distinct sets of IDs in different databases for the same table, ensuring that the same key
is never used for two different records created in different systems.
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
Applications product. Using Oracle 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 Trail Reporting 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:
■ Chapter 4, "Getting Started with Business Services"
■ Chapter 5, "Developing Services"
■ Chapter 6, "Defining Defaulting and Derivation Logic"
■ Chapter 7, "Defining and Using Message Dictionary Messages"
■ Chapter 8, "Managing Reference Data with SetIDs"
■ Chapter 9, "Using Fusion Middleware Extensions for Oracle Applications Base
Classes"
■ Chapter 10, "Implementing Lookups"
■ Chapter 11, "Setting Up Document Sequences"
■ Chapter 12, "Implementing Audit Trail Reporting"
4
4Getting Started with Business Services
Note: 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.
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.
Note: You should still provide services for all objects, and double
code the high performance alternatives when necessary.
This chapter describes how customers can develop new business applications using
existing services in the context of new or modified business processes.
This chapter contains the following sections:
■ Section 5.1, "Introduction to Services"
■ Section 5.2, "Designing the Service Interface"
■ Section 5.3, "Developing Services"
■ Section 5.4, "Invoking Services"
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:
■ Programmatic application programming interface (API) calls required by external
customers, cross-pillar integration, or third-party integration.
■ Business Process Execution Language (BPEL) process flows and composite
applications
■ Business-to-business (B2B) integration through standardized documents
■ Foreign UI technologies such as Microsoft .NET framework
■ XML-based reporting
■ Desktop applications such as Excel and Access.
Standard Operations
The primary purpose of standard service operations is to locate a business object and
handle its persistence. This includes storage, manipulation and retrieval of data,
locking, transaction management, business rule validation, and bulk processing. ADF
Business Components auto-generates the following groups of standard service
operations:
■ CRUD (Create, Read, Update, Delete) Operations:
– get<businessObjectName>: get a single business object by primary key.
– create<businessObjectName>: create a single business object.
– update<businessObjectName>: update a single business object.
– delete<businessObjectName>: delete a single business object by primary key.
– merge<businessObjectName>: update a business object if exists, otherwise
create new one.
■ Find Operation:
– find<businessObjectName>: find and return a list of business objects by find
criteria.
■ Bulk Processing Operations:
– process<businessObjectName>: process a list of business objects via a CRUD
command.
– processCS<businessObjectName>: process a list of business objects via a
change summary.
■ Control Hints Operations:
– List<AttrCtrlHints>
– getDfltCtrlHints(String viewName, String localeName): takes the view
object name and a locale and returns the base UI hints for that locale.
This group of operations are mainly used by the ADF Business Components
Service framework for service based entity object and view object support. For
more information about service-based entity objects and view objects, see
Section 5.4.1, "How to Invoke a Synchronous Service."
Custom Operations
Custom service operations encapsulate complex business rules and may coordinate
execution of two or more data-centric operations within one atomic transaction.
– delete requisition
– delete requisition line
– delete requisition distribution
– copy requisition
– get requisition
– cancel
– approve (including all approval states such as approve, reject, and
pre-approve)
– view approval history
■ Operations associated with Purchase Order:
– create
– delete purchase order
– delete purchase order line
– delete purchase order shipment
– delete purchase order distribution
– copy purchase order
– merge
– update (change)
– acknowledge
– get purchase order
– cancel purchase order
– cancel purchase order line
– approve (including all approval states)
– view approval history
– close
Typically, you should include all the standard operations, although the delete
operation should only be included if supported by the business object. If you only
need to delete a child object, then you must have specific delete operations on the child
objects. This is because you are not able to delete a child object using the delete
method on its parent object. For example, deletePurchaseOrder will delete a purchase
order and all of its lines, but won't only delete a specific line or lines.
of the use case that drives the interface, not the fine-grained specifics of one consumer.
A consumer can be seen as a representative of a specific use case, but the provider
should always apply well-measured foresight when defining the interface details.
Creating general purpose APIs from the beginning will:
■ Prevent method explosion as other similar use cases are requested.
■ Increase reuse by multiple use case.
For example:
For GetPersonName() operation: The provider, at a minimum, requires the primary
keys to access a person's name as input. However, the output could be either a
formatted name in a form of a simple String or a complex document representing
Name object. The list of returned attributes must be determined by the consumers'
business requirements. If the first consumer of an interface only requires FirstName
and LastName to be returned, it would be possible to only return these two values.
However, it is likely that a popular service operation such as GetPersonName() will
soon be adopted by more consumers, which will require other attributes of a name. In
this example, it makes sense to include Title, RoyalPrefix, LegalName, and so on into
the first specification of the service interface. This will avoid the creation of a new
interface version in the foreseeable future.
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.
Parent-Child Relationships
For parent-child relationships, you should define two view objects, one for the parent
and one for the child, and then define a view link between them. You must also have
the destination accessor generated so that the service framework is unable to query or
post the child along with the parent.
For composite object, you should create a composite association between the parent
entity object and the child entity object, and base the view link on the association.
However, in cases where composite associations cannot be defined you must add a
custom property, SERVICE_PROCESS_CHILDREN=true, to the entity association or view
link. This allows for the child objects to be processed along with the parent object (in
createXXX, updateXXX, mergeXXX, deleteXXX, and processXXX). Reasons for cases
where composite associations cannot be defined include:
■ A child has multiple parents but the relationship is really composite.
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.
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.
Return Object
The informational messages (and warnings) are reported as part of the return object.
ADF Business Components generates appropriate wrappers as the return objects when
necessary, and the wrappers contain the actual method return as well as the
informational messages. Table 5–1 lists some examples:
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:
■ getXXX returns the original object
■ create, update, mergeXXX, findXXX, and processXXX returns the wrapper object
that contains a list of the original object and a list of information messages
■ deleteXXX returns the informational message
■ Each custom method can be configured individually about whether to return
informational messages
Using SOA
When you invoke an ADF Business Components service from BPEL, you usually use
the asynchronous version unless you are sure the service satisfies the synchronous
invocation condition that was discussed previously.
For more information, see Part VI, "Common Service Use Cases and Design Patterns".
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:
■ Section 6.1, "Understanding Entity Object Defaulting and Derivation Logic"
■ Section 6.2, "Using Groovy Scripting Language"
■ Section 6.3, "Using Oracle ADF Validators and Convertor Hints"
When implementing defaulting or derivation logic, you should also consider the
following factors:
■ Always assign a valid value to an attribute.
You should know what the valid values are and there is no reason why you would
want to assign invalid values. The end users do not set these values and would
have no idea why they would be invalid.
■ Always use initDefaultExpressionAttribute for calculations that cross
containerships. Use initDefault for literal or statically computed values.
■ Instead of writing code in one of the triggering points during validation or the
posting cycle to achieve derivation logic, you can use a method validator or an
expression validator.
When you want the derivation logic to be customizable, the validator approach is
preferable. When using this approach the validation result should always be true
because this is not really a validation logic. You should also make sure that the
attribute avoids an infinite loop due to validation.
■ You can call either setAttribute(setter) or populateAttribute to assign the
default or derived value to an attribute.
When you call setAttribute(setter), the logic in the setter is fired and the
validation logic is also executed. This does not happen when you call
populateAttribute.
In most cases, using populateAttribute is sufficient because you should always
assign a valid value and therefore do not need to fire validation logic. However,
you may want to call the setter if there is additional logic such as cascading
derivation in the setter.
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.
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.
■ Validator - gets the Validator context JboValidatorContext merged with the
Entity on which the validator is applied. This is done so that you can use:
– newValue and oldValue to get to the values being validated
– sourceRow to get to the Entity or ViewRow on which the validator is applied
– All attribute names in the Entity or ViewRow as top-level names
and
source.structureDef.name+" of type "+sourceFullName
Example 6–5 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 6–5 Getting the Old Value of a Transient Entity Object Attribute
index = object.getStructureDef().getAttributeIndexOf("Salary");
Example 6–6 is an example of the WHILE construct as well as calling an accessor (Emp):
variables
{
Double avgSal
kind (where)
{
transientexpression
{
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;
}
}
}
}
}
if (EmpSal == null)
{
return null;
}
if (EmpDeptNum == null)
{
return 0;
}
if (EmpDeptNum > 40)
{
retune 500;
}
]]></TransientExpression>
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".
To access the Expression Editor, click the Edit button located next to the Value text
box.
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
converted by a converter, for example to convert a string of input characters into a
value of some other type such as a date or color.
To validate or convert an input value, you add the input component to the page and
then add a validator or converter to that field. Each validator and converter has some
messages associated with it:
■ Hints to display to the user details of what sort of value they need to enter.
■ Error messages to display if the user enters an invalid value.
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. In JDeveloper, select the af validator tag in the UI page.
2. Open the Property Inspector.
3. Select the message attribute.
4. Select the text resource.
5. Select the Application Messages resource bundle.
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.
Messages
The Error, Warning, Information, and UI String message types are described in detail in
Section 7.2, "Understanding Message Types."
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.
about message components, see Section 7.3.4, "About Message Components." For
information about logging and incident creation, see Section 7.5, "Understanding
Incidents and Diagnostic Logs with Message Dictionary." For information about the
standard log settings and about logging profile options see the "Default System Log
Settings" section in the Oracle Fusion Applications Administrator's Guide.
The valid values for message types are fixed and therefore cannot be customized.
Error Messages
Use the Error message type for messages that alert the user to data inaccuracies when
completing a field, submitting or saving a page, navigating from the page, or when an
application or unknown failure occurs. An error message requires attention or
correction before the user can continue with their task.
Warning Messages
Use the Warning message type for messages that inform users about an application
condition or a situation that might require their decision before they can continue.
Warning messages describe the reason for the warning and potential consequence of
the selected or intended action by users. The warning requires the attention of users,
and a standard question might be posed with the warning, or the warning can take the
form of a statement.
Information Messages
The Information message type is intended for the following types of strings:
■ 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 7–1.
These strings are used to provide a text record about request processing execution,
failures, and so on.
■ 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.
Message Text
Message text is required. This is a brief statement of the operation attempted and the
problem that occurred as a result, 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).
The text appears in bold at the top of the message window region. In addition, the
message text is the only message component displayed in limited real estate UIs, such
as pagers and phones. Therefore, the message text should be clear enough to be
understood alone when used in this context.This is a required field for all message
types.
Message Cause
The message cause text provides for the end user a concise explanation of why the
error occurred. It lists reasons for the failure such as a prerequisite that is not met,
incorrect inputs, an anticipated but incorrect action, and so on. The content in this field
is customizable and the text can contain numerous tokens. The maximum field size is
4000 characters.
The word Cause (in bold) is prefixed automatically to the beginning of the cause text.
This text appears below the user detail, if available. This component is optional and is
only applicable for messages of type Error and Warning. The components Cause and
User Action are mutually required, meaning if you enter one you must enter both.
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
this soft-copy documentation as a PDF file from the Oracle Technology Network at
http://www.oracle.com/technetwork/indexes/documentation/
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 7–1.
Table 7–1 Oracle ADF Exception Classes vs. Message Dictionary Classes
Exception Class Message Dictionary 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 7–2.
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"
Tip: If you need to see the original error message, you can run the
application with the -DAFERROR_MODE=debug parameter, as described
in Section 7.9, "Diagnosing Generic System Error Messages."
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 7–1 shows sample code that raises an ApplcoreException exception.
Example 7–2 shows an example of raising ApplcoreRowValException exception. Use of
the ApplcoreAttrValException exception is shown in Example 7–3. Example 7–4
illustrates how to throw a native JBOException.
// Get the token substituted full user message, in plain text format.
String userText = Message.getUserText("MYAPP", "MY_MESSAGE", tokens);
// Get the token substituted full admin message, in plain text format.
String adminText = Message.getAdminText("MYAPP", "MY_MESSAGE", tokens);
7.7.1 How to Associate Error Messages with Oracle ADF Entity Object Validation Rules
Note: 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.
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.
Note: If the selected message contains tokens, a row for each token is
added into the Error Message Expressions table.
try
{
// Create and execute a plsql statement
String mystmt = "BEGIN MY_PLSQL_PACKAGE.MY_PROCEDURE(); END;";
myStmt.executeUpdate();
An application error occurred. See the incident log for more information.
When you receive these types of errors, you can look at the log file entry to find the
original error message.
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:
■ -DAFERROR_MODE=debug: Causes the original error to be displayed in the UI
■ -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 and the "Introduction to Troubleshooting Using Incidents,
Logs, QuickTrace, and Diagnostic Tests" appendix in the Oracle Fusion Middleware
Administrator's Guide.
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.
2. In the Property Inspector, set the ErrorHandlerClass field to the value shown in
Example 7–11 and Figure 7–4.
Figure 7–4 Setting the Value of the ErrorHandlerClass Field in the Property Inspector
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.1, "Introduction to SetIDs"
■ Section 8.2, "Implementing SetID on Entity Objects"
■ Section 8.3, "Integrating SetID Task Flows into Oracle Fusion Functional Setup
Manager"
SetID Implementation
Once you have completed the development process as discussed in this chapter, and
delivered your application with the ability to use set-enabled reference data,
application implementers and administrators must then be able to define and maintain
reference data sets and set assignments that are appropriate to the organization which
will use the application. They can accomplish these tasks using the Manage Reference
Data Sets and Manage Reference Data Set Assignments applications, respectively.
You make these setup applications available to implementers and administrators by
incorporating their task flows into Oracle Functional Setup Manager. For more
information, see Section 8.3, "Integrating SetID Task Flows into Oracle Fusion
Functional Setup Manager".
For information about how to use the setID setup applications, see the Oracle Fusion
Applications Common Implementation Guide
■ 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 exactly 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".
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:
■ The two default seeded sets, COMMON and ENTERPRISE.
■ Default sets that map to existing transaction data, created as an upgrade to
Applications Unlimited.
■ New sets created by customers, to implement set-enabled reference entities
specific to their organizations.
application that owns the reference entities in that group. Application development
teams are ultimately responsible for defining and delivering reference groups.
Fnd_setid_sets_pkg package
This package contains table handlers for fnd_setid_sets table.
Fnd_setid_assignments package
This package contains table handlers for fnd_setid_assignments table.
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;
■ 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;
After building an entity object for a shared reference entity, you annotate the entity
object.
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:
■ Row Striping (this is the default value)
■ Striping With Common Rows
■ Subscription
When you select the SUBSCRIPTION pattern, the SetID Reference Table
Pattern field appears. Specify the subscription table to use.
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 8–3.
Notes:
■ The attribute you need to use as a determinant might not exist on
the parent record where its value can be retrieved from some
context. In that case, you must create a transient attribute to
represent the determinant, set the SetId Determinant Type
property for it, then override the getter method of the transient
attribute to get the value from wherever it has been stored.
■ Once a SetId Determinant code is defined, you can change the
code in the EO.xml file.
3. For foreign keys that are setID enabled, specify the determinant attribute that
drives each foreign key reference, as shown in Figure 8–5.
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.
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.
2. On the Attributes tab, select the foreign key attribute and add a validation rule.
The Edit Validation Rule page appears, as shown in Figure 8–6.
3. At the top of the page, select a rule type of Key Exists.
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. Click Add to include the attribute pair on the mapping list.
7. Select the Validation Execution tab, as shown in Figure 8–7.
Because the validation should be executed every time the determinant value
changes, it should be specified as a triggering attribute.
Note: The foreign key attributes that were mapped on the Rule
Definition tab are by default added as triggering attributes.
8. In the Triggering Attributes section, select the determinant attribute from the
left-hand list and shuttle it to the right-hand list.
9. Optionally, on the Failure Handling tab, specify a failure error message.
10. Click OK to create the key exists validator.
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
each task flow in Table 8–2.
For more information about task flows, see the Oracle Fusion Applications Common
Implementation Guide.
This chapter describes the Fusion Middleware extensions for Oracle Applications base
classes that extend the features of standard ADF Business Components classes.
The chapter includes the following sections:
■ Section 9.1, "Introduction to Fusion Middleware Extensions for Oracle
Applications Base Classes"
■ Section 9.2, "Using Multi-Language Support Features"
■ Section 9.3, "Using WHO Column Features"
■ Section 9.4, "Using PL/SQL-Based Entities"
■ Section 9.5, "Accessing FND Services"
■ Section 9.6, "Using Unique ID"
■ Section 9.7, "Using Data Security"
■ Section 9.8, "Using Document Sequencing"
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-1
Using Multi-Language Support Features
The base classes provided by Fusion Middleware extensions are the following:
■ OAApplicationModuleImpl
■ OAEntityImpl
■ OAEntityDefImpl
■ OAViewObjectImpl
■ OAViewRowImpl
■ OAViewCriteriaAdapter
They are found in oracle.apps.fnd.applcore.oaext.model.package and extend the
JBO classes with the same name (but without the OA prefix) in
oracle.jbo.server.package.
In Oracle JDeveloper, selecting the Oracle Fusion Applications Developer role
automatically sets the Fusion 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. For more information,
see Chapter 2, "Setting Up Your Development Environment."
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.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-3
Using Multi-Language Support Features
Note: This procedure does not apply to a _VL view. For information
about creating an entity object for a _VL view, see Task 2, "Create an
entity object for a base table".
Task 3 Associate the _VL view and _TL table entity objects
To create the association between the _VL view and _TL table entity objects, perform
the following procedure.
1. Follow the standard association object naming convention that describes the entity
relationships. For example, ItemsToTranslation.
2. In the Structure window, choose the entity object. In this case, it is
ItemsToTranslation.
3. In the Overview window, choose the Relationship option.
4. Designate the association as a Composition Association with a 1:* cardinality, as
shown in Figure 9–3.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-5
Using Multi-Language Support Features
Note: Ensure that the Source Accessor has been created prior to
performing Step 6.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-7
Using Multi-Language Support Features
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 9–5.
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.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-9
Using WHO Column Features
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.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-11
Using PL/SQL-Based Entities
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. Create a callable statement to invoke your PL/SQL method.
8. Validate your attributes. You can do this in either of two places:
■ In your insertRow() or updateRow() methods: Perform your validation in
Java in either of these two methods, or in PL/SQL stored procedures called
from the methods.
■ In your validateEntity() method: If validations are done in a separate
stored procedure in PL/SQL, you can call that stored procedure in this
method.
9.4.3 What Happens with PL/SQL Entities at Design Time and Runtime
The extensions provide the following design time and runtime support:
■ Provides the ability to identify PL/SQL-based entities.
■ Invokes PL/SQL for DML operations.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-13
Using Unique ID
Notes: The database table column data type that corresponds to the
entity attribute requiring a Unique ID must be large enough to hold
the uniquely generated value. Typically, it should be of type
NUMBER(18). NUMBER(15) may not be sufficient to hold the uniquely
generated values.
In addition, Oracle Applications coding standards require that the
entity attribute populated with a Unique ID be of type Long.
Using Fusion Middleware Extensions for Oracle Applications Base Classes 9-15
Using Document Sequencing
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:
■ Section 10.1, "Introduction to Lookups"
■ Section 10.2, "Preparing Entities and Views for Lookups"
■ Section 10.3, "Referencing Lookups"
■ Section 10.4, "Defining Validators for Lookups"
■ Section 10.5, "Annotating Lookup Code Reference Attributes for Set-Enabled
Lookups"
■ Section 10.6, "Integrating Lookups Task Flows into Oracle Fusion Functional Setup
Manager"
Lookups Implementation
Once you have completed the development process as discussed in this chapter, and
delivered your application with the ability to use lookups, application implementers
and administrators must then be able to define and maintain lookups that are
appropriate to the organization that will use the application. They can accomplish
these tasks using the Manage Standard Lookups, Manage Set-Enabled Lookups and
Manage Common Lookups applications.
You make these setup applications available to implementers and administrators by
incorporating their task flows into Oracle Fusion Functional Setup Manager. For more
information, see Section 10.6, "Integrating Lookups Task Flows into Oracle Fusion
Functional Setup Manager".
■ 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".
The FND_LOOKUP_TYPES table defines the lookup types available.
Note: When you register a lookup view application, you set a SET_
ENABLED flag to indicate that the lookup view is set enabled. For this
to be valid, every lookup type within that lookup view must have a
reference group defined. The reference group is part of the lookup
definition, and was defined when the lookup was defined. How that
happens is beyond the scope of this documentation.
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.
Lookup Types
■ Entity Object: LookupTypePEO
■ View Object: LookupTypePVO
■ Base Table/View: FND_LOOKUP_TYPES_VL
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.
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
■ Entity Object: LookupValuePEO
■ View Object: none
■ Base Table/View: FND_LOOKUP_VALUES_VL
(FND) Lookups
■ Entity Object: LookupPEO
■ View Object: LookupPVO
■ Base Table/View: FND_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
■ Entity Object: CommonLookupPEO
■ View Object: CommonLookupPVO
■ Base Table/View: FND_COMMON_LOOKUPS
Note: This view also was used to store lookup codes that were
common to multiple applications, but it now exists only for the
purpose of backward compatibility.
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
■ View Object: SetIdLookupPVO
■ Base Table/View: FND_SETID_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.
User
■ Insertion of new codes is allowed
■ Updating of start date, end date, and enabled fields is allowed
■ Deletion of codes is allowed
■ Updating of tag is allowed
Extensible
■ Deletion of lookup type is not allowed
■ Insertion of new codes is allowed
■ Updating of start date, end date, enabled fields, and tag is allowed only if the code
is not 'seed data'
■ Deletion of codes is allowed only if the code is not 'seed data'
■ Updating of module is not allowed
System
■ Deletion of lookup type is not allowed
■ Insertion of new codes is not allowed
■ Updating of start date, end date, and enabled fields is not allowed
■ Deletion of codes is not allowed
■ Updating of tag is not allowed
■ Updating of module is not allowed
Note: If you are using any of the three central lookup types (FND_
LOOKUPS, FND_COMMON_LOOKUPS, and FND_SETID_
LOOKUPS), you can skip the rest of this section.
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 ...
This script registers required seed data, and must be run on every database
instance.
6. Create ADF Business Components objects for your lookup view.
Each lookup view should have a separate entity object and view object (or PEO
and PVO) for both lookup types and lookup codes, extending from the base entity
To reference lookups:
1. Import the lookups standard view objects into your project and make sure they
can be referenced.
2. Open the entity object for editing.
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.
■ 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".
2. On the Validators tab, add a validation rule for the entity. The Edit Validation
Rule page appears, as shown in Figure 10–1.
3. At the top of the page, select a Rule Type of List.
4. On the Rule Definition tab, select the foreign reference column that is the lookup
code (for example, SalaryCode) as the attribute.
5. Select In as the operator.
Note: The foreign key attributes that were mapped on the Rule
Definition tab are by default added as triggering attributes.
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.
2. Create a new transient lookup type attribute to map to the LookupType attribute
on the reference entity, as shown in Figure 10–3.
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. Select the Validation Execution tab, as shown in Figure 10–5.
Because the validation should be executed every time the determinant value
changes, it should be specified as a triggering attribute.
8. In the Triggering Attributes section, select the determinant attribute from the
left-hand list and shuttle it to the right-hand list.
9. Optionally, on the Failure Handling tab, specify a Failure Message.
10. Click OK to generate the key exists validator for this lookup.
Figure 10–6 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.
■ For a set-enabled lookup type, specify which determinant attribute on the
entity object drives the setID of this lookup reference.
■ For a set-enabled foreign key, you should also specify the setID determinant
attribute that drives the foreign key reference.
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
Functional Setup Manager, using the parameters listed for each task flow in
Table 10–2. 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.
For more information about task flows, see the Oracle Fusion Applications Common
Implementation Guide.
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.1, "Introduction to Document Sequences"
■ Section 11.2, "Defining Document Sequence Categories"
■ Section 11.3, "Assigning a Document Sequence"
■ Section 11.4, "Striping Document Sequence Assignments"
■ Section 11.5, "Defining a Document Sequence Audit Table"
■ Section 11.6, "Enabling Document Sequences in ADF Business Components"
■ Section 11.7, "Managing PL/SQL APIs"
■ 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.
Note: It is recommend that you choose this type only when gapless
numbering is essential, as it may affect the performance of your
system.
/**
* 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_SET_OF_BOOKS_ID (Ledger Id),
* 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.
*
* @param appId Application Id
* @param categoryCode Document Sequence Category Code
* @param sobId Ledger Id to use for this Document Sequence.
* @param methodCode Document sequence Method Code (Automatic ("A"), Manual
("M") or null for both modes).
* @param txnDate Document Transaction Date
* @param seqVal Document Sequence Value to use in Manual Mode
* @param suppressWarn Suppress warning (Y/N/null)
* @param suppressError Suppress Error (valid values are Y/N/null)
* @return Document Sequence Value
* @see #postChanges
*/
public Long getDocSequence(Long appId, String categoryCode, Long sobId, String
methodCode, Timestamp txnDate, Long seqVal, String suppressWarn, String
suppressError)
{...}
/**
* Will validate the entity attribute with a document sequence value to use in
Manual
* 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_SET_OF_BOOKS_ID (Ledger Id),
* 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.
*
* Exception will be raised if document sequence value validation fails.
*
* Override this if you want a different behavior/way of validating the
document sequence.
*
* @param appId Application Id
* @param categoryCode Document Sequence Category Code
* @param sobId Ledger Id to use for this Document Sequence.
* @param methodCode Document sequence Method Code (Automatic ("A"), Manual
("M") or null for both modes).
* @param txnDate Document Transaction Date
* @param seqVal Document Sequence Value in Manual Mode
* @param suppressWarn Suppress warning (Y/N/null)
* @param suppressError Suppress Error (valid values are Y/N/null)
* @see #postChanges
*/
public void validateDocSequence(Long appId, String categoryCode, Long sobId,
String methodCode, Timestamp txnDate, Long seqVal, String suppressWarn, String
suppressError)
{...}
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 11–4 lists the metadata
fields in the Property Inspector window and their descriptions.
('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
if (ret <> FND_SEQNUM.SEQSUCC) then
dbms_output.put_line('Fail: '||to_char(ret));
end if;
end;
Example 11–3 Retrieve the Next Sequence Value for an Automatic Sequence
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;
For more information about task flows, see Oracle Fusion Applications Common
Implementation Guide.
This chapter describes how to implement Audit Trail Reporting in Oracle Fusion
Applications.
This chapter contains the following sections:
■ Section 12.1, "Introduction to Audit Trail Reporting"
■ Section 12.2, "Implementing Audit Trail Reporting"
Metadata
Two database schema tables, FND_AUDIT_WEBAPP_AM and FND_AUDIT_
ATTRIBUTES, hold metadata information that is required for Auditing.
■ FND_AUDIT_WEBAPP_AM captures the list of application modules for an
application.
WEBAPP APPLICATION_MODULE
VARCHAR2(80) VARCHAR2(240)
■ AuditTreeBean.java: Session scoped managed bean class for the AuditSetup page
fragment. It contains the action/action listener, binding, and display methods. It
also creates the Tree Model structure for the Applications Tree Table and filters
the data shown in the Applications Table for the selected view object.
■ AuditModelUtility.java: Utility file that holds the logic for reading the
applications modules and traversing through the structure to show those objects
that are auditable.
5. Determine which attributes of each business object to not audit. By default, all
attributes are shown except:
■ Attributes with a non-translatable custom property with Name="Auditable"
and Value="N". This follows an opt-out policy. That is, if no property is
defined, the value is assumed to be "Y."
■ Attributes that have display hint set to hidden.
■ Attributes that are history columns; for example: Created By, Creation Date,
Last Updated By
<ViewAttribute
Name="Attribute1"
IsUpdateable="false"
PrecisionRule="true"
EntityAttrName="Attribute1"
EntityUsage="AttributeEO"
AliasName="ROWID">
<Properties>
<CustomProperties>
<Property
Name="Auditable"
Value="N"/>
</CustomProperties>
<SchemaBasedProperties>
<DISPLAYHINT
Value="Hide"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
6. To have a user-friendly display name for all application modules, business objects
and attributes names the display name property for each needs to be set. For
applications modules and business objects it is also a good idea to put in a
description, since the description will be shown in the Audit Setup UI and also
will give the administrator further information on the business objects and/or
application module. The display name and description are available as a property.
<Properties>
<CustomProperties>
<Property
Name="Auditable"
Value="Y"/>
</CustomProperties>
<SchemaBasedProperties>
<LABEL
ResId="ViewObjectVO_LABEL"/>
<TOOLTIP
ResId="ViewObjectVO_TOOLTIP"/>
</SchemaBasedProperties>
</Properties>
<ResourceBundle>
<XliffBundle
id="oracle.apps.fnd.applcore.audit.test.model.view.common.ViewObjectVOMsgBundle
"/>
</ResourceBundle>
7. For custom business objects, identify the application module the custom business
objects belong to, and add this to the metadata table as defined in step 4. Define
the "Auditable" property as defined in step 5 on the custom business objects.
8. Enable the User Key.
To base a search ability on a key other than the primary key of the View Object,
you need to set the AUDIT_USER_KEY non-translatable property on this attribute.
This attribute must be a unique value, and it should be set only on one attribute
that is not the primary key.
<ViewAttribute
Name="TableName"
IsUnique="true"
IsNotNull="true"
PrecisionRule="true"
EntityAttrName="TableName"
EntityUsage="FndTablesEO"
AliasName="TABLE_NAME">
<Properties>
<CustomProperties>
<Property
Name="AUDIT_USER_KEY"
Value="Y"/>
</CustomProperties>
</Properties>
</ViewAttribute>
hardcoded value->
or <Property Name="AUDIT_CONTEXT1_KEYATTR_ADDL" Value=""/>
<-attribute of base view for addl. key->
<-composite key specification - end->
</CustomProperties>
</Properties>
</ViewObject>
<-DB View Name : This DBOBJECT should represent Database View that has a
query to list of all the primary keys specific to that View Object->
<Property Name="AUDIT_VIEWCRITERIA_DBOBJECT" Value=""/>
<-Key column of the DB View->
<Property Name="AUDIT_VIEWCRITERIA_KEYCOL" Value=""/>
<-Key attribute of the base View Object->
<Property Name="AUDIT_VIEWCRITERIA_KEYATTR" Value=""/>
</CustomProperties>
</Properties>
</ViewObject>
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/audit/ui/flow/AuditSetupAdminTF.xml#
AuditSetupAdminTF"/>
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/audit/ui/flow/AuditReportAdminTF.xml
#AuditReportAdminTF" label="Admin UI"/>
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/audit/ui/flow/AuditReportObjectSpeci
ficTF.xml#AuditReportObjectSpecificTF"
label="Object Specific UI"
parametersList="viewObject=oracle.apps.fnd.applcore.patterns.test.model.view.Servi
ceRequestsVO;pkValue=157;fromDate=01/01/2010;toDate=12/31/2010"/>
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 needs to 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. Once 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 13, "Getting Started with Your Web Interface"
■ Chapter 14, "Implementing the UI Shell"
■ Chapter 15, "Implementing Search Functions in the UI Shell"
■ Chapter 16, "Implementing Additional Functions in 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"
■ Chapter 19, "Implementing Attachments"
■ Chapter 20, "Organizing Hierarchical Data with Tree Structures"
■ Chapter 21, "Working with Localization Formatting"
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:
■ Section 13.1, "Introduction to Developing a Web Application"
■ Section 13.2, "Oracle Fusion Guidelines, Patterns, and Standards"
■ Section 13.3, "Basic Building Blocks"
■ Section 13.4, "Introduction to the UI Shell"
■ Section 13.5, "Applications UI Patterns and Features"
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 13–1, 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.
Work Area
A Work Area, as shown in Figure 13–2, consists of a Regional Area, a Local Area and a
Contextual Area. Each area is intended to have content for a specific purpose.
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
Workareas 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, in conjunction with those provided by Oracle ADF and
WebCenter, provide the basis for all web interfaces.
■ Enforcement of patterns.
■ Faster development.
■ Changes can be made to one component definition rather than to each instance in
every application.
Supported patterns are:
■ Applications Tables
■ Applications Panels
■ Applications Master-Detail
■ Applications Detail On Demand
■ Applications Tree
■ Applications Tree Tables
■ Applications Dialog Details
■ Using the Custom Wizard with Applications Popups
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
■ Page button bar (including navigation bar)
■ Facets for page-specific UI components
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 Tree
The Applications Tree component provides these basic capabilities:
■ Tree toolbar with default buttons
■ Facets for adding ADF tree, custom toolbar buttons, and so on
■ Default implementations for tree actions
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.1, "Introduction to Implementing the UI Shell"
■ Section 14.2, "Populating a UI Shell"
■ Section 14.3, "Implementing Application Menu Security"
■ Section 14.4, "Controlling the State of Main and Regional Area Task Flows"
■ Section 14.5, "Working with the Global Menu Model"
■ Section 14.6, "Using the Personalization Menu"
■ Section 14.7, "Implementing End User Preferences"
■ Section 14.8, "Using the Administration Menu"
■ Section 14.9, "Using the Help Menu"
For more information about the features, see:
■ Chapter 13, "Getting Started with Your Web Interface"
■ Chapter 15, "Implementing Search Functions in the UI Shell"
■ Chapter 16, "Implementing Additional Functions in 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"
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.
– 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.
– 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.
* 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.
■ Group Spaces
The Group Spaces link bundles all the collaboration tools and provides an easy
way for users to create their own dynamic collaborative groups around a project
or business task flow. See Section 15.4, "Implementing Group Spaces."
■ Personalization
The Personalization menu options let you set your preferences, edit the current
page, and reset the content and layout. See Section 14.6, "Using the Personalization
Menu."
■ Accessibility
The Accessibility link 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.
■ Administration
The Administration menu options allow you to customize the current page at a
multi-user level, to manage sandboxes, and to get access to the setup applications.
See Section 14.8, "Using the Administration Menu."
■ Help
The Help menu options let you control trace levels, run diagnostics, and provide
an About page that lists information about the application. See Section 14.9, "Using
the Help Menu."
■ Sign In / Sign Out
Note: When signing in, users always are directed to the application's
home page.
3. In the dialog:
■ Enter a file name and directory path.
The file name should follow these patterns:
– [<Product Code><LBA Prefix>]<Role>Dashboard.jspx
– [<Product Code><LBA Prefix>]<Object>Workarea.jspx
■ From the Use Page Template list, select UIShell.
Note: 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
menu 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."
Now you can add components to the page. Table 14–1 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.
title="#{adfBundle['oracle.apps...resource.xy
zGenBundle']['Header.DefaultMain']} -
#{adfBundle['oracle.apps...resource.xyzGenBun
dle']['Header.WorkAreaLabel']} -
#{adfBundle['oracle.apps.common.acr.resource.
ResourcesGenBundle']['Header.OracleApplicatio
ns']}" >
14.2.1.1.1 How to Create an Applications Menu The following information describes how
to create an ADF menu to access page elements through the Navigator menu on JSF
pages or task flows that are based on the UI Shell template.
Select the JSPX page in the Application Navigator, then right-click and select the
Create Applications Menu option.
This step creates the menu file with one itemNode. The menu file will be named <view
id>_taskmenu.xml. For example, if there is a PageA.jspx, its view ID in the
adfc-config.xmlfile is PageA, and the menu file name is PageA_taskmenu.xml. This
step also should add the ApplicationsMenuModel managed bean entry into the
adfc-config.xml file. The managed bean entry should not have the topRootModel
managed bean property set. Example 14–1 shows a sample of the generated content in
the PageA_taskmenu.xml file.
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/Tasks
List.xml#TasksList"
disclosed="true"
parametersList="fndPageParams=#{pageFlowScope.fndPageParams}"/>
<!-- Typical itemNode entry for a task flow -->
<itemNode id="__myProductTFId"
focusViewId="/PageA"
label="#{myBundle.myProductTFxyz}" taskType="defaultMain"
taskFlowId="<fully qualified-TFid>"
disclosed="true""/>
<!-- .. Additional itemNodes for other task flows on PageA -->
</itemNode>
</menu>
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 14–4, 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.
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.
Note: Most applications will have multiple task flows for the
Regional, Local and Contextual areas. For instance, Figure 14–1, "UI
Shell Areas" shows 10 task flows.
The Create ADF Task Flow dialog shown in Figure 14–6 is displayed.
5. Ensure that the JSF page fragment file is selected in the Application Navigator and
is displayed in the Edit view.
a. In the Edit view, click the Source tab.
b. Locate the line that resembles <f:facet name="localArea"/>.
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. From the Create menu that is displayed, select Region.
The <f:facet name="localArea"/> changes to <f:facet name="localArea">
and code resembling that shown in Example 14–2 will be inserted after it.
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. From the Create menu that is displayed, select Region.
l. Click OK on the Edit Task Flow Binding dialog that is displayed.
Code resembling that shown in Example 14–3 will be inserted after
<af:showDetailItem ...> and the page fragment in the editor will resemble
Figure 14–7.
Now that you have created the Main Area page fragment, you must wrap it in an
ADF task flow.
6. In the Create ADF Task Flow dialog:
a. Enter a descriptive name for the task flow.
For example, enter def_main_task-flow-definition.xml.
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 14–8.
Note: The menu data accomplishes several important jobs for you:
■ It defines properties of the page for you. For instance, it will be
displayed in no-tab mode or with dynamic tabs, and define the
width of the Regional Area.
■ It can create a task list menu for each page.
■ It can create labels for groups of tasks.
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.
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.
Note: 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 Workareas"), 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.
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 14–1.
■ Task Flow Id: ID of the task flow to be loaded.
To enter the ID, click the ellipsis to display the Select Task Flow Id dialog,
shown in Figure 14–12, and browse to the task-flow definition location. By
default, following the standard naming structure, the location will be in path_
to_application directory\ViewController\public_html\WEB-INF.
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 14–11, "Task Flow
Property Inspector".
16. To run the JSPX page, select the page in the Application Navigator, right-click the
page file, and choose Run.
The new page, shown in Figure 14–13, is displayed in a web browser.
17. Check that the newly rendered page contains one tab whose content is the task
flow that you defined in this procedure.
The available itemNode properties for Main Area and Regional Area task flows for
application menus are shown in Table 14–2.
Table 14–2 itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property Property Value What Happens on the Rendered Page
taskType Note: taskType can have four ■ If the value is dynamicMain, the page contains a new link
values: in the Regional Area. When you click the link, a new tab
with the loaded task opens.
■ dynamicMain
If the no-tabs model is used, no new tab is opened. Rather,
■ defaultMain
the current Main Area contents are replaced. (See
■ defaultRegional Section 14.2.3.4, "Supporting No-Tab Workareas.")
■ taskCategory ■ If the value is defaultMain, the page contains a tab
already running this task in the Main Area.
If the no-tabs model is used, only one itemNode should be
defined as a defaultMain. (See Section 14.2.3.4,
"Supporting No-Tab Workareas.")
■ If the value is defaultRegional, the task is loaded into the
Regional Area.
label String 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 Workareas"), 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.
taskFlowId ID of the task flow to be
loaded.
The task flow ID is a
concatenation of the file
location for the task flow
definition, and the task flow
name. For example:
/WEB-INF/MyTaskFlow.xml#My
TaskFlow
reuseInstance True or False If True, when the link is clicked a second time, the tab is
(optional) brought to the top.
A False value means that clicking the corresponding task link
opens new tabs.
However, if the no-tabs model is used, no new tab is opened.
Rather, the current Main Area contents are replaced. (See
Section 14.2.3.4, "Supporting No-Tab Workareas.")
Table 14–2 (Cont.) itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property Property Value What Happens on the Rendered Page
keyList String Important: keyList is used with the task flow ID to identify
the target tab in the Main Area. As such, keyList is only
applicable in dynamic tabs mode, and is ignored in no-tabs
mode.
keyList provides a way to identify a task flow instance. When
reuseInstance is true, use the specified keyList in addition to
the task flow ID to identify the target tab.
The keyList parameter has been implemented for the
following FndUIShellController data control methods:
■ openMainTask
■ discloseRegionalTask
■ collapseRegionalTask
■ navigate
■ openSubTask
In dynamic tabs mode, when looking for a match of an existing
tab, these APIs will first look for any instances of the task flow
that is already open, which has the same task flow ID as the
one passed into them as the parameter. In addition, it will
compare the keyList values, such that the existing task flow
will be picked only if its keyList values match the ones
specified in the keyList parameter.
It does not matter if the task flow parameters are the same or
different. If the keyList is not set in the menu metadata, you
can reuse a tab only if you pass in a null keyList.
loadPopup True or False See Section 14.2.3.5, "Implementing the Task Popup."
This provides a way to load the task flow into a Popup when
the user clicks one of the Task List links.
loadDependentFl True or False The no-tab navigation mode can load a Main Area task flow
ow and a dependent task flow simultaneously, while displaying
only one flow at a time. (See Section 14.2.3.4, "Supporting
No-Tab Workareas.")
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 If forceRefresh = true, the contents are refreshed. If
forceRefresh is set to false, if the task flow parameters are
identical, no refresh will occur, but if they are different, the
task flow is refreshed using the new parameters.
Table 14–2 (Cont.) itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property Property Value What Happens on the Rendered Page
stretch True (default) or False When the UIShellMainArea stretch attribute is set to true,
contents under localArea will be stretched when rendered in
the Local Area. When set to false, contents under
localAreaScroll will not be stretched, but will be rendered
with a scroll bar, if necessary, in the Local Area. (This facet is
contained within an af:panelGroupLayout with
layout=scroll.)
disclosed True or False All the task flows will be rendered in the Main Area. The task
(optional) 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 True or False (default) Task flow definitions use conditional activation. There are a
number of cases in which Oracle Fusion Applications run with
the Regional Area collapsed by default. Unless the user
expands it, there is no need to activate the task flows for the
Regional Area. However, some use cases depend on the task
flow that is under the Regional Area being active even when
collapsed. In this case, the active attribute can be set in the
property inspector for the item node. active has three possible
values:
■ default <False>
■ False
■ True
If you require that your task flows be activated or run even
though they are not displayed, you must change the active
property on the itemNode to True.
taskFlow The Task List is exposed as a task flow. See Section 14.2.4,
"How to Pass Parameters into Task Flows from Tasks List."
destination String The destination attribute is supported on the item nodes for
Task List; that is, for item nodes that have the task type set to
dynamicMain. The destination attribute is intended only for
navigating to an external web site. When it is defined, it takes
precedence over all other attributes. Example of the menu
data:
<itemNode id="__ServiceRequest_itemNode_externalUrl"
destination="http://www.yahoo.com"/>
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 14–2.
■ To add a dynamic Main Area task flow, set taskType="dynamicMain".
■ To add a default Regional Area task flow, set taskType="defaultRegional".
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}"/>
Example 14–4 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"/>
You also can set the no-tab mode declaratively in the Property Inspector:
1. Select the itemNode from the Structure window.
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. Set the Dynamic Tab Navigation property to false.
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.
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
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 14–6, 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.
■ 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 18–5,
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 14–7.
The methodParameters parameter can be used to pass a Java object into the task flow
that is specified in the taskFlowId parameter. Use the setCustomObject() method in
FndMethodParameters to set the Java object.
NDValue="/WEB-INF/TestPanelSplitterTaskFlow#TestPanelSplitterTaskFlow"
NDType="java.lang.String"/>
<NamedData NDName="keyList" NDType="java.lang.String"/>
<NamedData NDName="parametersList" NDValue="" NDType="java.lang.String"/>
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
Code in the managed bean for passing a hashmap to the task flow would resemble
Example 14–9. 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).
Then, in the managed bean of the task flow, the Java object can be read, as shown in
Example 14–10.
Note: 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.
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 14–11.
You can specify any file type, such as xls, doc, pdf, txt, rtf, and ppt, that is within the
application.
<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 14–14 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 14–14 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']}"
Example 14–15 Task Flow-specific Expression Language Expression Used for Task
Flow Permission Preliminary Check
rendered="#{securityContext.taskflowViewable[/WEB-INF/audit-expense-report.xml#aud
it-expense-report]}"
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.
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 Workareas"), 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.
2. Drag openMainTask and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 14–15 is displayed so you can choose
one of the three options.
Figure 14–15 Selecting an Open Option from the Applications Context Menu
2. Drag closeMainTask and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 14–17 is displayed so you can choose
one of the three options.
Figure 14–17 Selecting a Close Option from the Applications Context Menu
Two APIs shown in Example 14–16 open and close a Main Area tab.
* @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)
Example 14–17 methodAction Binding in Page Definition of Page Fragment That Calls
openMainTask
<methodAction id="openMainTask" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="openMainTask"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.openMainTask_
FndUIShellController_dataProvider_openMainTask_result">
<NamedData NDName="taskFlowId"
NDValue="/WEB-INF/TestPanelSplitterTaskFlow#TestPanelSplitterTaskFlow"
NDType="java.lang.String"/>
<NamedData NDName="keyList" NDType="java.lang.String"/>
<NamedData NDName="parametersList" NDValue="" NDType="java.lang.String"/>
<NamedData NDName="label" NDValue="Test App Panel"
NDType="java.lang.String"/>
<NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
<NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
<NamedData NDName="loadDependentFlow" NDValue=""
NDType="java.lang.Boolean"/>
<NamedData NDName="methodParameters"
NDValue="#{TestOpenMainTaskMBean.fndMethodParams}"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
Example 14–18 shows code in a managed bean for passing a hashmap to the task flow.
Example 14–18 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 14–19.
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 Workareas."
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 14–20.
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 14–21 are exposed as data control methods under
FndUIShellController data control.
/**
* Collapses a Regional Area task.
*
* @param taskFlowId Task flow to collapse
* @param keyList Key list to locate the task flow instance.
* This is a semicolon-delimited list of key-value pairs.
* For example, "key1=value1;key2=value2".
Notes:
■ Declarative support allows the inflexibleHeight property to
control the pixel height of the Regional Area panel. Programmatic
support does not have this allowance.
■ Programmatic support allows the forceRefresh property to make
it possible to refresh a task without passing in any parameters.
Declarative support does not have this allowance.
■ Refreshing a Regional Area task without disclosing the task is not
supported.
■ Multiple Regional Area tasks are allowed to be disclosed at the
same time. A switch to force showing only one task at a time is
not provided.
■ Support for persisting any of these settings explicitly altered by
the user during a session, across sessions, is not a part of this
feature.
<document>/oracle/apps/fnd/applcore/patterns/uishell/templates/contextual-area-tas
k-flow-template.xml</document>
<id>contextual-area-task-flow-template</id>
</template-reference>
■ 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 14–23.
taskFlowId="/WEB-INF/page2-task-flow-definition.xml#page2-task-flow-definition"
contextualAreaCollapsed="true"
contextualAreaWidth="0"/>
■ 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 14–24.
Set the method in the page managed bean to set the contextualAreaWidth and
contextualAreaCollapsed values, as shown in Example 14–24.
■ 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 14–25.
Set the method in the page managed bean to set the contextualAreaWidth and
contextualAreaCollapsed values, as shown in Example 14–25.
Note: Before you create menus, you first must create JSF pages using
the UI Shell template.
The Navigator menu 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.
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
outcome of the expression), the menu item will be hidden even if the user has
access to the page. There are certain times you would want to do this. For instance,
consider a person working in HR as a consultant, not an employee. You might
want a menu entry for editing employee data under an HR category, without
showing an entry under the Employee Self-Service category that also leads to the
same page. See Example 14–30.
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.
■ The applicationStripe attribute determines which LDAP stripe is checked for
the securedResourceName attribute.
securedResourceName="oracle.apps.hcm.people.portrait.ui.page.MyPortraitPageDef"
<groupNode id="groupNode_my_information_compensation"
idref="_groupNode_my_information_compensation_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].COMPENSATION}">
applicationStripe="hcm"
</groupNode>
<groupNode id="groupNode_my_information_career"
idref="_groupNode_my_information_career_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].CAREER}">
<itemNode id="itemNode_my_information_goals"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].GOALS}"
focusViewId="/ManageGoalsWorkArea" webApp="HcmTalent"
securedResourceName="oracle.apps.hcm.goals.core.publicUi.page.ManageGoalsWorkAreaP
ageDef"/>
<itemNode id="itemNode_my_information_performance_management"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PERFORMANCE}"
applicationStripe="hcm"
focusViewId="/PerformanceWorkArea" webApp="HcmTalent"
securedResourceName="oracle.apps.hcm.performance.documents.publicUi.page.Performan
ceWorkAreaPageDef"/>
</groupNode>
<groupNode id="groupNode_my_information_procurement"
idref="_groupNode_my_information_procurement_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PROCUREMENT}">
<itemNode id="itemNode_my_information_purchase_requisitions"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PURCHASE_
REQUISITIONS}"
focusViewId="/PrcPorCreateReqWorkarea" webApp="Procurement"
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>
The Preferences menu only appears if you have the ApplSession filter and mapping
set up. See Section 48.2, "Configuring Your Project to Use Application User Sessions.".
Set Preferences
You create the actual Preferences dialog, such as shown in Figure 14–22. See
Section 14.7 for the details of how to implement the Preferences menu.
supported. The task list will be loaded as a defaultRegional task flow and the Main
Area will be a defaultMain task flow.
Workarea Title
Each preferences page should display a title similar to {Category_name:Page_name}.
This can be done though an Expression Language expression and will not be created
automatically from the framework.
The name that appears in the task list can be different from the page title. This is
allowed because the task list name is generated from the task list preference
distributed menu metadata, while the page title will be from the local page-level menu
metadata.
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 Workareas" for more information.
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.
14.7.3 How to Deploy Preferences Pages and Design General Preferences Content
Application preferences pages are deployed with the corresponding product pages.
The design should be similar to that shown in Figure 14–22.
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).
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 Workarea 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.
English. If accessing a protected page, the login screen appears. This login screen may
allow the user to select a language for the session. If selected, this will override the
language. If the user does not select anything on login and if the user has a language
preference previously saved, this will override the language if it is an installed
language. If saved, it would be held in the LDAP settings for the Oracle Fusion
applications Language setting in the orclFALanguage attribute of the orclIDXPerson
object. This is controlled by Oracle Identity Manager.
Users can set the Language preference by selecting the Set Preferences link from the
Personalization menu in the Global Area. The Language option will look similar to
Figure 14–23.
Customization Manager...
Select this option to start the Customization Manager.
For information about customization, see Chapter 62, "Creating Customizable
Applications" and the "Customizing Applications with MDS" chapter in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework. For more information about the Customization Manager, see the
"Customization Manager" section in the "Extending Runtime Editing Capabilities
Using Oracle Composer" chapter, and the "Manage Customizations" section of the
"Introduction to Oracle Composer" chapter of the Oracle Fusion Middleware Developer's
Guide for Oracle WebCenter Portal.
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 Oracle Composer-Specific MDS Configurations" chapter of the Oracle
Fusion Middleware Developer's Guide for Oracle WebCenter Portal.
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" in the "Understanding the Customization
Development Lifecycle" chapter of the Oracle Fusion Applications Extensibility Guide.
Privilege
<app-role>
<name>FND_VIEW_ADMIN_LINK_PRIV</name>
<display-name>View Administration Link</display-name>
<description>Privilege to view administration link in UI shell. This privilege
is available from Roles(s): Supply Chain Application Administrator,Cost
Accountant,Application Implementation Consultant,Application Developer,Application
Administrator</description>
<guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<members>
<member>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>FND_ADMINISTRATION_LINK_VIEW_DUTY</name>
<guid>EA1D0BF0BC096F11B18BDEBD5F4BDB48</guid>
</member>
</members>
</app-role>
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>FND_VIEW_ADMIN_LINK_PRIV</name>
<guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.ResourcePermission</class>
<name>resourceType=FNDResourceType,resourceName=FND_Administration_
Menu</name>
<actions>launch</actions>
</permission>
</permissions>
</grant>
</context-param>
For recording, it may be necessary to turn on automation if all client components
need to be sent down. The following parameter should be present in the application
web.xml:
<context-param>
<description>
This parameter notifies ADF Faces that test automation is being used.
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.
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.
Troubleshooting
When you select the Troubleshooting option, an additional menu, similar to
Figure 14–28, is displayed.
■ Troubleshooting Options
Select this option to display the Options dialog, as shown in Figure 14–29.
■ 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.
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.
* Capture bind variables:
Select this option to enable the SQL trace option to also capture bind vari-
ables.
* Capture wait events:
Select this option to enable the SQL trace option to also capture wait
events.
■ 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 Advanced Application Developer's
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.
■ Applications logging: Applications logging is selected by default. Disabling
logging will warn users that no logging will take place.
– 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 and Diagnostics Tests" and "Troubleshooting for Oracle Fusion
Applications Using Logs, QuickTrace, and Diagnostic Tests" in the Oracle
Fusion Applications Administrator's 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.
■ Run Diagnostics Tests
Selecting this option opens the Diagnostics Dashboard user interface in a new
window. For more information, see "Managing Oracle Fusion Applications Log
Files and Diagnostics Tests" and "Troubleshooting for Oracle Fusion Applications
Using Logs, QuickTrace, and Diagnostic Tests" in the Oracle Fusion Applications
Administrator's Guide.
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 55.3, "Setting and Accessing Profile Values."
About Applications
Select this option to display the Oracle copyright statement and information about the
application.
Shell
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.1, "Implementing Tagging Integration"
■ Section 15.2, "Implementing Recent Items"
■ Section 15.3, "Implementing the Watchlist"
■ Section 15.4, "Implementing Group Spaces"
■ Section 15.5, "Implementing Activity Streams and Business Events"
■ Section 15.6, "Implementing the Oracle Fusion Applications Search Results UI"
For more information about the features, see:
■ Chapter 14, "Implementing the UI Shell"
■ Chapter 16, "Implementing Additional Functions in the UI Shell"
■ Chapter 13, "Getting Started with Your Web Interface"
■ Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
■ Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
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 does allow alternate links as well as 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 Developer's Guide
for Oracle WebCenter Portal.
1. Open your current application in JDeveloper.
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.
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.
You now can enable tagging for your business objects.
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:
■ There can be a maximum of only five columns as primary keys, such as
PK1.PK2.PK3.PK4.PK5.
■ If any primary key column is null, put "null" in the concatenated Resource Id
string. For example, if Resource Id is of type PK1.PK2.PK3, the value can be
123.ABC.null. Do not use just 123.ABC.
■ If your primary key consists of a date, although this is highly unlikely, ensure
that the date value that you use in string concatenation is formatted in Oracle
Database date format.
■ Developers cannot implement their own resource parser.
2. SERVICE_ID (VARCHAR2(200)): This is used to identify the object. The Oracle
Fusion Applications standard is to use the logical business object name.
3. NAME (VARCHAR2(200)): This is what will be displayed as the resource that is
tagged in the Tag Center, and it will be visible to the end users when they search
for a tagged item. Give it a meaningful name, such as <PO Number>+<PO Title>
or Invoice Description or Customer Name.
Note: All fields are varchar2(200). Ensure that you are not
violating the constraint. Also note that if, for instance, your product
has three business objects that you are planning to tag, then you must
build three different services with the proper business object name as
the service ID.
3. From the Resource Palette, go to My Catalogs > WebCenter Services Catalog >
Task Flows, 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.
Note: 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.
The ability to tag an object is now enabled on the page. The code will look similar
to that shown in Example 15–2.
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.
4. Add the entry shown in Example 15–5 to your adf-config.xml file to enable the
default resource action handler from Applications Core.
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"/>
<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.
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 15–1.
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 15–3 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.
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.
If the dataSecurityPrivilegeName parameter is not set, it defaults to read
privilege. This attribute is used in cases where a single table has different
privileges for different users.
■ Put the service definition into MDS. For ease of deployment, service definition
files will be stored in MDS.
■ 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 15–3.
■ Click one of the tags in the tag cloud region of the Tag Center to view the tagged
items, as shown in Figure 15–4.
■ Click the tagged item to view the object in the task flow mentioned in the service
definition file, as shown in Figure 15–5.
■ To check whether or not 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 15–6.
list. The feature is automatically turned on and will be available automatically in pages
using the UI Shell template. Security must be disabled to turn Recent items off.
Implementation
This API is exposed as the data control methods FndUIShellController.openSubTask
and FndUIShellController.closeSubTask that can be dragged and dropped to page
fragments to create links to notify the UI Shell. The FndUIShellController data
control is automatically available to all Oracle Fusion applications that reference
Applications Core libraries.
Example 15–8 shows the signature and Javadoc of the method.
/**
* Closes the currently-focused sub-task and the focus moves to the
* task from which this sub-task was started.
*
* @param methodParameters For future implementation. No-op for now.
* @return For internal Contextual Event processing
*/
public FndMethodParameters closeSubTask(FndMethodParameters methodParameters)
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."
the same label as the parent task flow's label and, therefore, will make it impossible to
distinguish between the parent flow and the sub flow entry in the Recent Items list.
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 15–8.
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 or not 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>
<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 15–10:
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();
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 or not 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:
■ Data security should be applied on an appropriate level. For example, in a
master/detail relationship, security definitions should be created on both parent
and child objects and applied on a proper level.
■ If the child record inherits the security from its parent, then the parent's security
must be programmatically enforced on a sub flow. This should be done by adding
a default method activity on the task flow and calling the data security API to
check that the user has access to the parent. If the user does not have proper
access, an authorization exception is generated.
In addition, you should programmatically enforce the parent data security where
applicable. For instance, if a view object takes the parent primary key as a
parameter, before executing the query the code should check that the user has
access to the parent.
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).
Example 15–9 Example Code from the View Object XML for Bind Variable with Default
Value
<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 15–12.
■ 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 15–10 presents sample code to create or update the lookup.
declare
begin
FND_LOOKUP_VALUES_PKG.CREATE_OR_UPDATE_ROW (
X_LOOKUP_TYPE => 'FIN_EXM_WATCHLIST_CATEGORY',
X_VIEW_APPSNAME => 'FND',
X_LOOKUP_CODE => 'SAVED_EXPENSE_REPORTS',
X_MEANING => 'In Progress Expense Reports'
-- X_SET_CODE IN VARCHAR2 DEFAULT NULL,
-- X_DESCRIPTION IN VARCHAR2 DEFAULT NULL,
-- X_ENABLED_FLAG IN VARCHAR2 DEFAULT 'Y',
-- X_START_DATE_ACTIVE IN VARCHAR2 DEFAULT NULL,
-- X_END_DATE_ACTIVE IN VARCHAR2 DEFAULT NULL,
-- X_DISPLAY_SEQUENCE IN NUMBER DEFAULT NULL
);
end;
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.
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>
■ 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 15–3.
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.
The <user> directory would be the user you used to save the search with, or
anonymous by default.
■ 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.
Note: This ID can be different than the display name that you
entered in the saved search UI.
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.
(QueryModel)evaluateEL("#{bindings.ImplicitViewCriteriaQuery.queryModel}");//See
next code sample for evaluateEL()
if (queryModel != null) {
if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
AppsLogger.write(this, "Watchlist saved search promotion:
getWatchListUserSavedSearchList method: queryModel is not null",
AppsLogger.FINEST);
}
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.
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 15–14, onto the page.
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 15–15.
6. Expand the connection node and the ADF library node in the Resource Palette as
shown in Figure 15–16.
Once the ADF Task Flows node is expanded, you should see two task flows. The
task flow AtkWatchlistUserSavedSearchPromotionTF is the one to be used.
7. Drag and drop the AtkWatchlistUserSavedSearchPromotionTF task flow as a
region into the toolbar component (present in the query region toolbar facet),
created in the previous steps. As soon as the task flow is dropped onto the page,
the Edit Task Flow Binding dialog is displayed. Enter the following values for the
mandatory parameters.
■ categoryCode: Provide the WATCHLIST_CATEGORY_CODE that has been seeded in
the ATK tables.
■ watchlistItemCode: Provide the WATCHLIST_ITEM_CODE provided while
creating the Watchlist setup data.
■ userSavedSearchList: This represents the model object of the query region. To
populate this field:
a. 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 15–12. In this
case, the value is watchListUserSavedSearchList, found in ADF
Managed Beans > backingBeanScope >
searchOrderScheduleBackingBean > watchListUserSavedSearchList.
The Expression will be:
#{backingBeanScope.searchOrderScheduleBackingBean.watchListUserSavedSea
rchList}
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 15–19. 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.
12. Run the UI page. In the toolbar facet of the query region, there will be a Watchlist
Options button, as shown in Figure 15–21.
When you click the button, a popup with the list of all saved searches is displayed,
as shown in Figure 15–22.
to:
parameter id="internalCriteriaName"
value="#{backingBeanScope.searchRelatedBean.internalCriteriaName}"
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:
■ Look into the PageFlowScope to retrieve the ViewCriteriaName.
■ 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 15–14.
Second, you can use the code shown in Example 15–15 to apply the ViewCriteria to
the search panel. If no ViewCriteria was passed, the code loads the default
ViewCriteria.
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.
■ 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:
■ The implementation is occurring in a label that is either dependent on ATGPF_MAIN
or uptakes ATGPF_MAIN on a regular basis.
■ The spaces application and the JDeveloper Standalone WebLogic Server that
would run the application have the requisite setup done.
■ The consuming applications are secure. Group Spaces functionality attempts to
retrieve the group spaces for the logged-on user. Without a secure application, this
functionality would fail.
BusinessActivityPublisher
This class provides the publishActivity API that can be used to publish Activities
asynchronously. This is a singleton per Java EE application. An instance of this class
can be obtained using the getInstance API. This lets product teams define such things
as ActivityTypes, ObjectTypes, and resource-view definitions, declaratively in the
service-definition.xml file, similar to business event-related activities.This would
allow product teams to follow the same mechanism to define and publish Activities
for both entity object and non-entity object-based model changes with very little code
changes.
/**
* Queues the Activity for publishing. The queued activities are published
* to the Activity Streaming service asynchronously if there is a matching
* ActivityType defined for the source business event. If no matching
* ActivityType is found in the service-definition.xml corresponding to the
* source entity object, the activity is ignored.
* @param activity
*/
public void publishActivity(BusinessActivity activity)
/**
* Should be called during App undeploy to stop the publisher thread.
* In a Java EE container, this method is called by Applications Core
* ServletContextListener.
*/
public void release()
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 15–17.
/**
* 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 15–18.
/**
* ID of the service-definition containing the metadata for this
* Activity.
* @return serviceId
*/
public abstract String getServiceId();
/**
/**
* 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();
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>
Table 15–5 Transient Attributes that Can Be Passed with the Payload
Attribute Type Description Sample Value
WCActivityServiceId String This attribute's value is used to oracle.apps.crmdemo.model.OpportunityEO
identify the business object service
to be associated with the Activity.
WCAdditionalActivityServiceId String This attribute's value is used to Values are similar to those of
1 identify any additional service that WCActivityServiceId
must be associated with the Activity.
WCAdditionalActivityServiceId String This attribute's value is used to Values are similar to those of
2 identify any additional service that WCActivityServiceId
must be associated with the Activity.
WCActivityActorGuid1 String This attribute's value is used to <User_GUID>
identify any actor that must be
associated with the Activity if the
default actor value must be
overridden. For instance, in the
message it can be accessed as
actor[0]
WCActivityActorGuid2 String This attribute's value is used to <User_GUID>
identify any actor that must be
associated with the Activity if the
default actor value must be
overridden. For instance, in the
message it can be accessed as
actor[1]
WCActivityObjectTypeNames String This attribute should provide a Emp, Dept
comma-separated list of object-type
names associated with a particular
Activity. Programmatically
getActivityObjectTypeNames()
API in the entity object's
EntityImpl.
The first object- type in this string
will be used to create the custom
attributes needed for the primary
object. When creating the primary
object for an Activity, the object type
of the first object listed in the
service-definition.xml file
should be used even though the
custom attributes used to construct
this object are fetched from a
different object type based on
getActivityObjectTypeNames() or
WCActivityObjectTypeNames. This is
necessary for the follow model to
work.
The order of the objects in this array
can be used to reference the objects
in the Activity message format
string.
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. Set the taskFlow resourceId parameter to #{securityContext.userName}. This
will tie the task flow to the current user at runtime.
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 Developer's Guide for Oracle WebCenter Portal.
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>
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 - Used on the Activity Stream full view task flow.
■ summaryByListMessageFormatKey - Used in the summary view Activity
Stream task flow.
■ summaryByCountMessageFormatKey - Used in the summary view task flow.
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.
The following sample uses the Java Resource Bundle class:
<resource-bundle-class>oracle.apps.crm.OpportunityResourceBundle</resource-bund
le-class>
<activity-types>
<generic-activity-category name="OPPTYUPDATE">
<activity-type name="OpptyStatusUpdate"
displayName="OPPTY_UPDATE"
description="OPPTY_UPDATE_DESCRIPTION"
messageFormatKey="OPPTY_STATUS_UPDATED"
defaultPermissionLevel="SHARED"/>
</generic-activity-category>
</activity-types>
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. For remaining activities, summarize by finding a common Actor. Summarize
or aggregate the objects either by listing them if there are three or fewer, or by
counting them if there are more than three.
For example, note the following activities:
a. James updated Project Alpha tasks.
b. Viju updated Project Alpha tasks.
c. Ling updated Project Alpha tasks.
d. Monty updated Oppty 200 laptops status
e. Monty updated Oppty Solaris workstations status
f. Monty updated Oppty 2 DB machines status.
In the summarized view, the Activities are summarized as follows:
■ Activities a-c: James, Viju, Ling updated Project Alpha tasks.
■ Activities d-f: Monty updated 200 laptops, Solaris workstations, 2 DB
machines opportunities status.
Example 15–19 shows sample format strings for the preceding scenario.
6. 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"
iconURL="">
</object-type>
</object-types>
7. 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 15–6 will be used.
<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:
■ taskFlowId: The task flow where you want to go.
■ resourceParamList: The list of parameters that you want to pass to the task
flow. For example, if a business object task flow takes the opptyId parameter,
in resourceParamList you should specify "opptyId". If multiple parameters
are required, the parameters should be separated by a semi-colon (;), for
example "opptyId;opptyType". When the hyper link is clicked, parameters
opptyId="oppty id value" and opptyType="type value" will be passed as
input parameters to the task flow.
<resource-view taskFlowId="/WEB-INF/OpportunityTF.xml#OpportunityTF">
<parameters>
<parameter name="viewId" value="Opportunity"/>
<parameter name="webApp" value="CRMApp"/>
<parameter name="pageParametersList" value=""/>
<parameter name="taskParametersList" value=""/>
<parameter name="resourceParamList" value="opptyId"/>
</parameters>
</resource-view>
<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");
}
}
resourceBundle="oracle.apps.fnd.applcore.crmdemo.BusinessActivityServiceResourceBu
ndle"
titleKey="CASE_SERVICE_CATEGORY"
icon="/a/s/g.gif"/>
</service-category-definition>
<activity-type name="unfollowObject"
displayName="Unfollow Object"
messageFormatKey="ACTIVITY_UNFOLLOW_OBJECT_MSG"
description="Unfollow Object">
</activity-type>
If you expand the Categories field, a list, similar to that shown in Figure 15–24, is
displayed:
Categories
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.
Search Term
This is a text field for the values on which to search. The field defaults to showing 20
characters, and 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.
To find only items with the tag foo, enter ecsf_tags:foo as the search word. No data will
be returned if the word foo is in the transactional data but not in the tag.
Click the Play button to initiate the search.
Saved Searches
Click the Saved Searches magnifying glass icon to open a list of saved searches. The
list shown in Figure 15–26 includes a Personalize… action item that will display the
Personalize Saved Searches dialog so that saved searches can be deleted or renamed.
■ 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 15–27.
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.
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:
■ Multiple categories or a single category
The sort can be based only on Relevance (an implicit universal attribute) and
LastModifiedDate (a universal attribute).
■ A Single Searchable Object in a category
The sort can be based on Relevance, LastModifiedDate, and all other attributes for
that Searchable Object, as shown in Figure 15–30.
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.
Common Filters
The Common Filters panel that is displayed below the Application Filters can be
expanded so that it appears similar to Figure 15–31.
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 15–32.
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 32.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 exists
in the list, it will be removed from its current place in the list and added to the front.
From that backing bean, you can call the Oracle Fusion Applications Search API to run
the search, as shown in Example 15–27.
Example 15–27 Calling Oracle Fusion Applications Search API to Run Search
public class GlobalSearchUtilBean {
public GlobalSearchUtilBean()
{
}
public void runSearch(ActionEvent actionEvent)
{
List<SearchCategory> categories =GlobalSearchUtil.getCategories();
// manipulate search category list here
String searchString = "some search string";
GlobalSearchUtil.runSearch(categories, searchString, actionEvent);
}
}
15.6.3.2 Running the Oracle Fusion Applications Search UI Under Oracle WebLogic
Server
For details of running the ECSF artifacts, such as the SearchFeedServlet, see
Chapter 28, "Creating Searchable Objects."
To run the UI Shell and Oracle Fusion Applications Search, follow the setup
instructions for running Applications Core under Oracle WebLogic Server in
Chapter 2, "Setting Up Your Development Environment" and the instructions on how
to set up a UI Shell page, menu entries and task flows from Section 14.1, "Introduction
to Implementing the UI Shell". This should give you a running UI Shell project.
Add the SearchDB database connection to the project. For more information about
creating the SearchDB connection, see Section 32.6.1, "How to Create the SearchDB
Connection on Oracle WebLogic Server Instance".
Update the ECSF command-line script (runCmdLinScript.sh) to reference the JAR files
containing the base classes. Example 15–28 shows the UNIX version; the DOS version
is similar.
resourceId="#{bindings.LookupType.inputValue}.#{bindings.ViewApplicationId.inputVa
lue}.#{bindings.Language.inputValue}.#{bindings.Meaning.inputValue}"/>
<af:region value="#{bindings.tagginglaunchdialog1.regionModel}"
id="r1"/>
<af:panelLabelAndMessage label="#{bindings.LookupType.hints.label}"
id="plam4">
<af:outputText value="#{bindings.LookupType.inputValue}" id="ot9"/>
</af:panelLabelAndMessage>
See Section 15.1, "Implementing Tagging Integration" for setting up tags in your
UI. Figure 15–33 shows the attributes for lookup types.
Note: Do not forget to mark your key columns and ensure the order
is consistent between the view object and the
tag:taggingButton.resourceId attribute.
Figure 15–34 shows the attributes for Searchable view object lookup types.
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 15–35.
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.
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 15–34. See Figure 15–36.
There are two parameters, shown in Table 15–7, that may be passed to the
extension.
15.6.6 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 27, "Getting Started with Oracle Enterprise Crawl and
Search Framework."
Figure 15–37 shows the result that will be produced (a single row in the search results
table).
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
■ Action Type of URL
■ An Action Target to the required destination, including groovy substitution
parameters
■ A Title
No Parameters are required; however a single iconURL parameter may be defined if an
icon is required for the URL action. See Table 15–8.
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.
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
■ Action Type of Task
■ A Title
Parameters are shown in Table 15–9. Note that, although this table resembles
Table 15–10, it presents the use case that the majority of users will use. The information
in Table 15–10 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.
when the user clicks the result and will be based on a permissions check based on the
applicationStripe and pageDefinitionName parameters. If these two parameters are
not supplied, the other parameters will be used "as is," and navigation will be
performed based on their values.
If the applicationStripe and pageDefinitionName parameter values are supplied, the
algorithm used is the same as for tagging.
■ Divide all delimited parameters based at the caret, and produce an ordered list of
targets that can be opened.
■ If there is only one target defined, use it with no permission check.
■ For each target, determine if the user can open the page and task flow.
■ If a target that can be opened is in the current view, use it.
■ Take the first target that can be opened.
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 15–10.
Note that, although this table resembles Table 15–9, 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 15–9.
<![CDATA[null]]>
</ActionTarget>
<Parameters>
<Parameter Name="navTaskParametersList">
<Value>
<![CDATA["lookupType=" + LookupType + ";viewApplicationId=" +
ViewApplicationId + ";language=US;meaning=" + Meaning]]>
</Value>
</Parameter>
<Parameter Name="webApp">
<Value>
<![CDATA['GlobalSearch']]>
</Value>
</Parameter>
<Parameter Name="TaskFile">
<Value>
<![CDATA["/WEB-INF/LookupTypeSearchResultsTaskFlow.xml"]]>
</Value>
</Parameter>
<Parameter Name="navTaskKeyList">
<Value>
<![CDATA["meaning=" + Meaning]]>
</Value>
</Parameter>
<Parameter Name="TaskName">
<Value>
<![CDATA["LookupTypeSearchResultsTaskFlow"]]>
</Value>
</Parameter>
<Parameter Name="viewId">
<Value>
<![CDATA["TestUIShellPage"]]>
</Value>
</Parameter>
</Parameters>
</Action>
15.6.7 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.
Authorization Tab:
■ 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 15–41.
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.
For instance, you can create an fmwadmin user on the Oracle Fusion Applications side
by adding to the jazn-data.xml file.
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.
Shell
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.1, "Introducing the Navigate API"
■ Section 16.2, "Warning of Pending Changes in the UI Shell"
■ Section 16.3, "Implementing the Oracle Fusion Home Page UI"
■ Section 16.4, "Using the Single Object Context Workarea"
■ Section 16.5, "Implementing the Third-Party Component Area"
■ Section 16.6, "Developing an Activity Guide Client Application with the UI Shell"
■ Section 16.7, "Troubleshooting UI Shell Issues"
For more information about the features, see:
■ Chapter 14, "Implementing the UI Shell"
■ Chapter 15, "Implementing Search Functions in the UI Shell"
■ Chapter 13, "Getting Started with Your Web Interface"
■ Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
■ Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
2. Drag navigate and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 16–2 is displayed so you can choose
one of the options.
Figure 16–2 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.
Certain parameters, summarized in Table 16–2, can be passed using the Navigate API's
argument list.
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 Workareas"), 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 16–1.
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 ASK deployment tables. These tables are
populated at deployment time through Functional Setup 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 cannot be passed as a parameter.
■ When navigating using this API, the ADF Controller state of the
source page is not cleaned up.
Example 16–4 Adding a client listener when a command link/button invokes Data
Control APIs programmatically
<af:commandButton text="Calling datacontrol api programmatically"
binding="#{backingBeanScope.backing_Navigateviaprogramatically.cb1}"
id="cb1" action="go">
<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 16–5 to their main page fragment's pageDef whose taskflow is attached
to the tab in MainArea.
The Data Control API shown in Example 16–5 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. Drop the JSPX to adfc-config.xml.
5. Repeat Steps1 through 4 for all home page JSPX pages.
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 16–3.
If the facet is empty, the area does not appear. You also can create a view scope
parameter so other flows on the page can get the context. See Figure 16–4.
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.
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 16–11 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 16–11 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.
Example 16–12 shows a sample entry for a child item node for defaultMain task in the
menu.xml to pass the appropriate deptno in the single object context to a task flow that
is initialized based on this input value.
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.
Figure 16–7 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 16–8 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. Using shared libraries for Activity Guide runtime JAR files
Add the shared library references oracle.soa.bpel and oracle.soa.workflow.wc
to the weblogic-application.xml file.
<library-ref>
<library-name>oracle.soa.bpel</library-name>
</library-ref>
<library-ref>
<library-name>oracle.soa.workflow.wc</library-name>
</library-ref>
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.".
Process Client Application with Oracle ADF" section of Oracle Fusion Middleware
Modeling and Implementation Guide for Oracle Business Process Management.
If using identity propagation to secure the Activity Guide, the properties
WorkflowAdminUser and WorkflowAdminPassword are not required.
9. In the page definition of Oracle UI Shell JSF fragment page, navigate to
pageTemplateBinding and set the Refresh property to ifNeeded.
10. Open the file adfc-config.xml.
11. Edit the file adfc-config.xml to include the location of the activity.properties
file. This should be the absolute path to the activityguide.properties file.
An example adfc-config.xml is shown in Example 16–13.
12. To enable a task flow popup with summary information, add the property
AGTasksPopupTaskFlowID to the activityguide.properties file.
Use this parameter to display a task flow summary in dynamic regions. Enter the
relevant task flow ID. If this parameter is not set, the value of OutputText is shown
as the default task summary.
13. Create a Workflow Service client configuration file. An example is shown in
Example 16–14.
<initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactor
y>
<participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>
<soapClient>
http://host:port
<identityPropagation mode="dynamic" type="saml">
<policy-references>
<policy-reference enabled="true" category="security"
uri="oracle/wss10_saml_token_client_policy"/>
</policy-references>
</identityPropagation>
</soapClient>
</server>
</workflowServicesClientConfiguration>
14. Deploy the Acitivity Guide client application with Oracle UI Shell as described in
"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:".
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. Select Project Properties.
From the Project Properties dialog, select Deployment.
4. Create a new WAR deployment profile.
5. Right-click the project and select Deploy. Deploy the project to the standalone
Oracle WebLogic Server connection created in step 1.
6. Launch the client page from a browser.
Problem
When ApplSession is not created, these problems occur:
■ User Language settings are not set.
■ Data security policies are not applied.
■ Webservice requests are run as anonymous users instead of named users.
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 16–15.
■ 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 16–15.
■ 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 through
the use of 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.
■ 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.
Problem
Clicking the Navigator in the global area shows a little white box.
This is an issue that developers would see.
Problem
The Navigator menu is showing all entries, rather than being filtered by what the user
has access to, and the Welcome page has all tabs exposed.
Solution
This is caused by menu security being turned off. This should happen only in
development environments.
Because menu security is on by default, check that the web server was not started with
-DAPPLCORE_TEST_SECURED_MENU=N.
Problem
Customizers and developers may encounter a URL that is not working.
Solution
Make sure the URL does not end with ".jspx."
Problem
A message such as "webApp <value> not defined" is displayed. This means the
application is not listed in the topology tables.
Solution
Check that the application is registered.
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:
■ Section 17.1, "Implementing Applications Tables"
■ Section 17.2, "Implementing the Applications Tree"
■ Section 17.3, "Implementing Applications Tree Tables"
■ Section 17.4, "Using the Custom Wizard with Applications Popups"
For basic information, see:
■ Chapter 13, "Getting Started with Your Web Interface"
■ Chapter 14, "Implementing the UI Shell"
■ Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-1
Implementing Applications Tables
Table 17–2 describes Applications table properties (including properties that are part
of the default managed bean), their allowable values, and default actions.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-3
Implementing Applications Tables
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-5
Implementing Applications Tables
Example 2:
Disable any of the buttons in the Applications Table
according to the functional rules or by setting
disable=false once 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 or not 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}
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-7
Implementing Applications Tables
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.
– Clicking the Delete icon deletes the selected row.
■ 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.
To allow Applications developers access to some of the implementation, the
Applications Table exposes a public class
oracle.apps.fnd.applcore.patterns.ApplicationsTableEventHandler that contains
default event handlers for all the buttons. The button methods are named as
process<buttonName>, such as processCreate and processEdit. Application
developers writing custom action handlers can also use the default implementation by
calling these methods.
Use
For example, to attach a custom button handler to the Create button, follow these
steps:
1. Define a managed bean class, as shown in Example 17–1.
Example 17–1 Defining a Managed Bean Class to Attach a Custom Handler to a Button
import oracle.apps.fnd.applcore.patterns.ui.ApplicationsTableEventHandler;
import oracle.apps.fnd.applcore.patterns.ui.util.PatternUtils;
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-9
Implementing Applications Tables
return outcome;
}
}
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. Drag and drop the data control to the JSF page.
4. In the Create context menu that is displayed, choose Applications > Table.
The Applications Table wizard is displayed.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-11
Implementing Applications Tables
– 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 EL 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 17–3.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-13
Implementing Applications Tables
2. In the Configure Table Patterns dialog, select default actions for your
Applications table (optional):
■ Create / Pattern: Creates a table row.
– Once you have chosen to enable row creation, choose a pattern from the
list to invoke an action.
– If you choose the Secondary Window 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 17–1,
" Applications Table Facets" for important information about the popup's
Cancel button.
■ Duplicate / Pattern: Duplicates the row.
– Once you have chosen to enable row duplication, choose a pattern from
the list to invoke an action.
– If you choose the Secondary Window 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 17–1,
" Applications Table Facets" for important information about the popup's
Cancel button.
■ Edit / Pattern: Enables row modification.
– Once you have chosen to enable row editing, choose a pattern from the list
to invoke an action.
– If you choose the Secondary Window pattern, click Configure Popup to
display the Applications Popup wizard (see Section 17.4, "Using the
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-15
Implementing Applications Tables
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 17–2, " 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 17–5.
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 17–2 for sample code that shows both the delete confirmation enabled
and the custom message.
Example 17–2 Sample Code Showing Delete Confirmation and Custom Message
<fnd:applicationsTable tableId="ATt2" id="AT2" confirmDelete="true"
deleteMsg="#{viewcontrollerBundle.ARE_YOU_SURE_YOU_WANT_TO_DELET}"
deleteEnabled="true" createPatternType="inline"
duplicatePatternType="inline" editPatternType="inline"
exportEnabled="true"
createText="#{viewcontrollerBundle.NEW}">
<f:facet name="additionalToolbarButtons"/>
<f:facet name="additionalActionItems"/>
<f:facet name="appsTableSecondaryToolbar"/>
<f:facet name="appsTableStatusbar"/>
<f:facet name="appsTableViewMenu"/>
<f:facet name="table">
<af:table var="row" rowBandingInterval="0" id="ATt2"
partialTriggers="::confirm ::create ::createMenuItem
::duplicate ::duplicateMenuItem">
With af:table selected in the Structure view, Figure 17–6 shows the PartialTriggers
entries in the Property Inspector view.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-17
Implementing Applications Tables
17.1.2.2.2 Multiple Row Selection on Table If multiple row selection is enabled, editing
functions will behave as shown in Table 17–3.
selectionListener="#{bindings.gsflattable1.collectionModel.makeCurrent}"
var="row" rows="#{bindings.gsflattable1.rangesize}"
emptytext="#{bindings.gsflattable1.viewable ? applcorebundle.table_empty_
text_no_rows_yet :
applcorebundle.table_empty_text_access_denied}"
fetchsize="#{bindings.gsflattable1.rangesize}"
rowbandinginterval="0" id="att3"
partialtriggers="::delete ::deletemenuitem ::create ::createmenuitem
::duplicate ::duplicatemenuitem ::selectionlistener ::selectedrowkeys"
rowselection="multiple">
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 17–8 shows the Edit All menu option and icon when the table is in the Click to
Edit mode.
Figure 17–9 shows the Click to Edit menu option and icon when the table is in the Edit
All mode.
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 17–2) on the Applications Table and does not happen
automatically.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-19
Implementing Applications Tables
selectionListener="#{bindings.ServiceRequests1.collectionModel.makeCurrent}"
rowSelection="single" id="ATt1"
partialTriggers="::confirm ::create ::createMenuItem">
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.
■ 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.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-21
Implementing Applications Tables
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 17–5 sets the partialTrigger attribute value on
the Create button icon and Create menu item
For example, you might drag and drop the data control component
TimezoneServiceAMDataControl > Timezone > Name, then choose Create >
Texts > ADF Input Text w/ Label from the context menu, as shown in
Figure 17–13.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-23
Implementing Applications Tables
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).
The resultComponentId would follow this format:
::<applicationsTableId>:_ATp:<tableId>
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-25
Implementing the Applications Tree
The properties shown in Table 17–5 are exposed on the Applications Tree.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-27
Implementing the Applications Tree
Example 17–7 Sample Markup Generated by the Applications Tree Creation Wizard
<fnd:applicationsTree treeId="tree1" id="appsTree1"
createPatternType="secondaryWindow"
createPopupId="create1,create2"
duplicatePatternType="inline"
deleteEnabled="true">
<af:tree value="#{bindings.ServiceRequestsView1.treeModel}"
var="node" rowSelection="single"
selectionListener="#{ApplicationsTreeBean.treeSelectionHandler}"
id="tree1"
partialTriggers="::duplicate ::duplicateMenuItem ::delete
::deleteMenuItem">
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:
* If No Node is selected when the Create button/menu item is clicked: The
new node is created in the first-level of the Tree.
* If Leaf Node or Expanded Parent Node is selected when the Create
button/menu item is clicked: The new node is created as a child of the
selected node, and placed directly below it.
* If Collapsed Parent Node is selected: The parent is expanded to show the
newly created child node placed directly below it.
– 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/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.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-29
Implementing the Applications Tree
– 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 the
developer needs to add custom logic to selection listener, the developer should
call this default selection listener from the custom logic. treeSelectionHandler
method of ApplicationsTreeBean provides the following behavior:
– When xxxxPatternType="secondaryWindow" and when there is no popup
configured for the level where the node needs to be created, the icon and the
menu item are disabled by default. But this behavior can be overridden by the
xxxxDisabled attribute, where "xxxx" could be create, edit or duplicate.
– Calls the ADF default tree listener:
#{bindings.xxxx.treeModel.makeCurrent}
Example 17–8 shows sample code for calling the default selection listener from the
custom selection listener.
Example 17–8 Calling the Default Selection Listener from the 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});
Use
For example, to attach a custom button handler to the Create button, follow these
steps.
Example 17–9 Defining 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;
return outcome;
}
}
Component First
Navigate to the Component Palette. Click the list of libraries and select Applications.
Drag the Applications Tree from the list of components and drop it onto the page. The
wizard will launch after dropping the Applications Tree on the page.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-31
Implementing the Applications Tree
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 Tree. 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 Tree under the Applications menu to launch the
Applications Tree wizard, as shown in Figure 17–15.
Once 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 17–17.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-33
Implementing the Applications Tree
■ 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 EL expression that selects labels to display in the tree,
such as #{label.countryLabel}.
You also can use the EL 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 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.
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,
Secondary Window, or Page).
■ Inline - Perform the action on the current table row (only available for the
Duplicate action)
■ Secondary Window - 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 Secondary
Window pattern is selected. When you click the Add button, 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.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-35
Implementing the Applications Tree
■ 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."
■ Confirmation Message: If you want to replace the default confirmation message
with a custom one, 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 confirmation message defined in a resource bundle, click the
ellipsis and choose from the list, as shown in Figure 17–4.
When finished, click OK to complete creation of the Applications Tree. Selecting
Cancel will abort the creation of the Applications Tree.
Editing - Properties
Once you have created the Applications Tree, you can modify the property values by
using the Property Inspector. You can select the Applications Tree in one of three
ways:
■ Select the component in the Design view of the page.
■ Select the <fnd:applicationsTree ...> line in the Source view of the page.
■ Select fnd:applicationTree from the hierarchy in the Structure View.
All the components created as part of the Applications Tree are editable using this
same approach, as shown in Figure 17–19.
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.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-37
Implementing Applications Tree Tables
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-39
Implementing Applications Tree Tables
Example 2:
Disable any of the buttons in the
Applications Tree Table according
to the functional rules or by setting
disable=false once 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 or not 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}
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-41
Implementing Applications Tree Tables
Note: For inline patterns, the ADF tree table beneath the
Applications Tree Table should be refreshed once the icon or the
menu item is clicked. For this to happen, the ADF tree table needs to
know that it should partially refresh itself. To do this, set the
partialTriggers attribute on the ADF tree table to the Ids of the
menu item and icon. For example, to refresh the tree table when the
Delete menu item is selected or the icon is clicked, set
partialTriggers="delete deleteMenuItem" on the ADF tree table.
The partialTriggers attribute is set by the Applications Tree Table
Creation wizard automatically. Applications developers should not
need to set it explicitly. Example 17–10 shows a sample markup that is
generated by the Applications Tree Table Creation wizard.
Example 17–10 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 17–7 shows the facets that are exposed on the Applications Tree Table.
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.
– When Create Pattern Type is secondaryWindow, a new row is created in the
data collection 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.) After the popup is
dismissed, the tree table is refreshed to display the newly-created row:
– 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.
– If Leaf Node or Expanded Parent Node is selected when the Create
button/menu item is clicked, the new row is created as a child of the
selected node and placed directly below it.
– If the Collapsed Parent Node is selected, the parent is expanded to show
the newly-created child node that placed directly below it.
– A new row is not added when the Create Pattern Type is page. Only a
standard outcome is returned
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-43
Implementing Applications Tree Tables
– 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.
– If Duplicate Pattern Type is inline, the newly-created row is placed above
the selected row.
– 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 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:
– When xxxxPatternType="secondaryWindow" and when there is no popup
configured for the level where the node needs to be created, the icon and the
menu item are disabled by default. But this behavior can be overridden by
xxxxDisabled attribute ("xxxx" could be "create", "edit" or "duplicate").
– Calls the ADF default tree listener:
#{bindings.xxxx.treeModel.makeCurrent} See Example 17–11.
Example 17–11 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});
Example
To attach a custom button handler to the Create button:
1. Define a managed bean class, as shown in Example 17–12.
Example 17–12 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;
return outcome;
}
}
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-45
Implementing Applications Tree Tables
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 17–20.
Once 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 17–22.
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 tree node or columns in
the tree table, as shown in Figure 17–23.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-47
Implementing Applications Tree Tables
When finished, click Next to proceed to the Select Tree Table Columns panel. Select
Cancel to abort the creation of the Applications Tree Table.
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, Secondary Window, Page).
■ Inline - Perform the action on the current table row.
■ Secondary Window - 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 Secondary
Window 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.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-49
Implementing Applications Tree Tables
■ 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."
■ Confirmation Message: If you want to replace the default confirmation message
with a custom one, 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 confirmation message defined in a resource bundle, click the
ellipsis and choose from the list, as shown in Figure 17–4.
Click Finish to complete creation of the Applications Tree Table. Select Cancel to abort
the creation of the Applications Tree Table.
17.3.1.2.3 Increasing Tree Table Width to Fill 100% of Its Container 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."
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
■ customized button capability
■ data binding
■ code that developers can use to invoke the popup
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-51
Using the Custom Wizard with Applications Popups
■ design-time support
■ popup facets and properties that can be customized
Popups can be used as standalone components or with the patterns shown in
Table 17–8.
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 17–27.
4. In the Create context menu that is displayed, choose Applications > Popup.
The Popup wizard is displayed.
Note: The data source for the table becomes the default data source
for the popup.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-53
Using the Custom Wizard with Applications Popups
■ The Components table is automatically populated with the data source fields.
■ In the Fields section:
– Click X to delete the selected component.
– Click + to add a component.
– 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.
– Click an entry in the Component to Use column to choose a component
from the list, as shown in Figure 17–30.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-55
Using the Custom Wizard with Applications Popups
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:
– Check the Enable Record Navigation box.
– Choose linear or non-linear navigation from the Navigation Type menu.
■ Choose View Only Content to create a read-only popup, or choose Editable
Content to allow users to edit the popup.
When you choose View Only Content, you automatically enable Slots 1 and 2.
When you choose Editable Content, you automatically enable Slots 1, 2, and 3,
as shown in Figure 17–32.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-57
Using the Custom Wizard with Applications Popups
2. Access the popup by double-clicking one of the following on the JSF page:
■ af:popup component in the Design view.
■ <af:popup...> line in the Source view.
■ af:popup entry in the Structure view hierarchy.
When you select the popup, the Popup - Property Inspector is displayed
below the page.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-59
Using the Custom Wizard with Applications Popups
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:
■ Section 18.1, "Implementing Applications Panels"
■ Section 18.2, "Implementing Applications Master-Detail"
■ Section 18.3, "Implementing Hover"
■ Section 18.4, "Implementing Applications Dialog Details"
For basic information, see:
■ Chapter 13, "Getting Started with Your Web Interface"
■ Chapter 14, "Implementing the UI Shell"
■ Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
■ 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 18–7.
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 18–1 contains attributes that are exposed for the buttons.
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 18–2 contains facets that are exposed for each panel button.
styleClass="TaskStampTextLabel"
id="ptot8"/>
<af:outputText
value="08-Nov-2007"
styleClass="AFTaskStampTextValue"
id="ptot9"/>
</af:panelGroupLayout>
<af:panelGroupLayout
layout="horizontal"
halign="right" id="ptpgl7">
<af:outputText
value="Budget Remaining"
styleClass="TaskStampTextLabel"
id="ptot10"/>
<af:outputText
value="$20,000.00"
styleClass="AFTaskStampTextValue"
id="ptot11"/>
</af:panelGroupLayout>
</af:panelGroupLayout>
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 Facet for holding the custom menu and menu af:commandMenuItem or af:group
items for the Submit button.
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.
To allow developers access to some of the implementation, the Applications Panel
exposes a public class
oracle.apps.fnd.applcore.patterns.ApplicationsPanelEventHandler that contains
default event handlers for all the buttons. The button methods are named as
process<buttonName> such as processSave and processCancel. Application
developers writing custom action handlers can also use the default implementation by
calling these methods.
return outcome;
}
6. Click Set.
2. Navigate to the data source that you want to bind to the Applications panel.
3. Drag and drop the data control to the JSF page.
4. In the Create context menu that is displayed, choose Applications > Panel.
The Applications Panel wizard is displayed.
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
Select the data source, then click OK to add it to the component. Option-
ally, 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.
c. To reorder component fields, click the up and down arrows. To delete
component fields, click the Delete icon (X). You will be able to add more
component fields later. See Section 18.1.3.4, "Adding a Data Source to an
Existing Panel."
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. 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 or
not you choose read-only. If you selected Read-only, the choices will change
from Input Text to Output Text types.
4. Click Next. The Components Layout dialog is displayed, as shown in Figure 18–5.
6. Click Next. The Page Buttons dialog is displayed, as shown in Figure 18–7.
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 18–9.
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 18–2).
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.
2. Access the panel by double-clicking one of the following on the JSF page:
■ Applications Panel component in the Design view.
■ Applications Panel line in the Source view:
fnd:applicationsPanel...
■ Applications Panel entry in the Structure view hierarchy:
fnd:applicationsPanel
When you select the panel as described in this section, the Applications Panel -
Property Inspector is displayed.
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 18–13 shows a panel's Structure view, which contains added
components.
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.
2. 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 18–2, " 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
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.
Facets
Table 18–3 shows the facets that are exposed on the Applications Master-Detail.
View Properties
See Table 17–2, " 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."
■ 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:
■ with a hide/show icon
■ without the hide/show icon
In the example in Figure 18–18, 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 18–18.
■ 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 18–19.
Configuring the Details Table Patterns is the same as configuring the Master Table
Patterns; see Figure 18–20 and step 5.
9. Click Next to display the Review panel configuration dialog, shown in
Figure 18–22.
When you click Finish, the Table/Table Master-Detail is added to the editor, and
appears similar to Figure 18–23 in Design mode.
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 18–19.
2. Click Next to display the Configure Navigation Buttons dialog, shown in
Figure 18–25.
Select the navigation buttons you want to appear on the Main form.
3. Click Next to display the Detail Header dialog, shown in Figure 18–21 for details.
4. Click Next to display the Configure Details dialog, shown in Figure 18–26.
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 18–19.
5. Click Next to display the Configure Navigation Buttons for the Detail section
dialog, shown in Figure 18–25.
6. Click Next to display the Summary dialog.
7. Click Finish to save your changes.
Your new Master-Detail displays in the JSF Page editor, shown in Figure 18–27.
Figure 18–28 Dragging from the Component Palette onto a Drop Component
<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>
Example 18–3 shows the sample markup for a table-based layout and Figure 18–31
shows an example of how the result appears.
<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>
View
Table 18–4 shows the properties that are exposed on the Applications Dialog Details.
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.
Component First
Navigate to the Component Palette. Click the list of libraries and select Applications.
Drag the Applications Dialog Details from the list of components and drop it onto the
page. The wizard will launch after dropping the Applications Dialog Details on the
page.
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 18–32.
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. Once 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.
Once 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 18–34.
Title
■ If the dialog will be read-only:
The format should be <Object Type> <Object Name> (such as Expense Report
WBJ3008D)
■ If the dialog contains editable fields:
The format should be <Action> <Object Type>: <Object Name> (such as
Approve Expense Report: WBJ3008D)
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 18–35.
■ 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.
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 is read-only, the window should be non-modal.
■ 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 18–37 shows
the default buttons in the form in the JDeveloper Design view.
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 18–38.
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 or not you
choose read-only. If you selected Read-only, the choices will change from Input
Text to Output Text types.
Editing - Properties
Once you have created the Applications Dialog Details, you can modify the property
values by using the Property Inspector. There are three ways to select the Applications
Dialog Details:
■ Select the component in the Design view of the page.
■ Select the <fnd:applicationsDialogDetails ... > line in the Source view of the
page.
■ Select fnd:applicationDialogDetails from the hierarchy in the Structure View.
All components created as part of the Applications Dialog Details are editable using
this same approach, shown in Figure 18–39.
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.
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.
Example 18–4 Example Method to Create a Managed Bean to Be the Cancel Button's
Action Listener
import org.apache.myfaces.trinidad.render.ExtendedRenderKitService;
import org.apache.myfaces.trinidad.util.Service;
import javax.faces.component.UIComponent;
"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 18–4, 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 18–5.
Example 18–5 Example Method to Create a Managed Bean to Be the OK Button's Action
Listener
import javax.el.ExpressionFactory;
import javax.el.MethodExpression;
import javax.faces.event.MethodExpressionActionListener;
methodLink = "#{pageFlowScope.PopupBean.closePopup}";
me =
ef.createMethodExpression(context.getELContext(), methodLink,
}
}
* Type - File/URL
* Last Updated By
* Last Updated 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 Manage Attachments icon. When clicked, the Attachments window is
launched showing any existing attachments as well as a new empty row at the
top of the list to allow the user to add new attachments.
– 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.
Figure 19–1 shows an example of an attachment field in a page or page segment
with 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
* Last Updated By
* Last Updated 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 Manage Attachments icon. When clicked, the Attachments window is
launched showing any existing attachments as well as a new empty row at the
top of the list to allow the user to add new attachments.
– 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.
Figure 19–2 shows an example of an attachment column in a table.
■ Attachment table:
The Attachment table can be shown in:
– A page or page segment
This occurs when you choose to display all attachments for the current record
in a table.
– A dialog
This occurs when the user clicks the Manage Attachments icon associated
with an attachment field either on a page or page segment, or an attachment
column in a table.
The following elements are rendered in the Attachment table:
– 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
– Type (required field that determines the type of Attachment)
* File (default)
* Text
* URL
* 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.
– File Name or URL (required field)
If the value is an existing attachment, a link is shown that opens the
attachment when selected. The link opens in a new browser tab or window
depending on the browser settings. For new rows:
* If Type is File, will show a file upload field
* If Type is Text, will show a text field
* If Type is URL, will show a text field
* 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.
– Last Updated By
Shows the name of the user that last updated the attachment relationship.
– Last Updated Date
Shows the date on which the attachment relationship was updated.
Figure 19–3 is an example of an Attachments table with the repositoryMode
attribute set to false.
Note: Be aware that the URLs and <class> entries cannot contain any
spaces or line breaks.
3. Create the view object representation of the business object that requires
attachments in your model project.
4. Create a Content Repository connection in JDeveloper.
Notes:
■ Attachments can support multiple Content servers.
■ Attachments stores the name of the Content Repository
connection used when creating a new attachment. This value is
then used when retrieving the attachments. It is important to
co-ordinate the naming and registration of Content Repository
connections. So that the Attachments code can connect to the
correct server to retrieve the requested file.
■ Developers need to create a Content Repository connection with
the name "FusionAppsContentRepository". This connection
should used jaxws as the socket type and Identity Propagation for
Authentication.
Also, be aware that there is an enforced maximum size for the files you can upload.
You can modify the default setting, but doing so will affect any application deployed
to the server that uses a multi-part form to upload from the desktop to Oracle
WebLogic Server. For more information, see "Setting Parameters to Upload Files to
Content Repositories" in Oracle Fusion Middleware Developer's Guide for Oracle
WebCenter Portal.
3. Click OK to access Step 1 of the Create Attachment View Link wizard, as shown in
Figure 19–5.
4. Complete the following information:
a. Select the name of the application that your view object belongs to.
b. Select the package where the attachment view link will reside.
c. Enter a unique name for the attachment view link.
5. Click Next to access Step 2. The View Object dialog appears, as shown in
Figure 19–6.
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.
Figure 19–6 Create Attachment View Link Wizard — View Object (Step 2)
7. Click Next to access Step 3. The Attachment Entity dialog appears, as shown in
Figure 19–7. The Attachment Entity is used to uniquely identify your business
object.
Figure 19–7 Create Attachment View Link Wizard — Attachment Entity (Step 3)
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. Click Next to access Step 4. The Categories dialog appears, as shown in
Figure 19–8. (The Display All Available Categories checkbox is not selected when
you first enter this page.)
Choose the categories that will be made available to the user in the Attachments
runtime UI. The categories you select here must be assigned to your attachment
entity. If they are not, they will not be visible in your UI.
Categories that you create using this wizard are inserted into the FND_DOCUMENT_
CATEGORIES and FND_DOCUMENT_CATEGORIES_TL tables against the Application that
you selected in Step 1 of the Attachment View Link wizard. Categories that you
edit are updated in the FND_DOCUMENT_CATEGORIES and FND_DOCUMENT_
CATEGORIES_TL tables.
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.2.5, "How to Assign Categories to the
Attachment Entity."
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: The end-user display name for the Category (USER_NAME from
the FND_DOCUMENT_CATEGORIES_TL table) is shown in the shuttle.
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.
Note: If you did not select the Display All Available Categories
checkbox, you must select at least one category before proceeding to
the final step in the wizard.
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.
10. Click Next to access the Application Module page. The Application Module dialog
appears, as shown in Figure 19–9. Select Application Module to create a new
instance of the view object that you selected on the View Object page, and create
an instance of the attachments view object as a child of the new instance.
11. Click Next to access the Summary page, which is shown in Figure 19–10. Review
your selections and click Finish to create your attachment view link.
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. Choose Application Navigator > AM name. Right-click and choose to open
the application module in the editor.
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. Save your changes.
where PO_INVOICES is the value that you entered in the Entity Name field in Step 3 of
the wizard.
See the " Available Seed Data Loaders" table in Chapter 56 for information about
Attachments Seed Data Loaders.
For a standard JSPX page, you must set the usesUpload property on the af:form that
contains your attachment component. For example:
<af:form usesUpload="true">
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. Once 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, and
deleteAllowed 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.
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. Open the attachment view link.
6. Link your secondary business object to the Attachments view object.
a. 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. Select the EntityName attribute (created in Step 2) in the Attachments view
object from the Destination Attribute list. Click Add to add this pair.
Repeat this for each of the AttachmentEntityName transient attributes.
d. Navigate to the Query tab, and click the Source Edit icon.
e. Modify the auto-generated Source and Destination queries to match the
appropriate Entity Names and Primary Key values Put parentheses around the
criteria that pertain to one business object and change the AND to an OR in
between each business object. Make sure your parentheses are matched
correctly, as shown in examples Example 19–9 and Example 19–10.
7. 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 19–11. (The added items are in
bold).
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.
Following is a list of some of the properties that are supported by the Attachment
component. Refer to Table 19–1 for basic descriptions of why and how each property is
used.
The most important properties to take note of are:
■ 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 or not 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.
A managed URL attachment is intended for use with pages that are hosted on internal
servers that are administered by Topology Manager. Since changes made by the
Topology Manager might invalidate the scheme://domain:port portion of a URL
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 still needs to 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 19–2 summarizes the available methods for Attachments APIs.
All methods are overloaded, providing two options for creating a new Attachment.
The first option creates the new Attachment row from the Attachment collection
linked to the parent view object. This is illustrated in Example 19–13.
The second option is to allow the method to create the Attachment row at the same
time, as shown in Example 19–14.
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.
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");
19.6.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):
For more information about task flows, see Oracle Fusion Applications Common
Implementation Guide.
The following condition (object instance set) is seeded with Oracle Fusion
attachments and can be reused by using the "Miscellaneous" category for your
product:
■ INSTANCE_SET_NAME: FNDDOCUMENTCATEGORIESFND214
■ PREDICATE: category_name = 'MISC'
5. Using the Manage Attachment Entities Setup UI, "switch on" category data
security for your attachment entity.
For more information, see Chapter 49, "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.
Note: The option is not available for all URL and Folder type
attachments, as shown in Figure 19–12. 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.
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.
■ If repositoryMode = false:
– The Check In, Check Out, and Cancel Check Out buttons are not rendered in the
Attachments table toolbar.
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.9.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:
■ Empty, indicating that the file is not checked out.
■ Displays the Oracle Fusion Applications username of the user who currently has
the file checked out.
The user name is derived from the Checked Out By value that is stored against the
file in the Content server. The stored Content Server username is mapped to the
appropriate Oracle Fusion Applications username. If the value cannot be mapped,
the Content server username is displayed in the column. This value is never stored
in the Attachments Table.
URL attachments
The following rules apply regardless of the repositoryMode value:
■ The Category, Title, and Description fields are updateable.
■ The Check Out, Check In, and Cancel Check Out functions are always disabled.
Folder attachments
If repostoryMode = true:
■ The Category, Title, and Description fields are updateable.
■ All of the update functions are disabled.
Tip: Clicking the Cancel Check Out button cancels the check out
without making any updates to the file. The check out is cancelled
immediately in the Content Repository.
2. 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 19–15.
4. Click Browse to browse your local file system. Select the updated file that you
want to upload.
5. Click OK to save your changes and close the dialog.
The selected file is uploaded to the content server. The Checked Out By column is
cleared.
6. Click Save on the Attachments Table page to commit your transaction.
Tip: If you cancel the entire transaction, the checked out status
returns to the state that it was in before the transaction took place.
Structures
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:
■ Section 20.1, "Introduction to Trees"
■ Section 20.2, "Configuring the Trees Application Launch Page"
■ Section 20.3, "Working with Tree Structures"
■ Section 20.4, "Working with Trees"
■ Section 20.5, "Working with Tree Versions"
■ Section 20.6, "Managing Labels in the Generic Label Data Source"
■ Section 20.7, "Using the Applications Hierarchy Component to Develop
Applications"
■ Section 20.8, "Integrating Custom Task Flows into the Applications Hierarchy
Component"
■ Section 20.9, "Using the fnd:hierarchy Property Inspector to Specify Tree Versions"
■ Section 20.10, "Using the Expression Builder to Bind TreeCode, TreeStructureCode,
and TreeVersionId Properties"
■ Section 20.11, "Embedding the Tree Picker Component in a User Interface"
■ Section 20.12, "Setting Bind Variables and View Criteria"
■ Section 20.13, "Using Service APIs to Manage Trees"
■ Section 20.14, "Advanced Topics"
■ Open metadata that can be read by any application that needs to use
tree-management hierarchies. This does the following:
– Minimizes the number of application programming interfaces (APIs) that need
to be written for accessing hierarchies
– Allows the sharing and understanding of hierarchies across Oracle Fusion
applications
– Allows the sharing of hierarchies with Oracle Business Intelligence reporting
and analytics systems
■ 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.
■ label - #{applcoreBundle.TASKS}
■ Task Type - defaultRegional
■ taskFlowId -
/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/Ta
sksList.xml#TasksList
■ Disclosed - true
6. At the Set Run Configuration window, click OK.
The trees application launch page opens in a browser window, as shown in
Figure 20–2.
Note: Parameter values customized at the tree level will override the
default values specified at the tree-structure level.
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
In addition to parameter values provided by the customer, tree management provides
support for those special parameters whose values for any bind variable are seeded at
runtime by tree management.
For example, to use the effectiveStartDate attribute of a tree version that a data source
uses as one of the bind variables from which the value for the effectiveStartDate bind
variable will be retrieved from the trees effective start date, you can specify a data
source parameter effectiveStartDate with the value
#{treeVersion.effectiveStartDate}. You would then you need to expose an
effectiveStartDate bind variable for the data source view object either in view criteria or
a WHERE clause.
You can specify parameters using the syntax for value and name shown in Table 20–2.
20.3.2.1.1 Example Use Case The data source DemoEmpVO has the view criteria
DemoEmpVC1, which is based on the bound values DemoEmpBV1 and
DemoEmpBV2. These are to be applied to the data source view object for tree versions
under the DEMO_EMP_TS tree structure, with varying bound values DemoEmpBV1
and DemoEmpBV2 for trees under this tree structure.
When creating the tree structure FND_DEMO_EMP_TS, the following parameters
must be added to the tree structure data source that corresponds to DemoEmpVO:
■ Parameter name: VIEW_CRITERIA_NAME
■ Parameter type: View Criteria
■ Parameter value: <name of the view criteria to be applied>, in this case
DemoEmpVC1
The following two bindings also must be added:
■ Parameter names: DemoEmpBV1 and DemoEmpBV2
■ Parameter type: Bound Value
■ Parameter value: <actual value, which can be overridden at tree level>
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 has a view criteria defined with a bind variable for special
parameters:
Data source has a WHERE clause using a bind variable for special parameters:
■ Code
■ Name
■ Status
2. Click Search.
All tree structures matching your search criteria appear in the Results area of the
page.
Clicking Advanced enables you to perform an advanced search by specifying
additional options, such as adding fields to search. You also can save your search
criteria for future use.
Clicking the down arrow displays a search field dropdown list that contains the
available values for that field. You can select from the list, or search for other values.
For example, Figure 20–14 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.
From each search field dropdown list, you can do one of the following:
■ Select a value from the list that displays.
■ Click the Search link to search for a value not in the list.
If you select a value from the list, the dropdown 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
Figure 20–15 opens:
You now can search for a value and then click OK to select it.
nodes and contain no children. In Figure 20–20, "ICs" does not have any
children, making its rooted path shorter than all the others in the hierarchy.
■ Allow Skip Level Nodes (Level, Depth, or Group only) - Specifies whether a
hierarchy can have two nodes at the same level with parent nodes at different
levels. In Figure 20–21, Washington, DC, does not have a node at the State
level.
■ 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 Figure 20–24 display.
■ 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.
■ Select a usage limit:
– None - Specifies that there are no restrictions.
– Use All Values - Specifies that all available nodes must be included in the
tree version.
■ Define Children By: Range - indicates that the hierarchy supports nodes that
are a range of values.
■ Define Children By: Foreign Key Relationship - 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 Figure 20–25.
Figure 20–27 Create Tree Structure: Specify Data Sources Page with View Object
The Create Tree Structure: Specify Performance Options page opens, as shown in
Figure 20–28.
26. Enter the name of an appropriate row-flattened table or click the down arrow to
select or search for one.
27. Enter the name of an appropriate column-flattened table or click the down arrow
to select or search for one.
28. Enter the name of an appropriate column-flattened entity object if the field does
not already contain one.
29. Click Next.
The Create Tree Structure: Specify Access Rules page opens.
Note: The Create Tree Structure: Specify Access Rules page is not yet
implemented.
3. Enter a new name for the duplicate tree structure if you want to replace the that
already displays in the field.
4. Enter a duplicate tree structure code if you want to replace the that already
displays in the field.
5. Click Save and Close to create the duplicate.
Note: The Edit Tree Structure: Specify Access Rules page is not yet
implemented.
9. Click Submit.
10. Click OK to close the Confirmation window.
To create a tree:
1. Click Create, or choose Create Tree from the Actions dropdown menu.
The Create Tree: Specify Definition page opens, as shown in Figure 20–32.
Note: Parameter values customized at the tree level will override the
default values specified at the tree-structure level.
If the page shown in Figure 20–33 opens, click Next and skip to Step 11.
If the page shown in Figure 20–34 opens, click Add in the Specify Labels area.
The Select and Add: Labels window opens, as shown in Figure 20–35.
■ Click Cancel to abort the operation and return to the top-level Manage Trees
and Tree Versions page.
■ Click Back to return to the previous page.
■ Click Next to continue to the Create Tree: Specify Access Rules page.
Note: The Create Tree: Specify Access Rules page is not yet
implemented.
To duplicate a tree:
1. Select the tree you wish to duplicate.
See Section 20.4.1, "How to Search for a Tree," if the tree you want to duplicate is
not in the current Results list.
2. Click Duplicate, or choose Duplicate from the Actions dropdown menu.
The Duplicate Tree window opens, as shown in Figure 20–36.
To edit a tree:
1. Select the tree you wish to edit.
See Section 20.4.1, "How to Search for a Tree," if the tree you want to edit is not in
the current Results list.
2. Click Edit, or choose Edit from the Actions dropdown menu.
The Edit Tree: Specify Definition page opens.
3. Do any of the following:
■ Edit the name of the tree.
■ Edit the description
■ Choose another icon image
■ Edit data-source-parameter values, if this option is available
4. Click Next.
The Edit Tree: Specify Labels page opens. The page that displays depends on
whether or not the tree structure used when creating the tree has a labeling
scheme associated with it.
Note: The Edit Tree: Access Rules page is not yet implemented.
To delete a tree:
1. Select the tree you wish to delete.
See Section 20.4.1, "How to Search for a Tree," if the tree you want to delete is not
in the current Results list.
2. Click Delete, or choose Delete from the Actions dropdown menu.
3. Confirm the deletion and click OK.
■ Edit
■ Delete
■ Set tree version status
■ Audit tree versions
Note: Since tree versions are time based, you must select a start date.
Selecting an end date is optional.
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.
9. Click OK to close the Confirmation window.
The Create Tree Version: Specify Nodes page displays, as shown in Figure 20–38.
Note: This is the default window that opens when adding a node.
■ 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.
Note: This option appears only if Define Children By: Range has
been selected on the Choose Data Source and Parameters window.
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 window shown in Figure 20–41 replaces the
default Add Tree Node window.
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 window shown in Figure 20–41 replaces the
default Add Tree Node window.
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.
Note: The referenced tree and tree version must belong to the same
tree structure.
3. Optionally, click the Preview link to ensure you have specified the correct
referenced tree version for the selected referenced tree. Figure 20–44 shows the
window that displays. Confirm the data and click OK to close the window.
own Search UI, it will be used to add and select value nodes instead of the default
Search UI.
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."
4. Select a data source and click Edit Node. The Edit Node window, shown in
Figure 20–48, opens.
Note: The actual name of the window depends on the node being
edited.
3. Highlight an existing node and click Create. The Create Tree Node window
displays, as shown in Figure 20–49.
4. Select a data source and click Continue. The Create New Record window, shown
in Figure 20–50, opens.
Note: The actual name of the window depends on the node being
created.
3. Use the steps in Section 20.5.1, "How to Create a Tree Version" as a guide to editing
the tree version.
To schedule an audit:
1. Click Schedule Audit.
The Schedule Audit window, shown in Figure 20–56, opens.
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.
Note that the flattening process specified is the one that corresponds to your
choice.
3. Click Flattening.
4. Click OK to close the Schedule Flattening confirmation window, shown in
Figure 20–59.
5. Click Done to return to the Manage Trees and Tree Versions page.
2. Click Search.
All labels matching your search criteria appear in the Results area of the page.
Clicking Advanced enables you to perform an advanced search by specifying
additional options, such as adding fields to search. You also can save your search
criteria for future use.
To create a label:
1. From the Manage Labels summary page, click Create, or choose Create Label from
the Actions dropdown menu.
The Create Label page displays, as shown in Figure 20–60.
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. Enter a short name for the label.
4. Enter a name for the label.
5. If you wish, enter a description.
6. If you wish, enter an icon name.
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 ID.
To edit a label:
1. Select the label you want to edit.
See Section 20.6.1, "How to Search for a Label," if the label is not in the current
Results list.
2. From the Manage Labels summary page, click Edit, or choose Edit from the
Actions dropdown menu.
The Edit Label page displays, shown in Figure 20–61.
To delete a label:
1. Select the label you want to delete.
See Section 20.6.1, "How to Search for a Label," if the label is not in the current
Results list.
2. From the Manage Labels summary page, click Delete, or choose Delete from the
Actions dropdown menu.
The warning page shown in Figure 20–62 displays.
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.
2. 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, as shown in Figure 20–64:
6. Run the .jspx from either the Application Navigator or the visual editor.
A browser window opens and the application runs. Figure 20–70 shows an
example of a tree table application.
The full code used to register each custom task flow in the data-source view object is
shown in the examples that follow.
Example 20–2 Search Task Flow for the Add Node Operation
<Properties>
<SchemaBasedProperties>
<fnd:SEARCH_PAGE Value="/WEB-INF/EmpSearch.xml#EmpSearchTF"/>
...
...
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.
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>
2. 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>
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>
2. 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:
List<String> pkValue = editParam.getPkValue();
In the submit() actionListener that maps to the Submit return activity, you specify
the result:
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>
2. 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>
The Hierarchy component has facets and properties, which are listed in Table 20–6 and
Table 20–7.
Note: Since only customers create tree versions, you must use service
APIs to generate lists of tree versions or active tree versions.
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.
TreeCode expression:
#{HierarchyHandler.treeModelsList[hierarchyId].treeCode}
TreeStructureCode expression:
#{HierarchyHandler.treeModelsList[hierarchyId].treeStructureCode}
TreeVersionId expression:
#{HierarchyHandler.treeModelsList[hierarchyId].treeVersionId}
Figure 20–74 shows the results window that displays when you enter a
tree-structure-code value and click Select Tree Node.
ice and allows access to tree structure metadata. This application module exposes the
TreeStructureVO under the name "TreeStructure" as well as the hierarchy of ADF
Business Components objects accessible through the TreeStructureVO. This application
module does not include any of the tree or tree version entities. The Javadoc for the
available APIs is included with JDeveloper. To access the Javadoc in JDeveloper, do the
following:
1. Choose the Go to Java Class... option from the Navigate dropdown menu.
The Go to Java Class window opens.
2. Enter TreeStructureService in the Name: field.
3. Choose Go to: > Javadoc and click OK.
This application module is considered a public API to work with tree structure
metadata and exposes the APIs shown in Table 20–8.
Tables:
■ FND_TREE_STRUCTURE
■ FND_TREE_STRUCTURE_TL
■ 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
■ FND_TREE_LOG_PARAMS
These tables are described in the sections that follow.
IS_LEAF and DISTANCE are two important row-flattening-table columns. For more
information, see Section 20.14.3.4.1 and Section 20.14.3.4.2.
20.14.3.4.1 IS_LEAF This column provides information about whether or not a tree
node is a leaf. In many instances, only a leaf contain meaningful information, while
other nodes provide a structural purpose. IS_LEAF makes it easier to differentiate a
leaf from other nodes, and makes it simpler to write simple queries and get faster
responses. Valid values are Y (yes) and N (no).
20.14.3.4.2 DISTANCE This column indicates the distance between the node and its
ancestor, which are specified in the row. For example, the distance between a node and
its parent or children is 1, between a node and its grandparent or grandchildren is 2,
and so on. DISTANCE, then, helps developers to get the entire path - from the root
node to the intermediate leaf/node without having to perform any additional queries.
A simple example is shown in Figure 20–77.
In the FND_TREE_NODE table, DISTANCE is stored in the form of an adjacency list,
as shown in Table 20–14.
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
Note: All fields not containing nodes will be filled with Null.
For more information, see "Using Business Events and the Event Delivery Network" in
Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
This chapter describes the Oracle Fusion Applications standards and guidelines for
working with localization formatting.
■ Section 21.1, "Introduction to Localization Formatting"
■ Section 21.2, "Formatting Currency"
■ Section 21.3, "Formatting Numbers"
■ Section 21.4, "Formatting Date and Timestamp Values"
■ Section 21.5, "Formatting Time Zones"
■ Section 21.6, "Formatting Numbers, Currency and Dates Using Localization
Expression Language Functions"
■ Section 21.7, "Implementing Bi-directional Support"
■ Section 21.8, "Supporting Mnemonic Keys"
■ Section 21.9, "Implementing Localization Formatting in ADF Desktop Integration"
■ Section 21.10, "Implementing Localization Formatting in Oracle BI Publisher
Reports"
■ Section 21.11, "Implementing Localization Formatting in ADF Data Visualization
Components"
■ Section 21.12, "Configuring National Language Support Attributes"
■ Section 21.13, "Standards and Guidelines for Localization Formatting"
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.
■ One is the Expression Language function fnd:currencyPattern(currencyCode)
that takes the currency code input in the context user interface as a parameter. If
JPY is input to this Expression Language function, then the number would be
formatted according to the Japanese Yen pattern: #,##0;-#,##0 without showing
any decimal digits, whereas if the same Expression Language function is used for
the US dollar input parameter, the number would be formatted according to the
USD pattern: #,##0.00;-#,##0.00. For example, the numerical value 135.6789 that is
fetched from the database needs to be shown as 135.68 USD, whereas the same
number in JPY would be shown as 136 JPY.
The syntax is:
fnd:currencyPattern(bindingToAmountCurrencyCode)
■ The other implementation to format currency values is the
fnd:currencyPatternWithPrecisionAndSymbol Expression Language function,
which is a more flexible function than fnd:currencyPattern. The
fnd:currencyPatternWithPrecisionAndSymbol function takes these input
parameters:
■ currency code to be used for formatting
■ number of precision digits required in the formatted number
■ whether the currency code or symbol is to be shown in the formatted number
The syntax is:
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 needs to 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:
Precision: Determines the use and number of decimal digits, comma placement, and
so on.
Currency symbol: Displays the standard symbol for the currency.
In this sample code, the grouping separator and decimal separator will be taken from
the user's number preferences, and the number of precision digits will be set to 2. Also,
the symbol shown will correspond to the currency code set in the af:convertNumber
tag.
<af:outputText value="#{node.Amount}" id="ot28">
<af:convertNumber type="currency"
currencyCode="#{bindings.CurrencyCode.attributeValue}"
pattern="#{fnd:currencyPatternWithPrecisionAndSymbol(bindings.CurrencyCode.attribu
teValue,2,'symbol'}"/>
</af:outputText>
The fields Ordered, Total Tax, and Total in FIGURE1 show how currency values are
formatted in Oracle Fusion Applications.
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 this sample code.
<af:outputText label="Amount" value="#{bindingToOrderTotal}">
<af:convertNumber type="currency"
currencyCode="#{bindingToAmountCurrencyCode}"
pattern="#{fnd:currencyPattern(bindingToAmountCurrencyCode)}" />
<af:outputText>
a user might choose that the grouping separator has to be shown once every three
digits with a maximum of three decimal digits (#,##0.###). An example is a value of
1234.5 in the database that might have to be displayed as 1 234,500 or 1,234.500 or
1.234,500.
Input decimal fields should be formatted according to the user's number preferences.
In this sample code, use the <af:convertNumber pattern... entry to retrieve the
number formatting pattern from the applCorePrefs bean.
<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 21–2 is an example of a number field that is
formatted according to the user's number formatting preferences.
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 should be used 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)
■ fnd:formatNumber2(java.lang.Number decimalValueToBeFormatted, int
maximumNumberOfFractionDigits)
This sample code shows how to use these two functions for decimal number
formatting.
<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'}"/>
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 this sample, use the
<af:convertNumber pattern... entry to retrieve the number formatting pattern from
the applCorePrefs bean.
<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>
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 should be
used 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:
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
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 21–4 corresponds to the output ID field shown in
the above sample code.
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 this example indicates that the number
formatting pattern is being retrieved from the applCorePrefs bean.
<af:inputText value="#{bindings.SequenceNumber.inputValue}"
label="#{bindings.SequenceNumber.hints.label}"
required="#{bindings.SequenceNumber.hints.mandatory}"
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 field Sequence in Figure 21–5 corresponds to the input ID field shown in the above
sample code.
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.
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 21–2.
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 an commandLink using the
fnd:formatNumber2 Expression Language function is shown in Example 21–3.
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 21–1. 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 21–2 using the fnd:formatNumber function is shown in
Example 21–4:
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 21–2.
In Oracle Fusion applications, you must not hardcode the % sign in the value attribute
of the outputText tag, because this makes the percentage values locale-insensitive.
The Percent of Project Work Complete field in Figure 21–6 corresponds to the output
percentage field shown in Example 21–5.
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 21–6.
Both the filter for the date and the date field should be formatted according to the
user's date formatting preferences. If this is not done, the dates will not be displayed
according to the user's preferences.
The values for the Due Date field in Figure 21–7 are examples of how a date value is
formatted according to the user's preferences in Oracle Fusion Applications.
This sample shows how to display the current date in the JSF page.
<af:inputDate binding="#{localDateBean.currentLocalDate}"
value="#{bindings.StartDate.inputValue}"
label="#{bindings.StartDate.hints.label}(Type: java.sql.Date)"
required="#{bindings.StartDate.hints.mandatory}"
shortDesc="#{bindings.StartDate.hints.tooltip}"
id="id1">
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
</af:inputDate>
This workaround can be used only if there is no middleware tier validation for the
date field. For example, if the middleware tier validation has a condition that the date
field's value cannot be more than the middleware tier's system time, the conversion
with the above method will generate a validation error. In such cases, you would need
the ATG enhancement to convert the server time zone date to the user's preferred time
zone.
The Required Date field in Figure 21–8 should default to the user's preferred time-zone
rather than the server time-zone.
Note that there is a single space between the two Expression Language
expressions.
■ Pattern 3
pattern="#{applCorePrefs.DateFormatPattern}
#{applCorePrefs.timeFormatPatternWithoutSeconds}"
Note that there is a single space between the two Expression Language
expressions.
This pattern is applicable if it does not need to display the Seconds part of a
date-time value.
Both the filter for the date-time and the date-time field should be formatted according
to the user's date and time formatting preferences, as shown in this sample code. If this
is not done, these fields will not be processed according to the user's preferences.
<af:column sortProperty="LastUpdateDate" filterable="true"
sortable="true"
headerText="#{bindings.NlsOrders1.hints.LastUpdateDate.label}"
id="c1">
<f:facet name="filter">
<af:inputDate value="#{vs.filterCriteria.LastUpdateDate}"
id="id8" >
<af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/>
</af:inputDate>
</f:facet>
<af:inputDate value="#{row.bindings.LastUpdateDate.inputValue}"
label="#{bindings.NlsOrders1.hints.LastUpdateDate.label}"
required="#{bindings.NlsOrders1.hints.LastUpdateDate.mandatory}"
shortDesc="#{bindings.NlsOrders1.hints.LastUpdateDate.tooltip}"
id="id1">
<f:validator binding="#{row.bindings.LastUpdateDate.validator}"/>
<af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/>
</af:inputDate>
</af:column>
The Last Saved field at the top right of Figure 21–9 is an example of how a date-time is
formatted according to the user's preferences in Oracle Fusion Applications.
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).
This is to say that nothing needs to be explicitly added into the automatically
generated af:convertDateTime tag.
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
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 21–8:
required="#{bindings.InvoiceDate.hints.mandatory}"
shortDesc="#{bindings.InvoiceDate.hints.tooltip}"
showRequired="true" autoSubmit="true"
valueChangeListener="#{pageFlowScope.invoiceActionsBean.invoiceDateValueChangeList
ener}"
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 21–9.
In Figure 21–11, 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.
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.
This should be used only for invariant timestamp values. Invariant timestamp values
are timestamps in which varying Timezone will not make a difference to the business
logic of the application.
<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.
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 21–11, the
dateValue object must be converted to a String object by calling the toString()
method.
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:
■ Number and currency objects:
– java.math.BigDecimal
– java.lang.Integer
– java.lang.Long
■ Date and DateTime (Timestamp) objects:
– 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 21–13.
Returns the formatted number value using the user preferences for the number format
mask, grouping separator and decimal separator.
Overrides the scale—the number of digits following the decimal point—of the user
preferred number format pattern using the value assigned to maxFractionDigit.
This function produces the tag shown in Example 21–15.
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 21–17.
Returns the formatted date value based on the user preferred date format mask.
This function produces the tag shown in Example 21–19.
Use the Expression Language function shown in Example 21–20 to format date time
values.
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 21–21.
Use the Expression Language function shown in Example 21–22 to format date time
values with user formatting masks and the user-specified time zone.
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 21–23.
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 21–24.
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.
actionListener="#{ItemRelationshipRegionalSearchBean.onAdvancedButtonClick}"
id="cb4"/>
<af:spacer width="8" height="10" id="s7"/>
<af:image source="/images/seperator_img.png" id="i2" shortDesc=""/>
<af:spacer width="8" height="10" id="s8"/>
<af:commandButton
textAndAccessKey="#{ResourcesGenBundle['Action.Search1']}" id="cb5"
actionListener="#{ItemRelationshipRegionalSearchBean.onRegionalAreaSearchClick}
"/>
<af:spacer width="5" height="10" id="s9"/>
<af:commandButton text="#{ResourcesGenBundle['Action.Reset']}"
id="cb6"
actionListener="#{ItemRelationshipRegionalSearchBean.onResetBtnClick}"/>
<af:spacer width="5" height="10" id="s10"/>
</af:panelGroupLayout>
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 21–12, the panel containing the three buttons
Advanced, Search and Reset is aligned to the right.
Therefore, the expected behavior is that, in the Arabic locale shown in Figure 21–13,
the panel, with the buttons' text in Arabic, is aligned to the left.
Figure 21–15 shows how the command image link supports bi-directional behavior in
an Arabic locale.
How to use the textAndAccessKey attribute using the resource bundles is shown in
Example 21–28.
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 21–29 shows how to externalize the accessKey attribute using the
applCoreBundle.
Example 21–30 shows how to externalize the accessKey attribute using a resource
bundle.
Here, the accessKey attribute has been externalized and is read from the applCore
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:
■ When a textAndAccessKey attribute has a value with more than
one "&", the letter following the first "&" is chosen as the access
key.
■ When an accessKey attribute has more than one letter, the first
letter is chosen as the access key.
In Figure 21–16, the buttons on the top right are examples of buttons with soft keys
that must not be hardcoded, so that they can be different for different locales.
■ 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 grouping separator in the number values, make sure that
Use 1000 Separator is checked, as shown in Figure 21–19.
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.
■ 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 Text category.
■ Click OK. In the Style dialog, Figure 21–20 shows that @ is defined as the Number
style.
■ 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, you should display the currency symbol in a
separate cell. Make sure None is selected for Symbol, as shown in Figure 21–22.
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.
■ Click OK and save the file.
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.
■ Select the Advanced tab and enter format code, as shown in Figure 21–25.
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 BI Publisher and Oracle Fusion application integration environment, if
format-number is used to format a number, whether or not 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 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.
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'?>
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 'USD' is passed to CurrencyCode_Field at runtime, the value displayed is
1,234,567.89.
■ If 'JPY' is passed to CurrencyCode_Field at runtime, the value displayed is
1,234,568.
■ If 'INR' is passed to CurrencyCode_Field at runtime, the value displayed is
12,34,567.89.
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:
■ If 'USD' is passed to CurrencyCode_Field at runtime, the value displayed is
1'234'567,89.
■ If 'JPY' is passed to CurrencyCode_Field at runtime, the value displayed is
1'234'568.
■ If 'INR' is passed to CurrencyCode_Field at runtime, the value displayed is
12'34'567,89.
Follow these steps to format a currency field in the BI Publisher RTF template.
■ Open the RTF template file with Word.
■ Expand BI Publisher > Sample XML and select a sample XML file that contains
sample data for the number fields to be formatted in the RTF template.
■ Double-click the currency field to be modified (for instance ORDER_TOTAL). In
the BI Publisher Properties dialog, click the Properties tab and make sure Type is
set to Regular Text.
■ Click the Advanced tab and enter format code, as shown in Figure 21–28.
Note: If the time component and time zone offset are not included in
the XML source date, BI Publisher assumes it represents 12:00 AM
UTC (that is, YYYY-MM-DDT00:00:00-00:00).
Figure 21–29 Selecting Date and Time Format in Oracle Fusion Application Preferences
■ <?format-date:xdoxslt:sysdate_as_xsdformat();'MEDIUM'?>
For more abstract format masks, see "Oracle Abstract Format Masks" in "Number,
Date, and Currency Formatting" in the Oracle Fusion Middleware Report Designer's Guide
for Oracle Business Intelligence Publisher.
With using abstract format masks, date and timestamp values are formatted according
to the default format of the Oracle Fusion application user's locale.
<dvt:markerText><dvt:y1Format>
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
</dvt:y1Format></dvt:markerText>
In Figure 21–31, 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.
In Figure 21–32, 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.
Table 21–1 Using af:convertNumber for Number Formatting and dvt:attributeFormat for Text Formatting
Is dvt:attributeFormat Needed
Graph Type Parent Tags for af:convertNumber for Number Formatting?
Bar Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes (for O1 axis)
<dvt:y1Format>, and <dvt:y2Format>
Bar Horizontal <dvt:y1TickLabel>, <dvt:y2TickLabel> Yes (for O1 axis)
,<dvt:y1Format>, and <dvt:y2Format>
Bubble Graph <dvt:x1TickLabel>, <dvt:y1TickLabel>, Yes (but not for O1 axis, for X1
<dvt:y2TickLabel>, <dvt:x1Format>, axis)
<dvt:y1Format>, <dvt:y2Format> and
<dvt:zFormat>
Combination graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes (for O1 axis)
<dvt:y1Format>, and <dvt:y2Format>
Funnel Graph <dvt:sliceLabel> Yes (for funnel section values)
Line Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes (for O1 axis)
<dvt:y1Format>, and <dvt:y2Format>
Pareto Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, and Yes (for O1 axis)
<dvt:y1Format>
Pie Graph <dvt:sliceLabel> Yes (for slice values)
Pie Bar Charts <dvt:y1TickLabel>, <dvt:sliceLabel> and Yes (for slice values)
<dvt:y1format>
Gantt Chart <af:column> Yes (for O1 axis)
Gauge <dvt:metricLabel> and <dvt:tickLabel> Yes (for O1 axis)
ADF Pivot Table <af:inputText> or <af:outputText> whose
parent tag is <dvt:dataCell>
<af:inputText> or <af:outputText> whose
parent tag is <dvt:headerCell>
In Figure 21–33, 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.)
Table 21–2 Using af:convertNumber for Currency Formatting and dvt:attributeFormat for Text Formatting
Can dvt:attributeFormat Be Added for
Tags in which af:convertNumber Can Currency Formatting of Attributes on the
Graph Type Be Added for Currency Formatting Ordinal Axis?
Bar Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes
<dvt:y1Format>, and <dvt:y2Format>
Bar Horizontal <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes
<dvt:y1Format>, and <dvt:y2Format>
Bubble Graph <dvt:x1TickLabel>, <dvt:y1TickLabel>, Yes (but not for O1 axis, for X1 axis)
<dvt:y2TickLabel>,<dvt:x1Format>,
<dvt:y1Format>, <dvt:y2Format> and
<dvt:zFormat>
Combination Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes
<dvt:y1Format>, and <dvt:y2Format>
Funnel Graph <dvt:sliceLabel> Yes (for funnel section values)
Line Graph <dvt:y1TickLabel>, <dvt:y2TickLabel>, Yes
<dvt:y1Format>, and <dvt:y2Format>
Pareto Graph <dvt:y1TickLabel>, Yes
<dvt:y2TickLabel>,and <dvt:y1Format>
Pie Graph <dvt:sliceLabel> Yes (for slice values)
Pie Bar Charts <dvt:y1TickLabel>, <dvt:sliceLabel> and Yes (for slice values)
<dvt:y1format>
Gantt Chart <af:column> No
Gauge <dvt:metricLabel> and <dvt:tickLabel> No
ADF Pivot Table <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:
■ If there is a single categorical Date attribute being displayed on
the O1Axis, the graph displays a TimeAxis instead of the typical
O1 / Ordinal Axis. The TimeAxis will show dates in a hierarchical
format instead of as a single label on an O1 Axis, for example June
27, 2001. To show a single label on the O1 Axis, the TimeAxis
should be turned off (timeAxisType="TAT_OFF") and a
<dvt:attributeFormat> should be used to specify the date format.
■ The Area graph displays a time axis when dates (object type
java.util.Date) are specified for the column labels. Several
timeXXX attributes are defined on the graph tag to customize the
time axis. The child tag timeAxisDateFormat controls the format
in which the time axis labels are displayed.
<dvt:timeAxisDateFormat dayFormat="DAY_OF_MONTH"
monthFormat="MONTH_LONG"
quarterFormat="NONE" yearFormat="YEAR_LONG"
timeFormat="HOUR_MINUTE_SECOND"/>
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 21–34, 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.
Table 21–3 Using af:convertDateTime for Date and Timestamp Formatting Formatting
Graph Type Is dvt:attributeFormat Required?
Bar Graph Yes
Bar Horizontal Yes
Bubble Graph Yes
Combination Graph Yes
Funnel Graph Yes (for funnel section values
Line Graph Yes
Pareto Graph Yes
Pie Graph Yes
Pie Bar Charts Yes
Gantt Chart No (Add af:convertDateTime as a child tag of af:column)
Gauge N/A
ADF Pivot Table <af:inputText>/<af:outputText> whose parent tag is <dvt:dataCell>
<af:inputText>/<af:outputText> whose parent tag is <dvt:headerCell>
regional or territorial number and date formats. Typically, in order 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.
Table 21–5 lists language and territory values used with NLS attributes.
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 21–6 lists the following:
■ Database attribute: The database NLS session parameter name.
■ Associated session attribute: The Oracle Fusion Applications NLS session
attribute name related to the database attribute name, if one exists. If the attributes
are indeed related, configuring a value for the Oracle Fusion Applications NLS
session attribute results in an ALTER SESSION in the database layer.
■ Default value: The default value of the attribute. This value is configured both in
the database and init.ora as the database default.
■ Alter Session: Indicates whether an ALTER SESSION is created in the database.
When an ALTER SESSION initiates at session creation or attachment, execute NLS_
LANGUAGE and NLS_TERRITORY first, as these may affect other attributes.
– Create: An ALTER SESSION is created once, when the connection is first
created.
– 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.
This part of the Developer's Guide discusses how to use descriptive, extensible, and
key flexfields to develop Oracle Fusion applications that can be customized by
application implementors and administrators without programming.
Getting Started with Flexfields introduces flexfield concepts and features, including the
development process, development roles, and how flexfields appear in the user
interface.
Using Descriptive Flexfields discusses the descriptive flexfield concepts and features, the
development process, how to incorporate descriptive flexfields in user interface (UI)
tables, forms, and query panels, and how to use descriptive flexfields with Oracle
Business Intelligence, web services, and ADF Desktop Integration.
Using Extensible Flexfields discusses the extensible flexfield concepts and features, the
development process, contexts, dedicated tables and views, how to employ extensible
flexfields on an application page, how to programmatically access business component
information, and how to customize the runtime modeler.
Using Key Flexfields discusses the key flexfield concepts and features, the development
process, producer and consumer development activities, how to incorporate key
flexfields in UI tables and forms, and how to define and access key flexfield
combination filters.
Testing and Deploying Flexfields discusses how to test your flexfield business
components using Integrated WebLogic Server, how to deploy your flexfield
application to a standalone instance of WebLogic Server to test the full lifecycle, how
to regenerate flexfield business components programmatically, and how to make
flexfield setup task flows accessible from Oracle Fusion Functional Setup Manager.
This part contains the following chapters:
■ Chapter 22, "Getting Started with Flexfields"
■ Chapter 23, "Using Descriptive Flexfields"
■ Chapter 24, "Using Extensible Flexfields"
■ Chapter 25, "Using Key Flexfields"
■ Chapter 26, "Testing and Deploying Flexfields"
22
Getting Started with Flexfields
22
This chapter discusses the basics of using flexfields to enable customers to add custom
attributes to business objects in their Oracle Fusion applications.
This chapter includes the following sections:
■ Section 22.1, "Introduction to Flexfields"
■ Section 22.2, "Participant Roles"
■ Section 22.3, "The Flexfield Development Life Cycle"
■ Section 22.4, "Flexfields in the Application User Interface"
validated, and configure how the attributes are displayed. For more information,
see Section 22.1.1, "Descriptive Flexfields."
■ Extensible: An extensible flexfield is similar to a descriptive flexfield, but with the
following additional features:.
– The number of configurable segments is not fixed. That is the number of
segments is extensible.
– Attributes can be grouped into contexts so they will always be presented
together in the application user interface.
– Hierarchical categories enable you to reuse contexts for similar entities.
– Extensible flexfields support one-to-many relationships between the entity
and the extended attribute rows.
For more information, see Section 22.1.2, "Extensible Flexfields."
■ Key: Key flexfields enable customers to use their own coding scheme or naming
scheme customers to identify their business entities by giving implementors the
ability to configure business entities to be identified using flexible, multi-part,
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 can
be implemented to represent part numbers and account numbers. Key flexfields
are never optional; customers must configure them for the product to operate
correctly.
For more information, see Section 22.1.3, "Key Flexfields."
To better understand flexfields and the differences between descriptive flexfields,
extensible flexfields, and key flexfields, it is important to understand flexfield
structures and contexts.
■ Structure: A flexfield structure is a specific configuration of segments. If you add
or remove segments, or rearrange the order of segments in a flexfield, you produce
a different structure. In some applications, different end users need to see
individually tailored segment structures for the same flexfield; for example, the
correctly formatted local postal address for customer service inquiries, which
would change based on the user's locale.
Your flexfield can display different segments and prompts for different end users
based on a data condition in your application data, such as the user's role or a
value entered by the user. All types of flexfields allow for multiple structures. All
the segments that you might need to use to create all the anticipated structures
must be defined as part of the flexfield.
■ Contexts: Descriptive and extensible flexfield segments are context-sensitive — they
are varied or made available in your application by implementors to reflect the
needs of the organization for which the application is being configured.
Segments are made available to an application as groups of attributes called
contexts. Each context is defined as part of a flexfield, and is comprised of a set of
context-sensitive segments that store a particular type of related information. The
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
might consist of segments that represent height, width and depth. The
implementor can also define a Measurements context, which contains segments
that reuse the same underlying height, width and depth columns, and which also
includes segments for weight, volume and density.
category and a TV category, and so on. The Home Entertainment product might have
contexts that specify voltage, dimensions, inputs and outputs. Contexts are reusable
within a given extensible flexfield. For example, the dimensions context could be
assigned to any category that needs to include dimensional information.
Owner
The flexfield 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.
■ 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.
■ Consumer: A key flexfield consumer incorporates a flexfield into an application.
The consumer typically stores segment values or combination IDs (CCID) on a
transaction table, and works with the structural and seed data and the business
components that have been configured by the flexfield producer.
Implementor
A flexfield implementor is 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 assumes the role of implementor.
3. For descriptive and key flexfields, link the flexfield business components to the
application's business components.
4. Incorporate the flexfield into UI pages.
5. Define sample flexfield data and use it to test the flexfield.
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 (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 planning and implementing flexfield configuration, such as defining structures,
contexts, attributes, labels, behavior, and associated value sets, see the "Using
Flexfields for Custom Attributes" chapter in the Oracle Fusion Applications Extensibility
Guide.
Note: You must use the specified tools throughout the development
lifecycle to create and update the flexfield metadata and product
tables. Do not use database tools unless you are instructed to do so. If
you use database tools instead of the specified tools, you risk
destroying data integrity and you lose the ability to audit changes to
the data.
Because Oracle Fusion Applications tables are interrelated, any
changes that you make using the specified tools, such as building
business components or UI forms, can update many tables at once. If
you do not use the specified tools, you might not update all the
necessary tables. In addition, most of these tools perform validation
and change tracking.
If tables are not properly synchronized, you risk unpredictable results
throughout Oracle Fusion Applications products.
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.1, "Introduction to Descriptive Flexfields"
■ Section 23.2, "Developing Descriptive Flexfields"
■ Section 23.3, "Creating Descriptive Flexfield Business Components"
■ Section 23.4, "Creating Descriptive Flexfield View Links"
■ 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"
■ Section 23.7, "Adding Descriptive Flexfield UI Components to a Page"
■ Section 23.8, "Configuring Descriptive Flexfield UI Components"
■ Section 23.9, "Loading Seed Data"
■ Section 23.10, "Working with Descriptive Flexfield UI Programmatically"
■ Section 23.11, "Incorporating Descriptive Flexfield into a Search Form"
■ Section 23.12, "Preparing Descriptive Flexfield Business Components for Oracle
Business Intelligence"
■ Section 23.13, "Publishing Descriptive Flexfields as Web Services"
■ Section 23.14, "Accessing Descriptive Flexfields from an ADF Desktop Integration
Excel Workbook"
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."
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 learn how implementors configure descriptive flexfields to meet customer's
needs, see the "Using Flexfields for Custom Attributes" chapter in the Oracle Fusion
Applications Extensibility Guide.
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. Create descriptive flexfield business components.
See Section 23.3, "Creating Descriptive Flexfield Business Components".
Tip: After completing this step, you can regenerate the flexfield
business components programmatically at runtime to update your
descriptive flexfield implementation without manual intervention.
For more information, see Section 26.4, "Regenerating Flexfield
Business Components Programmatically".
3. 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. Nest the descriptive flexfield application module instance in the application
module.
See Section 23.5, "Nesting the Descriptive Flexfield Application Module Instance in
the Application Module".
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. Add the descriptive flexfield usage to the appropriate application pages.
See Section 23.7, "Adding Descriptive Flexfield UI Components to a Page".
7. Configure the descriptive flexfield UI components.
See Section 23.8, "Configuring Descriptive Flexfield UI Components".
8. Load any necessary application seed data, such as error messages or lookup
values.
See Section 23.9, "Loading Seed Data."
After implementing a flexfield, you can define seed or test value sets for the flexfield,
and you can create a model that you can use to test it. For more information, see
Section 26.1.2, "How to Test 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 planning and
implementing flexfield configuration, such as defining attributes, labels, behavior, and
associated value sets, see the "Using Flexfields for Custom Attributes" chapter in the
Oracle Fusion Applications Extensibility Guide.
To make the Manage Descriptive Flexfields task flows available to implementors,
register them with the Oracle Fusion Functional Setup Manager. For more
information, see Section 26.5, "Integrating Flexfield Task Flows into Oracle Fusion
Functional Setup Manager".
View Rows" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework. In a polymorphic collection of rows, 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 should be used.
Given a collection of polymorphic view rows, each row can be a different type.
The attribute sets that are associated with the discriminator are predefined. In fact,
Oracle ADF enables each view row to have its own view definition. When a
polymorphic collection of rows is created, Oracle ADF selects a view definition for the
row to be added based on the value of the discriminator attribute.
Descriptive flexfield segments are exposed as view row attributes in the order that
they are defined in the flexfield's metadata. Global segments are exposed as attributes
in the base view object of the polymorphic collection. Every context is modeled as an
extended view object of the base view object. That is, an extended view object is
created for every context value. These extended view objects, which are referred to as
subtype view objects, expose context-sensitive segments as subtype-specific view
attributes. The context segment is exposed as the discriminator attribute of the
polymorphic view rows.
You use a wizard to generate a polymorphic base view object that is based on the
descriptive flexfield definition, then create a view link to connect the product view
object and the base view object. You can then use the base view object to add the
flexfield to a UI page. For more information about the generation of base and subtype
view objects, see Section 23.3, "Creating Descriptive Flexfield Business Components."
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.
columns as flexfield segments. After you have registered a flexfield, you can reuse the
flexfield with other product tables.
To complete the process for developing a descriptive flexfield:
1. Add extension columns to the product table.
2. Register the flexfield and define its metadata and master usage. You can register
the flexfield using a registration task or using procedures from the FND_FLEX_DF_
SETUP_APIS PL/SQL package.
3. Optionally reuse the flexfield by adding the same set of extension columns to
other product tables.
4. Register all secondary usages using either a registration task or procedures from
the FND_FLEX_DF_SETUP_APIS PL/SQL package.
5. Register the entity details for each usage.
6. Register flexfield parameters to identify values that are obtained from external
reference data sources, such as different database columns, constant values, or
session attributes. You can register the parameters using a registration task or
using the procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
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 57, "Using the
Database Schema Deployment Framework."
Tip: You can also define and register a flexfield using the FND_FLEX_
DF_SETUP_APIS PL/SQL package, as described in Section 23.2.2.2,
"Registering and Defining Descriptive Flexfields Using the Setup
APIs.".
11. Select Context Segment from the Column Usage Type dropdown list.
12. From the Column Name dropdown list, select the database column that you want
to map to the flexfield's context segment. The column must be of type VARCHAR2.
13. Repeat the following steps for each table column that you want to map to a
flexfield segment, as shown in Figure 23–3:
a. In the Column Details tab, choose Actions > New.
b. Select Segment from the Column Usage Type dropdown list.
c. Select the database column from the Column Name dropdown list that you
want to map to a segment of the flexfield.
15. You can register the entity details now or later. However, this step must be
completed before you can generate the flexfield usage's business components. For
more information, see Section 23.2.5, "How to Register Entity Details."
16. (Optionally) Register secondary usages of the flexfield as described in
Section 23.2.4, "How to Register the Reuse of a Descriptive Flexfield."
23.2.2.2 Registering and Defining Descriptive Flexfields Using the Setup APIs
In addition to using a registration task, as described in Section 23.2.2.1, "Registering
and Defining Descriptive Flexfields Using a Registration Task," 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."
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
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 57, "Using the
Database Schema Deployment Framework."
Tip: You can also register the secondary usage of a flexfield using the
FND_FLEX_DF_SETUP_APIS PL/SQL package, as described in
Section 23.2.4.2, "Registering the Secondary Usage of a Descriptive
Flexfield Using the Setup APIs.".
■ Column Name Prefix: If you used a prefix for the flexfield column names,
enter the prefix.
■ Description: Provide a short description of the flexfield usage.
6. Click Save and Close.
7. You can register the entity details now or later. However, this step must be
completed before you can generate the flexfield usage's business components. For
more information, see Section 23.2.5, "How to Register Entity Details."
Tip: You can also register entity details using the FND_FLEX_DF_
SETUP_APIS PL/SQL package, as described in Section 23.2.4.2,
"Registering the Secondary Usage of a Descriptive Flexfield Using the
Setup APIs."
5. If no row exists in the Entity Details section, choose Actions > New to create a
row.
6. Set the following values:
■ Entity Object: Provide the full class name of the table's entity object.
■ 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.
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.hcm.payroll.flex.dff1, then
you cannot define the oracle.apps.hcm.payroll.flex package for
another usage, because that package would then identify both usages.
Instead, you could use oracle.apps.hcm.payroll.flex.dff2.
Product View
C1 C2 Primary Key
Object
View link
extends
Flexfield
View Objects
Primary Key G1 G2 Context: v2 Y _v2_VO
Product Entity
C1 C2 Primary Key A1 A2 A3 A4 A5
Object
No Java implementation classes are generated for descriptive flexfield view objects.
The product view object may or may not have Java implementation classes.
– 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."
Note: The role referred to here is not a role in the security sense. It
exists only during this procedure, for the purpose of specifying where
your generated flexfield business components should be stored.
12. On the Entity Object page, expand the tree of available models and select an entity
object to use as the data source for the descriptive flexfield, as shown in
Figure 23–8.
Figure 23–8 Create Flexfield Business Components Wizard — Entity Object Page
The entity object you select must include all of the attributes representing the
columns that are reserved for the descriptive flexfield.
Descriptive flexfield attributes will be validated by the entity object along with its
other attributes.
13. If you want to select an entity object for which the descriptive flexfield attributes
are defined as transient (not based on database table columns), then select the
checkbox labeled Use the entity attributes named after their corresponding
flexfield database columns. This checkbox is not selected by default.
When an attribute of a descriptive flexfield entity object is transient, there is no
matching underlying column name. When you select this checkbox, 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 master 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."
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.
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.
17. When all of the defined parameters are mapped, click Next.
19. 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.
2. Create the flexfield business components for the descriptive flexfield as described
in Section 23.3.1, "How to Create Descriptive Flexfield Business Components".
2. In the New Gallery, go to Business Tier > ADF Business Components and select
Flexfield View Link.
3. Click OK to access the Create Flexfield View Link wizard, as shown in
Figure 23–10.
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.
Figure 23–11 Create Flexfield View Link Wizard — View Objects Page
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.
10. Click Next.
Note: You can skip the Properties page because view link-specific
properties are not supported.
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.
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.
Note: You can also use descriptive flexfields in the following ways:
■ Incorporate descriptive flexfield view object attributes as search
criteria in an advanced query search form.
See Section 23.11, "Incorporating Descriptive Flexfield into a
Search Form".
■ Use ADF Desktop Integration to incorporate descriptive flexfields
into an Excel workbook.
See Section 23.14, "Accessing Descriptive Flexfields from an ADF
Desktop Integration Excel Workbook".
To add a descriptive flexfield UI component, you add the component to a page in the
one of the following configurations:
■ As part of a form component.
■ As part of a table component, with the context-sensitive segments of the flexfield
presented in a detailStamp facet. This is the typical configuration, which allows
for the full range of possible values in the context segment.
■ As part of a table component, with context-sensitive segments of the flexfield
presented as columns. To use this configuration, you must guarantee that the
flexfield context segment will have the same value in all rows of the table.
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.
Note: 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 about the data-first approach, see the "Introduction
to Placeholder Controls" section in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework
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 23–14 Flexfield View Object Nested Under Master View Object
4. Drag the flexfield view object onto a form, and select the appropriate flexfield UI
component.
Tips:
■ 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.10.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.
5. 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.
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 23–15, 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.
5. Create a detail region (detailStamp facet) if the table does not have one, as shown
in Figure 23–16.
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 23–17; this creates fields for the
context-sensitive segments.
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.
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 23–15, and select Oracle Descriptive Flexfield Column as the UI
component. This creates the base flexfield column in the table.
5. Edit the JSP source code for this page, and remove the following attribute from the
<fnd:descriptiveFlexfield> tag:
mode="global"
6. Add an additional 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.
coreVORow.setNewRowState(Row.STATUS_NEW);
}
Caution:
■ 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".
The significant properties on the Common, Data, Style and Behavior property tabs are
listed in Table 23–1.
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.
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.
in applications. Flexfield seed data can be uploaded and extracted using the Seed Data
Loader.
After you complete the registration process described in Section 23.2.2, "How to
Register and Define Descriptive 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 the role of 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.
For information about extracting and loading seed data, see Chapter 56, "Initializing
Oracle Fusion Application Data Using the Seed Data Loader".
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.10.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.
You register a value change listener to capture any ValueChangeEvent that occurs. When
an end user changes a segment value, the input components associated with the
flexfield segments on the application page deliver a value change event, and the
listener is called.
2. Specify the handler method as UI metadata on the flexfield's value change listener
property (described in Table 23–1). 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 23–8 is an example of the
metadata as an EL expression that identifies the dffChangeListener listener from
the Java method in Example 23–7.
For more information about handling value change events, see the "Using Input
Components and Defining Forms" chapter inOracle Fusion Middleware Web User
Interface Developer's Guide for Oracle Application Development Framework.
Figure 23–21 Edit Query Criteria Tab of View Object View Criteria Definition
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.
2. Create a new JSPX page in the user interface project.
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 a Query Panel with results, as
shown in Figure 23–22.
5. 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 23–23.
Note: Figure 23–6 illustrates the attributes associated with the base
descriptive flexfield view object (global segments) and the
context-sensitive attributes.
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.
...
<ReadOnlyFlag>N</ReadOnlyFlag>
<BIEnabledFlag>Y</BIEnabledFlag>
...
</Segment>
...
</Context>
...
<Context>
<ContextCode>VS_FRM_CHR_ON_CHR2</ContextCode>
...
<Segment>
<SegmentCode>L10</SegmentCode>
...
<ReadOnlyFlag>N</ReadOnlyFlag>
<BIEnabledFlag>Y</BIEnabledFlag>
<BIEqualizationTag>L10_TAG</BIEqualizationTag>
...
</Segment>
...
</Context>
...
<DescriptiveFlexfield>
more information about value sets, see the "Creating Custom Value Sets" section in
the Oracle Fusion Applications Extensibility Guide.
Figure 23–24 Create Flexfield View Link Wizard — View Objects Page
nested instance of this application module. You can identify the Oracle
Business Intelligence application module by the analytics subpackage
under the package root.
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 23–25.
As you define the custom properties, keep the following points in mind:
■ The default view instance inside the business intelligence-enabled flexfield
application module is typically called DefaultFlexViewUsage.
■ The custom property names should be formatted as BI_VIEW_LINK_
mypropertyname
■ The custom property values must be formatted as source_
viewobjectinstance_name, viewlink_definition_name, destination_
viewobjectinstance_name.
■ Use the fully qualified view object instance names for the source view object
and destination view object, and the fully qualified package name for the view
link definition.
■ Business intelligence joins between the view object instances that you specify
in different application modules are created while importing them from Oracle
ADF if custom properties are defined on the application module.
rows. You accomplish this by exposing the descriptive flexfield application module as
a web service and adding utility methods to support the flexfield service data project
to the product application module.
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 23–6, 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 23–26 shows a Business Component Browser view of a
descriptive flexfield.
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. Nest the descriptive flexfield application module instance in the product
application module as described in Section 23.5.1, "How to Nest the Descriptive
Flexfield Application Module Instance in the Application Module."
4. Add the view object instance to the application module as described in
Section 23.6.1, "How to Add a Descriptive Flexfield View Object Instance to the
Application Module."
Figure 23–27 Generating a Service Data Object Class for the Master View Object
e. Click Finish.
10. If the Add icon is disabled, the application is already service enabled. Complete
the following steps to expose the master view object operations:
a. 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 23–28,
select all the operations in the Basic Operations list, and click OK.
11. 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.
12. In the overview editor for the product application module, click the Java
navigation tab and click the link for the Application Module Class.
13. Add the utility methods shown in Example 23–10 to the application module class.
These utility methods enable web service clients to obtain FlexfieldSdoSupport
objects to access flexfield information.
Replace Flexfield with the appropriate string for the flexfield that you are working
with.
In the getFlexfieldSdoSupport method, replace getDffAM with the name of the
getter method for the nested flexfield application module.
Example 23–10 Utility Methods for Flexfield Service Data Object Support
public List<String> getFlexfieldSdoNamespaceAndName(String contextValue)
{
FlexfieldSdoSupport ss = getFlexfieldSdoSupport(contextValue);
if (ss == null)
{
return null;
}
return Arrays.asList(ss.getSdoNamespace(), ss.getSdoName());
}
14. In the overview editor for the product application module, click the Service
Interface navigation tab for the product application module and click the Edit
icon in the Service Interface Custom Methods section.
15. 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.
<Contents>oracle.apps.fnd.applcore.flex.test.dff1.model.DFF1MasterApplicationModul
eService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceEndpointProvider">
<Contents>ADFBC</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiName">
<Contents>DFF1MasterApplicationModuleServiceBean#oracle.apps.fnd.applcore.flex.tes
t.dff1.model.DFF1MasterApplicationModuleService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaName">
<Contents>DFF1MasterApplicationModuleService.xsd</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaLocation">
<Contents>oracle/apps/fnd/applcore/flex/test/dff1/model/</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiFactoryInitial">
<Contents>weblogic.jndi.WLInitialContextFactory</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiProviderURL">
<Contents>t3://localhost:port_number</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiSecurityPrincipal">
<Contents>weblogic</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiSecurityCredentials">
<Contents>weblogic1</Contents>
</StringRefAddr>
</RefAddresses>
</Reference>
4. 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.
Note: The remote server class was generated when you exposed the
descriptive flexfield as a web service in Section 23.13.1, "How to
Expose a Descriptive Flexfield as a Web Service." This class has a name
that ends with ServiceImpl.java.
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 23–12 shows how to get a data row. The XML payload output of this
program is shown in Example 23–13.
■ Example 23–14 shows how to create a new data row.
■ Example 23–15 shows how to update an existing data row.
import ...
}
}catch(Exception e){
e.printStackTrace();
}
Example 23–13 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>
DFF1MasterApplicationModuleService dff1Service =
(DFF1MasterApplicationModuleService)
ServiceFactory.getServiceProxy(
DFF1MasterApplicationModuleService.NAME);
DataFactory dataFactory =
ServiceFactory.getDataFactory(dff1Service);
MasterDffImpl dffMaster =
(MasterDffImpl)dataFactory.create(MasterDff.class);
dffMaster.setPrimaryKeyCode(PK1);
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();
}
}
...
DFF1MasterApplicationModuleService dff1Service =
(DFF1MasterApplicationModuleService)
ServiceFactory.getServiceProxy(
DFF1MasterApplicationModuleService.NAME);
DataFactory dataFactory =
ServiceFactory.getDataFactory(dff1Service);
MasterDffImpl dffMaster =
(MasterDffImpl)dff1Service.getMasterDff1(PK1);
XMLHelper xmlhelper = ServiceFactory.getXMLHelper(dff1Service);
String uri = dffMaster.getType().getURI();
String xml = xmlhelper.save(dffMaster, uri, "MasterDff");
System.out.println(xml);
System.out.println(dff1Service.getMyFlexfieldTypeSdoPath());
dffSubType.set(dff1Service.getMyFlexfieldTypeSdoPath(), contextValue);
dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,
Arrays.asList("GlobalSegment1")).get(0),
new BigDecimal(02));
dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,
Arrays.asList("P6_S0_On_Number")).get(0),
new BigDecimal(123));
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();
}
}
...
A web page in a popup dialog can be associated with a dynamic column, enabling
end users to pick flexfield segment values. Alternatively, users can enter values
directly into the segment fields. No custom code is required in either case.
This is the most typical scenario. Each descriptive flexfield segment is displayed as
a distinct column in the ADF Desktop Integration Table.
■ Using a static column, in a popup dialog associated with a single cell. Use this
approach for either of the following reasons:
– The descriptive flexfield is exposed in an ADF Desktop Integration Table, is
context sensitive, and the context changes from row to row. A static column is
required in this case.
– 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.
23.14.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.
■ To make the descriptive flexfield column of the ADF Desktop IntegrationTable
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 Desktop Integration Table" section of
the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle
Application Development Framework.
■ For the table's UpdateComponent and InsertComponent properties, specify one
of the following as the subcomponent to use:
– 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.14.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.
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.
For static display of a descriptive 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 descriptive 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.
Example 23–16 Updating or Inserting a Row with a Static Column Descriptive Flexfield
//Retrieve your worksheet view object
myworksheet_VOImpl srcVO = myVO
//Get the descriptive flexfield row based on the descriptive flexfield view
accessor.
DFFViewRowImpl dffRow = (DFFViewRowImpl)srcRow.getAttribute(mydff_viewaccessor);
while (token.hasMoreTokens()) {
prjValues.add(token.nextToken());
}
}
//Get the descriptive flexfield segment information.
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();
// 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)
!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;
}
}
}
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:
■ Section 24.1, "Introduction to Extensible Flexfields"
■ Section 24.2, "Overview of Integrating Extensible Flexfields in an Application"
■ Section 24.3, "Creating Extensible Flexfield Data Tables"
■ Section 24.4, "Defining and Registering Extensible Flexfields"
■ Section 24.5, "Defining and Registering Extensible Flexfield Business Components"
■ Section 24.6, "Employing an Extensible Flexfield on a User Interface Page"
■ Section 24.7, "Loading Seed Data"
■ Section 24.8, "Customizing the Extensible Flexfield Modelers"
■ Section 24.8.2, "How to Customize the Runtime User Interface Modeler for
Extensible Flexfields"
■ Section 24.9, "Testing the Flexfield."
■ Section 24.10, "Accessing Information About Extensible Flexfield Business
Components"
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."
contexts, so end users can specify only a single value for each context-sensitive
segment, such as the percent of travel time required for the position. The Certification
and License Requirements context is a multi-row context, so end users can enter
multiple rows, one for each certificate or license required for the position.
Figure 24–2 Parts User Interface Page for the All-in-One Printers Category
Figure 24–3 Parts User Interface Page for the Fax Category
Figure 24–4 Printers Logical Page in the Parts User Interface Page
Logical pages have several layout options. For example, in Figure 24–1, the developers
chose to hide the entire left section because their customers will add attributes to a
single page that is known at the time of development. However, in Figure 24–4,
developers chose to display the list of logical pages in the left pane. For more
information about layout options, see Section 24.6, "Employing an Extensible Flexfield
on a User Interface Page."
example, the root category (the category the does not have parents) is Computers and
Office. One of its child categories is Printers and Ink. The Printers and Ink category, in
turn, has a Printers child category. The Printers category has two children categories —
All-in-One Printers and Single Function Printers.
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.
The category hierarchy translates into a hierarchy of view objects that are configured
to support polymorphic view rows. The view objects have view links to associated
context view objects. A CategoryCode attribute acts as the discriminator that
determines which category view row type should be used. At application runtime, the
category in the base category view object row determines what pages and contexts are
displayed. Given a collection of polymorphic view rows, each row can be a different
type depending upon the category. An application module that holds the category
view object is generated for each category.
1. 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. Create the flexfield metadata. In this step, you use PL/SQL procedures to register
the flexfield and its usages, create a default context data element, and register the
flexfield data columns and root category.
See Section 24.4, "Defining and Registering Extensible Flexfields."
3. Create and configure business components to support the extensible flexfield. In
this step, you create an entity object and a view object over the base extension
table, and, if they exist, the translation extension table and view. You then create
the base category view object over the product table entity object (the table for
which the flexfield is an extension). If you want to enable search capabilities, you
create a declarative view object for searching over the product table that the
flexfield extends. Last, you configure the flexfield usages' application modules to
support flexfields and you register the flexfield's business components.
See Section 24.5, "Defining and Registering Extensible Flexfield Business
Components."
4. Add the extensible flexfield to the appropriate UI pages.
See Section 24.6, "Employing an Extensible Flexfield on a User Interface Page."
5. Load any necessary application seed data, such as error messages and lookup
values.
See Section 24.7, "Loading Seed Data."
6. Optionally, customize the generated model or the generated UI artifacts (or both).
See Section 24.8, "Customizing the Extensible Flexfield Modelers" and
Section 24.8.2, "How to Customize the Runtime User Interface Modeler for
Extensible Flexfields."
7. Test the flexfield.
See Section 24.9, "Testing the Flexfield."
After you have completed the extensible flexfield development process and delivered
your application, implementors can use the Manage Extensible Flexfields task flow to
define contexts, categories, and pages, and to configure the segments for each
extensible 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 planning and implementing flexfield configuration, such as
defining attributes, labels, behavior, and associated value sets, see the "Using
Flexfields for Custom Attributes" chapter in the Oracle Fusion Applications Extensibility
Guide.
Note: The steps in this section assume that the product table that the
flexfield is extending already exists.
marked as translatable, all segment values are stored in the translation extension table,
otherwise they are stored in the base extension table.
Table 24–2 lists the required translation extension table columns and Table 24–3 lists
the required translation extension view columns. You can include additional columns,
such as columns that are required by application standards.
The translation table name should have a suffix of _TL to identify it as a translation
table, and the name of the view of the translation table should have a suffix of _VL.
The primary key of the translation extension table must include the EFF_LINE_ID
column, the CONTEXT_CODE column, the CATEGORY_CODE column, the
LANGUAGE column, and the columns that match the primary key columns of the
product table.
Developers typically create the same number of VARCHAR2 type attribute columns in
the translation extension table as exist in the base extension table, but you are not
required to do so. Create as many VARCHAR2 type attribute columns as you think are
necessary for a translatable context. To avoid compatibility and interoperability
problems, name the columns ATTRIBUTE_CHARnumber, such as ATTRIBUTE_
CHAR1, ATTRIBUTE_CHAR2, and so forth. When setting the size of the VARCHAR2
columns in an extension translation table, consider that the columns might need to
contain multibyte characters.
You must use the Database Schema Deployment Framework tools to create the tables
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 57, "Using the Database Schema
Deployment Framework."
Table 24–1 (Cont.) Extensible Flexfield Base Extension Table (_B) Specification
Column Type Nullable?
ATTRIBUTE_NUMBER1_UOM VARCHAR2(9) Yes
....
ATTRIBUTE_NUMBER20 NUMBER Yes
ATTRIBUTE_NUMBER20_UOM VARCHAR2(9) Yes
ATTRIBUTE_TIMESTAMP1 TIMESTAMP Yes
... TIMESTAMP Yes
ATTRIBUTE_TIMESTAMP10 TIMESTAMP Yes
If the consumers want to support interface loading of extensible flexfield data, also
add entries for the BASE_INTERFACE, EXTENSION_INTERFACE, and
EXTENSION_INTERFACE_TL table types.
■ FND_DF_SEGMENTS_B
Add one row for the extensible flexfield with CONTEXT_CODE set to "Context
Data Element" and SEGMENT_CODE set to "Context Segment."
■ FND_FF_COLUMN_USAGES
For each usage, add an entry for each context-specific column in the EXTENSION
and EXTENSION_TL tables. For example, add entries for all the ATTRIBUTE_
CHARn columns, for all the ATTRIBUTE_NUMBERn columns, and so forth.
■ FND_EF_CATEGORIES_B
An extensible flexfield requires at least one entry in this table. Add additional
entries only if you are shipping your application with some categories already
defined.
After you create the flexfield's business components, you must complete the
registration process by adding entity details, as described in Section 24.4.1, "How to
Register Extensible Flexfields." You must have at least one entity usage per base
extension table. If you require parallel sets of extensible flexfield artifacts generated for
different uses (for example, public view objects and private view objects), replicate the
entity usage entries with a different group name. When the business components are
generated for the flexfield, a separate set of components are generated for each group.
For more information, refer to the package specification.
B3_VO
Line ID Key C3 Line ID Key C3 Key B3
C2_EO EFF Primary Context X C2_VO EFF Primary Context X B2_VO Primary Category:
Line ID Key C2 Line ID Key C2 Key B2
C1_EO EFF Primary Context T U V W C1_VO EFF Primary Context T U V W B1_VO Primary Category:
Line ID Key C1 Line ID Key C1 Key B1
Extends
Extends Primary Category
Extends
Key
Base Category View Objects
Extends
EFF Primary Context A1 A2 A3 A4 A5 EFF Primary Context A1 A2 A3 A4 A5
Line ID Key Line ID Key
Primary Category
Base Extension Table Base Extension Table
Key
Entity Object Context-Sensitive View Object Context-Sensitive
Attributes Attributes Base Application Table View Objects
Primary Category
Key
Base Application Table
Entity Objects Other Application
Attributes
Defining and Registering Extensible Flexfield Business Components
Tip: After completing these steps, you can regenerate the flexfield
business components programmatically at runtime to update your
extensible flexfield implementation without manual intervention.
For more information, see Section 26.4, "Regenerating Flexfield
Business Components Programmatically."
Note: The packages in which these entity objects are created must
not fall under the packages allocated for runtime generated business
components (which are specified in adf-config.xml and the flexfield
usage metadata).
24.5.1.1 Creating and Configuring an Entity Object Over the Base Extension Table
For each extensible flexfield usage, use the standard wizard to create an entity object
over the base extension table that is described in Table 24–1, but apply the changes
described in the following procedure to support the extensible flexfield.
To create and configure an entity object over 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
■ Primary key columns of the product table
■ CONTEXT_CODE
■ CATEGORY_CODE
■ CREATED_BY
■ CREATION_DATE
■ LAST_UPDATED_BY
■ LAST_UPDATE_DATE
■ LAST_UPDATE_LOGIN
2. On the Attribute Settings page, do the following:
■ Set the EFF_LINE_ID attribute to be a unique primary key.
■ Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.
3. On the Java page, confirm that the objectnameBEOImpl entity object class to be
generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.
4. After creating the entity object, configure all of its attributes to be hidden.
On the UI Hints tab of the Property Inspector for each attribute, set the Display
Hint property to Hide.
24.5.1.2 Creating and Configuring an Entity Object Over the Translation Extension
Table
If you created a translation extension table for the flexfield usage, as described in
Table 24–2, use the standard wizard to create an entity object over the translation
extension table, but apply the changes described in the following procedure to support
the extensible flexfield.
To create and configure an entity object over the extensible flexfield translation
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
■ Primary key columns of the product table
■ CONTEXT_CODE
■ CATEGORY_CODE
■ SOURCE_LANG
■ LANGUAGE
■ CREATED_BY
■ CREATION_DATE
■ LAST_UPDATED_BY
■ LAST_UPDATE_DATE
■ LAST_UPDATE_LOGIN
2. On the Attribute Settings page, do the following:
■ Set the EFF_LINE_ID attribute to be a unique primary key.
■ Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.
3. On the Java page, confirm that the objectnameTlEOImpl entity object class to be
generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.
4. After creating the entity object, configure all of its attributes to be hidden.
On the UI Hints tab of the Property Inspector for each attribute, set the Display
Hint property to Hide.
5. 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.
24.5.1.3 Creating and Configuring an Entity Object Over 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 over the translation extension view that is
described in Table 24–3, but apply the changes described in the following procedure to
support the extensible flexfield.
To create and configure an entity object over the extensible flexfield translation
extension view:
1. On the Attributes page of the wizard, include only the following columns as
attributes in your new entity object:
■ EFF_LINE_ID
■ Primary key columns of the product table
■ CONTEXT_CODE
■ CATEGORY_CODE
2. On the Attribute Settings page, do the following:
■ Set the EFF_LINE_ID attribute to be a unique primary key.
■ Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.
3. On the Java page, confirm that the objectnameVlEOImpl entity object class to be
generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.
4. After creating the entity object, configure all of its attributes to be hidden.
On the UI Hints tab of the Property Inspector for each attribute, set the Display
Hint property to Hide.
5. 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.
Note: No view objects are required over the translation table entity
object.
■ To support categories for the flexfield, create a view object over the product table
entity object for which you are developing this extensible flexfield.
■ To support searching, create declarative view objects.
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.
setWhereClauseParams(null);
applyViewCriteria(null);
ViewCriteria vc = getViewCriteria("getItemByKey");
setNamedWhereClauseParam("OrganizationIdBind", orgId);
setNamedWhereClauseParam("InventoryItemIdBind", invId);
applyViewCriteria(vc);
executeQuery();
Row r = null;
if(hasNext())
{
r = next();
setCurrentRow(r);
}
return r;
}
This method queries the correct category row based on up to five primary key
values passed into the method.
findApplicationModule(categoryAMInstName);
effAM.createDetailRowIfNotExist(
categoryViewUsageName, contextViewLinkAccName,
category_pk1, category_pk2, category_pk3,
category_pk4, category_pk5);
}
FND_DF_TABLE_USAGES
FND_DF_ADFBC_USAGES
Note: When it is not clear what type of data will be configured for
the extensible flexfield, name the containing region, such as a page or
a dialog, "Additional Information" or "Additional Information: Object
Name" for view-only data, and "Edit Additional Information" or "Edit
Additional Information: Object Name" for editable data. If the
containing region is a tab, name the tab "Additional Information" or
"Edit Additional Information," as appropriate. This convention
ensures consistency across Oracle Fusion applications.
24.6.1 How to Expose the Logical Pages and Contexts Associated with One Extensible
Flexfield Usage
You can incorporate an extensible flexfield into the UI as a list of the logical pages for a
single usage, combined with the contexts for the selected logical page, and integrated
into a single task flow.
To expose the logical pages and contexts that are associated with one extensible
flexfield usage:
1. Create a task flow for the single extensible flexfield usage, which includes a page
fragment with a splitter that contains the list of the usage's logical pages on the
left, and the contexts associated with the selected logical page on the right.
2. Add the task flow to the page.
3. Render the page.
SupportsSortCollection="true" Configuration=
"EFFRuntimeAM"
syncMode="Immediate"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
2. Complete the following steps to mark the flexfield usage's package directory as a
flexfield model package:
a. Create an inf directory in the flexfield usage's package directory. For example,
if the usage's package is oracle.apps.fnd.applcore.crmdemo.flex, then
create the /oracle/apps/fnd/applcore/crmdemo/flex/inf directory.
b. To identify the package directory as a flexfield model package, create a file
named FlexfieldPkgInf.xml in the package's inf directory and add the
following contents to the file.
<?xml version="1.0" encoding="UTF-8" ?>
<flexfield-inf/>
3. Complete the following steps to identify the flexfield user interface packages:
a. Either create a web application archive (WAR) deployment profile in the
project that is named FlexfieldViewController and that contains flexfield
user interface packages, or reference the flexfield user interface packages
through a library Java archive (JAR) file. Do not include this deployment
profile in the application enterprise archive (EAR) file. This is only a marker
profile.
b. Find the flexfield user interface package directory under the
ViewController/public_html directory and add an inf subdirectory to the
flexfield user interface package directory.
c. To identify the package directory as a flexfield user interface package, create a
file named FlexfieldViewPkgInf.xml in the package's inf directory and add
the following contents to the file.
<?xml version="1.0" encoding="UTF-8" ?>
<flexfield-inf/>
4. Add the following snippet to the Application tag at the top of the
Databindings.cpx file in order for the application to find the page definitions for
the generated UI artifacts:
PageMapClass="oracle.jbo.uicli.mom.DynamicPageMapImpl"
BasePageDefPackageName="pageDefs"
24.6.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 is comprised of 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.
4. Add a parameter that is exactly the same as the one you added in Step 2 to the task
flow.
11. Open the Java file and add the following code snippet, replacing the value for
taskFlowId with the appropriate string:
public class ContextsRenderingBean {
private String taskFlowId =
"/WEB-INF/oracle/apps/fnd/applcore/flex/eff/runtime/ui/test/flow/ContextsTF.xml
#ContextsTF";
private String newTaskFlowId =null;
private boolean refreshRegion = false;
public ContextsRenderingBean () {
}
12. Open the page definition for the launch page and scroll to the location of the
dynamic region binding.
13. Add the following refresh condition setting to the taskFlow tag:
RefreshCondition="#{backingBeanScope.ContextsRenderingBean.refreshRegion}"
This setting provides the call back and the conditions for the refresh of the contexts
region.
14. Follow the steps listed in Section 24.6.1.3, "Rendering the Page" to view the user
interface.
When you run the page and click on the page link, the call back to refreshRegion
will look up the ID for the contexts task flow and enable a refresh of the dynamic
region.
24.8.1 How to Customize the Runtime Business Component Modeler for Extensible
Flexfields
To extend the extensible flexfield runtime business component modeler, override the
EFFBCModelerFactory.getCustomEFFBCModeler method, shown in Example 24–3, in
the custom extensible flexfield runtime business component modeler factory.
24.8.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 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:
1. Create wrapper classes for the default customizer implementation classes.
2. Create a wrapper of the metadata provider implementation class.
3. Register the metadata provider wrapper class in the metadata for the flexfield's
business component.
24.8.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.8.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 are
read-only for single and multi-row 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 24–5.
if(contextViewDefImpl.getName().toUpperCase().indexOf("RESOLUTION") >0 ) {
returnData = "#{pageFlowScope.EFF_PARAM5=='Y'}";
}
return returnData;
}
24.8.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 are 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.8.2.1.4 How to Customize the Page Task Flow To customize which context task flows
are rendered in a page task flow, create a wrapper class for the
ContainerPageCustomizerImpl implementation class and override the
getContextTFRenderedELExpression method. This method returns the value of the
region tag for a context task flow.
24.8.2.1.5 How to Customize the Search Task Flow To customize the search task flow,
create a wrapper class for the SearchRegionCustomizerImpl implementation class.
Example 24–4 shows the ways in which you can customize the search task flow and
the methods to override to perform the customizations.
Table 24–4 (Cont.) Methods to Override to Customize the Search Task Flow
Customization Method to Override Notes
Alter properties in getApplicationsTablePropertie This method returns a hashmap
the product table sMap of name-value pairs of the
component for properties to be set.
search results.
Alter properties in getADFTablePropertiesMap This method returns a hashmap
the ADF Table that of name-value pairs of the
is in the product properties to be set, as shown in
table component Example 24–6.
for search results.
Customize the getQueryPanelPropertiesMap This method returns a hashmap
query panel of name-value pairs of the
properties. properties.
Get a handle to the customizeGeneratedSearchTaskf Use DOM objects to customize
document object lowRegion generated artifacts only if there is
model (DOM) no other way to perform for the
object of the customization.
generated search
region and its
pageDef.
Customize the getResultsTableColumnComponen This method returns a JSP EL
readOnly property tReadOnlyELExpression expression.
for a component in
search results table
column.
Customize the getResultsTableColumnProperti This method returns a hashmap
properties on the esMap of name-value pairs of the
search results table properties.
column for an
attributeDef.
Set the task flow getSearchTaskFlowDataControlS The task flow can be generated
data control scope cope with either a SHARED scope or a
to shared. ISOLATED scope. The default is
ISOLATED. Override this method
to set the scope to SHARED.
Add custom getAdditionalToolbarComponent Use the
toolbar Definitions AdditionalToolbarComponentDef
components. inition inner class to provide
metadata for the required
component. You can add
components of type CHOICELIST,
BUTTON, SPACER, and SEPARATOR.
Set the default getDefaultSearchCriteriaName
search criteria on
the search page as
it is loaded.
Customize the customizeGeneratedSearchTaskf This method returns a handle to
generated search low the DOM object for the generated
task flow XML. task flow XML. You only should
use DOM objects to customize
generated artifacts if there is no
other way to perform the
customization.
{
HashMap propertiesMap = new HashMap(10);
propertiesMap.put("filterVisible","false");
propertiesMap.put("columnStretching","column:description");
propertiesMap.put("inlineStyle","width:100%;");
return propertiesMap;
}
24.8.2.1.7 How to Register the Metadata Provider Class for the Business Component In order
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.
* @return
*/
public static String getContextVoName(Long appId, String flexCode,
String flexUsageCode,
DBTransaction txn,
String contextCode,
String tableType,
String effGroup)
Example 24–10 Method to Get Name for EFF Context Entity Association Between Base
and Extension Entity Objects
/**
* @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 getCategoryContextAssocName(Long appId, String flexCode,
String flexUsageCode,
DBTransaction txn,
String contextCode,
String tableType,
String effGroup)
Example 24–11 Method to Get Attribute Name for EFF Context Entity/View Object Given
Segment Code (FND_DF_SEGMENTS_VL.SEGMENT_CODE)
/**
* Get the attribute name for the EFF context view
* object / entity object given the segment code.
* @param segmentCode - segment code for attribute name.
* @return attribute name
*/
public static String getContextAttributeName(String segmentCode)
Example 24–13 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)
This chapter discusses how to use key flexfields in Oracle Fusion applications to access
data that is represented by different organizations using different combinations of
fields, and to customize the presentation of that information to end users in a way that
is most appropriate for their organizations. This chapter also 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 25.1, "Introduction to Key Flexfields"
■ Section 25.2, "Completing the Producer Tasks for Key Flexfields"
■ Section 25.3, "Completing the Consumer Tasks for Key Flexfields in Reference
Mode"
■ Section 25.4, "Using Key Flexfield Advanced Features in Reference Mode"
■ Section 25.5, "Completing the Development Tasks for Key Flexfields in Partial
Mode"
■ Section 25.6, "Working with Combination Filters for Key Flexfields"
that implementors can set up however they like using key flexfield segments. Key
flexfields let your implementors customize your application to show their codes any
way they want them. For example, a different company might have a different code for
the same notepad, such as "8x14-PD-Y-NR", and they can easily customize your
application to meet that different need. Key flexfields let you satisfy different
customers without having to reprogram your application.
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 should be used.
Given a collection of polymorphic view rows, each row can be a different type.
The attribute sets that are associated with the discriminator are predefined. In fact,
Oracle ADF enables each view row to have its own view definition. When a
polymorphic collection of rows is created, Oracle ADF selects a 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 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.
You use a wizard to generate a polymorphic base view object that is based on the key
flexfield definition, then create a view link to connect the product view object 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.
usage segment columns in the product table. The table that contains the redefined
segment columns is referred to as a partial table. The master usage is sometimes
referred to as reference mode and partial usage is referred to as partial mode.
There are two types of partial usages:
■ All-segment partial usage: In this mode, the product table has columns for all of the
key flexfield segments.
■ Single-segment partial usage: In this mode, the product table has only one key
flexfield segment column.
Producer
The key 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. The producer's product owns the combinations
table for that flexfield.
Consumer
A key flexfield consumer 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.
Figure 25–1 Key Flexfield Development Roles, Business Components and Supporting
Artifacts
Consumer
Product Foreign Key Product Foreign Key Product
View Object Entity Object Table
Flexfield
View Link
Producer Phase 2
Reference
ReferenceKey Flexfield
Re
efe nceKey
Reference
erenc Ke
KeyeyFlexfield
F
Flexfield
Flexfiel
le
exxfie
ffie
eld
d Read-Only Code
Polymorphic
Polymorphic View Objects
Po
olym
ymoorph
rphhciiccVOs
Polymorphic
phic
p VOs
VO
VO
Oss Combination Entity Object
Dynamic
Insertion Call
Combinations
Table
Flexfield
View Link
Maintenance
Maintenance
M Key Flexfield
Main
Maintenance
nte
ena
annce
ce eKey
KeyyFlexfield
Key Flexfiel
Flex
Fl
Flexfield
lexf
exxfie
fie
iel
eld
el
Polymorphic
Polymorphic View Objects
Po ymorp hiccVOs
Polymorphic
olym phic VOs
VOs
VO
over the updatable entity object, and define a view link between your code
combination master view object and the key flexfield view objects. Then you
create the maintenance application module.
■ In producer phase 2, you optionally configure the maintenance application
module to accept dynamic combination insertion calls, and implement the
appropriate Java class in the user interface to invoke dynamic insertion. You
create a read-only reference entity object over your combinations table, and
create reference model key flexfield business components over the read-only
entity object.
See Section 25.2.4, "How to Create Key Flexfield Business Components".
Tip: After completing this task, you can regenerate the flexfield
business components programmatically at runtime to update your key
flexfield implementation without manual intervention. For more
information, see Section 26.4, "Regenerating Flexfield Business
Components Programmatically".
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. Optionally, build a key flexfield maintenance user interface.
For more information, see Section 25.2.6, "How to Build a Key Flexfield
Maintenance User Interface".
5. Optionally, implement key flexfield advanced features such as code combination
constraints or API access to segment labels, or access flexfields from a worksheet
using ADF Desktop Integration.
For more information, see Section 25.4, "Using Key Flexfield Advanced Features in
Reference Mode".
6. Optionally, define, implement, and invoke key flexfield code combination filters.
For more information, see Section 25.6, "Working with Combination Filters for Key
Flexfields".
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. Add your key flexfield to an application page.
See Section 25.3.4, "How to Employ Key Flexfield UI Components on a Page."
5. Configure the key flexfield user interface components.
See Section 25.3.5, "How to Configure Key Flexfield UI Components."
After completing these tasks, you can define seed or test value sets for the flexfield,
and you can create a model that you can use to test it. For more information, see
Section 26.1.2, "How to Test 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 26.5, "Integrating Flexfield Task Flows into Oracle
Fusion Functional Setup Manager."
The product table and its key flexfield columns must be registered in the Oracle Fusion
Middleware Extensions for Applications (Applications Core) data dictionary before a
flexfield can be defined on it. For more information, see Chapter 57, "Using the
Database Schema Deployment Framework."
Any implementation of flexfields in Oracle Fusion applications typically requires
application seed data, which is the essential data to enable flexfields to work properly
in applications. Flexfield seed data can be uploaded and extracted using Seed Data
Loader.
After you complete the registration process described in Section 25.2.1, "How to
Develop Key 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 the role of the implementor. In
addition to the registration data, your flexfield seed data might include structures and
value sets that you have defined for your flexfield.
For information about extracting and loading seed data, see Chapter 56, "Initializing
Oracle Fusion Application Data Using the Seed Data Loader".
Note: The product table and its key flexfield columns must be
registered in the Applications Core data dictionary before a flexfield
can be defined on it. For more information, see Chapter 57, "Using the
Database Schema Deployment Framework."
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 U.S. and
another for France). Each structure instance is identified by an 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.
This is a way of adding simple striping to the combinations table. You insert the DSN
column to enable you to tag sets of combination codes with your own numeric IDs,
and 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.
The table's primary key is composed of a combination of the CCID, SIN, and DSN
columns depending on the conditions listed in Table 25–1.
The combinations table must include the columns listed in Table 25–2. These columns
indicate whether a combination is enabled and active. The column names and data
types must match exactly.
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.
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 be nullable or they should have default
database values.
is used, the partial table must either include those columns or a column from which
the SIN or DSN can be derived.
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 about flexfield
definitions.
The definition of a key flexfield includes the following information:
■ The code, name, and description of the flexfield.
■ The master usage code. This code is typically the same code as the flexfield.
■ The name of the combinations database table.
■ The names of the database table columns to be used as flexfield segments.
■ The name of the CCID column.
■ The names of the SIN and DSN columns, if they exist.
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 outputs 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
In order 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 access 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."
least one segment. You specify a segment label as global if you want it to apply to all
segments. Any key flexfield segment can have any number of segment labels applied.
Table 25–3 presents the results of setting these flags on a segment label in various
combinations.
For example, in General Ledger's Accounting flexfield, the Account segment label is
required and unique because 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.
the standard value attribute columns, but they can use these custom columns for
their own implementations of value attributes.
■ SUMMARY_FLAG — this is a predefined system value attribute, for use with the
GL# key flexfield only.
Create value attributes using a procedure from the FND_FLEX_KF_SETUP_APIS PL/SQL
package.
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).
2. To enable administrators to define cross validation rules that are appropriate for
their organizations, develop a runtime maintenance utility that they can use to
define and maintain their own rows in a dedicated repository table, FND_KF_
CROSS_VAL_RULES, as shown in Table 25–4.
These filters are compatible with, and supported by, the key flexfield combination
filter infrastructure.
The value of each of these filters should be a logical combination of boolean
expressions. At runtime, all filters from this 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 the
pseudocode in Example 25–1.
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.
procedure MY_VALIDATION_CALLOUT (
NEW_CODE_COMBINATION in my_comb_table%ROWTYPE,
VALIDATION_CONTEXT in FLEX_VAL_CTX_RECORD);
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 in the
combinations table that are not related to the flexfield will be passed as null.
VALIDATION_CONTEXT is a record containing any additional usage specific context that
may be useful. Currently this record contains only a VALIDATION_DATE field. If there is
no validation date, a null value will be passed for VALIDATION_DATE.
The API is expected to raise an exception (with an error message) if validation fails. If
an exception is raised then dynamic insert will be aborted, and the message in the
exception displayed to the end user. The log will also record the entire call stack,
including the fact that the exception was raised from a custom callout. If the API
returns without exception it will be considered a success.
After you have written the custom validation callout procedure, you can register it
with the key flexfield. The custom validation callouts are registered in the FND_KEY_
FLEXFIELDS_B key flexfield registration table as shown in Table 25–5.
The base view object is extended to define view object rows of different structure
codes. Each structure code corresponds to a view object definition that includes the
appropriate flexfield columns for that structure, in addition to the inherited CCID and
SIN columns. Although flexfield view objects carry both SINs and structure codes,
only SINs are used to link to the product view object.
If the combinations table has other fixed (nonflexfield) columns, 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. Build a writable maintenance model.
This model supports building a maintenance mode application, and it supports
dynamic combination insertion. It is always required unless you want all end user
access to code combinations to be strictly read-only.
2. Build a read-only reference model.
This is needed so that you or a consumer of your key flexfield can build a page
with a foreign key reference to the combinations table, which is the most likely
way that end users will access the key flexfield.
You can build this model in one of the following ways:
■ Without dynamic combination insertion support.
To accomplish this, build your read-only reference model.
■ With dynamic combination insertion support.
To accomplish this, you must enable dynamic combination insertion in the
maintenance model and then build the read-only reference model.
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 be sure to select the Maintenance Mode checkbox
when you encounter it on the Usage Settings page, as described in the following
procedure.
2. Create a master view object 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.
Note: This is not a role in the security sense. It exists only during this
procedure, for the purpose of specifying where your generated
flexfield business components should be stored.
Figure 25–4 Create Flexfield Business Components Wizard — Entity Object Page
11. Expand the tree of available models and select an entity object to use as the data
source for the key flexfield.
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 master usage, this includes
attributes that represent the CCID, SIN, and segment columns, and the DSN
column if it exists in the combinations table.
12. 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,
select the checkbox labeled Use the entity attributes named after their
corresponding flexfield database columns. This checkbox is unselected by
default.
When a key flexfield entity object attribute is transient, there is no matching
underlying column name. When you select this checkbox, 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. Make sure 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 master 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.
16. Refresh the project to see the newly created flexfield business components in the
Application Navigator.
25.2.4.1.2 How to Link Your Maintenance Model Key Flexfield Business Components to Your
Code Combination Master View Object You need to create a flexfield view link from your
code combination master view object 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 over the combinations table
entity object.
The master view object and the base key flexfield view object are linked through the
combination of a CCID, and SIN, and if present, a DSN.
Figure 25–5 Create Flexfield View Link Wizard — View Objects Page
6. In the Select Source View Object tree, expand the available objects from your
current project and select your code combination master view object.
7. 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.
8. In the View Link Accessor Name field, enter an appropriate name for the view
link accessor.
9. Click Next to access the Source Attributes 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.
25.2.4.1.3 How to Create the Maintenance Application Module You need to 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
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.
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.
Note: For each key flexfield, only one instance of the application
module is needed. For example, even though two view links may
have been created to access the same flexfield, only one instance of the
flexfield application module is needed in the product application
module.
5. When you complete the Create Application Module wizard, right-click the new
application module instance and choose Run to test it.
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
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.
■ You have only one nested key flexfield application module instance in this
application module, and this 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 combinations, 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. In the maintenance application module, implement the Java class
oracle.apps.fnd.applcore.oaext.model.KFFCombinationCreator from the
oracle.apps.fnd.applcore.oaext.model package.
The class has only one method defined:
public void createKeyFlexfieldCombination(Long sin, Long dsn, List<Object>
segValues);
FlexfieldSegmentValue.ValueAttributeValue valAttrValue =
segValue.getValueAttributeValue(valAttrCode);
// Value attribute code is also available in the value object.
System.out.println(" ValueAttrCode = "
+ valAttrValue.getValueAttributeCode());
// Get the default value of the value attribute.
System.out.println(" ValueAttrDefaultValue = "
+ valAttrValue.getDefaultValue());
// Get the value of the value attribute.
System.out.println(" ValueAttrValue = "
+ valAttrValue.getValue());
}
}
System.out.println();
System.out.println();
System.out.println();
+ 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));
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 the following
example, an alternative version of MyKffMaintenanceAM.java.
Example 25–5 Calling insertCombination to Make the New Entity Available to the Master
View Object
public void createKeyFlexfieldCombination(
Long sin, Long dsn, List<Object> segValues)
{
KFFCombinationAttributes combAttrs =
((KFFMApplicationModuleImpl)
getMyKffAM1()).insertCombination(sin, dsn, segValues);
25.2.4.2.4 Inserting a Code Combination that Uses Custom Validation Procedures or Cross
Validation Rules If custom validation procedures or cross validation rules are registered
with the flexfield, you must create a Java class for the maintenance application module
that implements KFFCombinationCreatorProxy. This makes the information in the
KFFCombinationCreatorProxy.Context object, such as validation date, available to the
custom validation procedures.
1. In the maintenance application module, generate a Java class that implements
KFFCombinationCreatorProxy from the oracle.apps.fnd.applcore.oaext.model
package and extends your existing base object class. By default, the base class is
OAApplicationModuleImpl from the same package. An example of an application
module class is shown in Example 25–3.
@Override
public void createKeyFlexfieldCombination(
Long sin, Long dsn, List<Object> segValues)
{
// Delegated to the method that takes "context".
this.createKeyFlexfieldCombination(sin, dsn, segValues, null);
}
@Override
public void createKeyFlexfieldCombination(final Long sin, final Long dsn,
final List<Object> segValues,
final Context context)
{
KFFCombinationAttributes combAttrs =
((KFFMApplicationModuleImpl) getMyKffAM1()).insertCombination(
sin, dsn, segValues, context);
}
}
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:
a. In the New gallery, select General > Deployment Profiles > ADF Library JAR
File and click OK.
b. Enter a name for the profile and click OK.
4. 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.
2. 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 into the form or table that you just created.
For more information, see Section 25.3.4, "How to Employ Key Flexfield UI
Components on a Page".
Caution: 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.
For more information about setting user interface properties, see Section 25.3.5.1,
"Configuring Flexfield-Level User Interface Properties."
Figure 25–8 Create Flexfield View Link Wizard — Source Attributes Page for Key
Flexfields
10. 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.
11. If your destination key flexfield supports multiple structure instances, the
Structure Instance Number dropdown list appears on the Source Attributes page.
You must specify a structure instance as an additional source attribute. From the
dropdown list, select the source attribute that corresponds to the SIN of the
destination key flexfield.
The SIN must be mapped to type java.lang.Long.
12. 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.
13. Click Finish to go to the Summary page.
Note: You can skip the Properties page because view link-specific
properties are not supported.
14. On the Summary page, review the summary, then click Finish to create the view
link.
15. 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.
25.3.3 How to Add an Instance of a Key Flexfield View Object to the Product
Application Module
You need to add a flexfield view object instance that reflects the 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 your foreign key product 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, ExpenseLines is the
master and GLKff is the detail.
For more information about creating a hierarchy of view instances, see "Adding
Master-Detail View Object Instances to an Application Module" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
2. Create a view link between the view object for the foreign key product table and
the key flexfield view object as described in Section 25.3.1, "How to Create Key
Flexfield View Links."
Figure 25–9 Flexfield View Instance Nested Under Master View Instance
Note: This section assumes you are using the data-first method of
adding flexfields to your application, in which you build the data
model first, then create the user interface by dragging data controls
onto a page. The UI-first method is also available, but is not
documented here.
In a typical application, you would have one combinations 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 pages with foreign key references to the same key
flexfield. For example, in an order entry/inventory application, you might have a
combinations page where you define new parts with a key flexfield for the part
numbers.
You would also have a page with a foreign key reference 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 key flexfield combination filter, which you use to determine the
acceptable values of your part numbers. This combination filter references the same
key flexfield as the combinations page and the foreign key 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:
■ Adding the key flexfield UI component to a form or a table
■ Defining a default value for every SIN attribute to prevent application errors when
a new row that contains key flexfield columns is added on an application page
■ For ADF Form pages, adding code to ensure proper updating of reference mode
and partial mode SIN values
■ For partial flexfield segments or segments on a combinations page, where the
flexfield is in an ADF Table that is wrapped in an Applications Table component,
adding functionality that dynamically refreshes the segment columns whenever
the Applications Table component is refreshed by another component, such as a
button or a search query.
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.
5. If 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, select editAll. If you want the end user to
click into a row to make it editable, select clickToEdit.
If you select clickToEdit, 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 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: For partial flexfields in table components, you can 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 in reference mode, the default Structure Instance
Number 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.
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.3.4.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, the developer 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 in order for the concatenated value to be updated.
25.3.4.4 Ensuring Proper Updating of Partial Mode SIN Values in an ADF Form
When an end user makes changes to an existing ADF Form row that contains key
flexfield partial 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 25–7.
//Get the handle of the child iterator binding. This is the same iterator
//that you get when you drag the key flexfield partial usage onto a jspx page
DCIteratorBinding childBinding =
bindingControl.findIteratorBinding("Kff1PaInstanceIterator");
"#{bindings.KffCriteriaQuery.processQuery}",
Object.class,QueryEvent.class,queryEvent);
DescriptiveFlexfield.updateFlexColumns(appTable);
}
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 displays 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 25–13.
Note: You do not need to enter values for all segments when
searching for a key flexfield code combination.
The significant properties on the Common, Data, Style, Behavior and Other property
tabs are listed in Table 25–6.
1
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.
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 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.
The default values of these properties are derived from the flexfield metadata, but you
can override them by inserting customization elements into the UI 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 element from the
Component Palette into the key flexfield element, as a child of the
keyFlexfieldpartial element:
<fnd:flexfieldLabeledSegmentHint propertyname1="value" [propertyname2="value"
[propertyname3="value" [propertyname4="value" [propertyname5="value"
[propertyname6="value" [propertyname7="value"]]]]]]>
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 element from the
Component Palette into the key flexfield element:
<fnd:keyFlexfieldPartial propertyname1="value" [propertyname2="value"
[propertyname3="value"]]>
12. Select the attribute that corresponds to the discriminator, such as _STRUCTURE_
INSTANCE_NUMBER, from the Attribute dropdown list.
13. Accept the default values of Equal to for the Operator and Literal for the
Operand.
14. Click OK.
16. If the Java Classes section does not display a view object class, click the Edit icon
to generate and configure Java implementation classes, and complete the
following steps:
a. In the Select Java Options dialog, select Generate View Object Class.
b. Optionally select Include bind variable accessors, Include custom java data
source methods, or both.
c. Click OK.
17. In the Java navigation tab, click the path shown for the View Object Class to open
it in the source editor. This is the class that ends with VOImpl.
18. In the source editor, override the getCriteriaItemClause() method from the
oracle.jbo.ViewCriteriaItem package as shown in Example 25–10.
Set VIEW_CRITERIA_NAME to the name of the view criteria that you just created, and
set KFF_ACCESSOR_NAME to the view accessor from the view link between the
foreign key view object and the key flexfield polymorphic view object.
Note: If the foreign key view object contains more than one key
flexfield, the getCriteriaItemClause() method must call
getCriteriaItemClauseWhenKffExposedinQueryPanel() for each key
flexfield, passing the appropriate criteria name and KFF Accessor
Name.
String returnString;
returnString = null;
returnString =
this.getCriteriaItemClauseWhenKffExposedinQueryPanel(
vci, VIEW_CRITERIA_NAME, KFF_ACCESSOR_NAME);
return returnString;
}
5. In the Edit Table Columns dialog, you can rearrange any column and select table
options.
6. 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 25–17.
import java.util.List;
import javax.faces.event.AbortProcessingException;
import oracle.adf.model.BindingContext;
import oracle.adf.model.binding.DCBindingContainer;
import oracle.adf.view.rich.event.QueryOperationEvent;
import oracle.adf.view.rich.event.QueryOperationListener;
import oracle.adf.view.rich.model.AttributeCriterion;
import oracle.adf.view.rich.model.Criterion;
import oracle.adf.view.rich.model.QueryDescriptor;
import oracle.jbo.uicli.binding.JUFormBinding;
import oracle.jbo.ViewCriteria;
import oracle.jbo.ViewCriteriaItem;
import oracle.jbo.ViewCriteriaRow;
import oracle.jbo.common.ViewCriteriaItemImpl;
import oracle.jbo.uicli.binding.JUSearchBindingCustomizer;
if (item.getName().equals(
MASTER_VO_ATTR_FROM_WHICH_KFF_DISC_DERIVED)){
proxyval = item.getValue();
}
ViewCriteriaRow nvcr =
(ViewCriteriaRow) nvc.getCurrentRow();
List<ViewCriteriaItem> ncriteriaItemsList =
nvcr.getCriteriaItems();
for(ViewCriteriaItem nitem: ncriteriaItemsList){
if (nitem.getName().equals(KFF_DISCRIMINATOR_ATTR_NAME))
nitem.setValue(proxyval);
}
}
}//if instanceof
}//end for
}
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.
8. Complete the following steps to attach the custom bean to the query.
a. Open the JSPX page.
b. In the Structure window, select af:query.
c. In the Property Inspector, expand the Behavior section.
d. In the QueryOperationListener field, enter an EL expression that resolves to
the custom bean's processQueryOperation() method, such as
#{CustomBean.processQueryOperation}.
Purchasing product view object that enables Order Management to restrict the
displayed items to only those with Purchasable set to Y.
Code combination constraints are applied in the following situations:
■ When an end user launches a key flexfield pop-up window to search for a code
combination.
■ When the code-combination ID attribute of a foreign key view object 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:
■ Extra WHERE clause
■ Validation date
■ Validation rules
■ Dynamic combination creation allowed
The destination of the view accessor is the base key flexfield 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 25–18 shows the
accessor name AcctKffConstraints.
4. Edit the view accessor to define the bind parameter values, as shown in
Figure 25–19.
Note: 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.
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 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 25.4.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 25.4.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 25.4.1.4, "Constraining Code Combinations by Validation Rules."
■ Dynamic combination creation allowed: This constraint is invoked with the
bind parameter Bind_DynamicCombinationCreationAllowed.
For information about how to provide a value for this bind parameter, see
Section 25.4.1.5, "Enabling or Disabling Dynamic Combination Creation for a
Specific Usage."
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:
❏ View object level (evaluated once)
■ Bind_ExtraWhereClause
■ Bind_ValidationRules
❏ Row level (evaluated every time)
■ BindVar0 through BindVar9
■ Bind_ValidationDate
■ Bind_DynamicCombinationCreationAllowed
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)"
25.4.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 only apply 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 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
is validated by a business component. When the ALWAYS_APPLIED_FLAG is set to N, the
validation rule is applied only when the rule is included in the list of validation rules
as an argument to C or PL/SQL validation APIs or as a Bind_ValidationRules
parameter as described in Section 25.4.1.4.2, "How to Set the Bind_ValidationRules
Parameter."
Because the names of the segment columns that the customer will use for the code
combinations are not known during development, you must use the lexical references
listed in Table 25–7 to refer to the segment column and value attributes in the rule's
WHERE clause. In addition to the lexical references, the FLEXFIELD.VALIDATION_DATE
bind variable can be used in validation rule WHERE clauses. No other flexfield bind
variables can be used.
For example, if the following WHERE clause was registered as a validation rule for a
segment, the derived SQL query to retrieve the segment's list of values would be
similar to Example 25–12, and the derived SQL query to retrieve the combination list
of values would be similar to Example 25–13.
GL_AFF_AWC_API_PKG.gl_valid_flex_values(
:{FLEXFIELD.VALIDATION_DATE}, &{VALUE.VALUE}) = 'Y')
25.4.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.
The validation rules are pre-defined as part of the key flexfield definition. The
supplied list is the list of rules that need to be applied when searching for a code
combination.
Note the following caveats when constructing this list:
■ The validation rule codes are case sensitive.
■ Space characters are preserved. For example, "VRULE1; VRULE2" will be parsed
into "VRULE1" and " VRULE2" (with a leading space).
■ Unrecognized and unused rules are discarded silently. For example, if you
have a validation rule for an optional label, and the label has not been
assigned yet in the current flexfield definition, the rule will be ignored at
runtime.
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.
By setting this value to TRUE or FALSE, you can control whether your specific usage
of the key flexfield allows dynamic insertion even though the key flexfield as a
whole is enabled for dynamic insertion. Set the value to TRUE if you want your
usage of the key flexfield to allow dynamic insertion. Set the value to FALSE if you
do not want your usage of the key flexfield to allow dynamic insertion. Set the
value to null to indicate that the key flexfield itself should determine whether
dynamic combination insertion is allowed or not.
If the key flexfield does not allow dynamic combination insertion, this constraint is
ignored. Bind_DynamicCombinationCreationAllowed is a row-level bind
parameter.
Example 25–14 Retrieving Segment Label Information Using the Flexfield Application
Module
// First find the flexfield application module:
FlexfieldApplicationModuleImpl flexAM = (FlexfieldApplicationModuleImpl)
rootAM.findApplicationModule("Kff1nAM1");
// You can find the "column name" defined in the entity. The column name
// is typically the database column name.
System.out.println(attr.getColumnName());
}
Example 25–15 is an example of Java code that retrieves segment label information
from a deployed flexfield using the flexfield view row.
Example 25–15 Retrieving Segment Label Information Using the View Row
// This is just for illustration. In a real application, the
// flexfield view row should be retrieved through the view link accessor.
ViewObject vo = rootAM.findViewObject("Kff1nAM1.DefaultFlexViewUsage");
vo.executeQuery();
while (vo.hasNext())
{
FlexfieldViewRowImpl row = (FlexfieldViewRowImpl) vo.next();
// Given a KFF view row, you can find the labeled attributes through
// the view def. An empty list is returned if the given label is not used
// in the row.
List<AttributeDef> labeledAttrs =
row.getFlexfieldViewDef().getLabeledAttributes("SEGMENT_LABEL_RU1");
for (AttributeDef attr: labeledAttrs)
{
System.out.print(attr.getName() + "=" +
row.getAttribute(attr.getName()) + ";");
}
System.out.println();
}
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, refer to the
Javadoc.
25.4.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 (BI) 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 or administrator can select which individual
flexfield segments to make available for use with Oracle Business Intelligence.
You can enable the segments for business intelligence using the Manage Key Flexfields
task, which is accessed from the Oracle Fusion Applications Setup and Maintenance
work area.
An alternative method to business intelligence–enable a key flexfield and its segments
is to set the BIEnabledFlag to Y at both the key flexfield level and the segment level in
the key flexfield seed data file (SDF), as shown in Example 25–16.
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 60.8.1, "Designing a Column-Flattened View
Object for Oracle Business Intelligence."
Figure 25–20 Create Flexfield View Link Wizard — View Objects Page
of this application module. You can identify the Oracle Business Intelligence
application module by the analytics subpackage under the package root.
4. Define the custom properties required to link the master view object instance to
the default view instance.
This is done on the General tab of the nested business intelligence–enabled
flexfield application module instance definition, as shown in Figure 25–21.
When you generate a flexfield business component, the key flexfield business
component and other artifacts are developed based on the information in the flexfield
metadata. As illustrated in Figure 25–2, 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.
As an example, suppose that an application module has the master view object Fkt1
and a view link from the master view object to the detailed key flexfield view object,
Global1, which is a polymorphic view object.
The Business Component Browser view shown in Figure 25–22 corresponds to a
particular row in the master view object, displaying the segment structure in the key
flexfield with SIN of 11.
Figure 25–22 Business Component Browser View of Flexfield Row with SIN = 11
Figure 25–23 Business Component Browser View of Flexfield Row with SIN = 25
Note: In this section, master view object refers to the product foreign
key view object as illustrated by Figure 25–1.
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."
c. If any subtype view object SDOs are missing, edit the flexfield base view
object, and, on the Java navigation tab, click the Edit Java options icon.
In the Select Java Options dialog shown in Figure 25–25, 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 25–25 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. Edit the master view object.
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 25–26, enter a name for the
attribute.
Figure 25–27 Generating Java Classes for the Master View Object
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 25–17 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.
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 Service Interface 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 25–28.
Select the checkbox for each operation of the view object that you want to expose
in the service interface and clear the rest.
Figure 25–28 Create Service Interface Wizard — Service View Instances Page
and view criteria find operations that you chose to expose, as shown in
Figure 25–29.
20. In the overview editor for the product application module, click the Java
navigation tab.
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 25–18 to the application module class.
These utility methods enable web service clients to obtain FlexfieldSdoSupport
objects to access the flexfield's information.
Replace Flexfield with the appropriate string for the flexfield that you are working
with. Use a string that describes how the flexfield will be used by the customers.
For example, getLedgerSdoNamespaceAndName is better than
getGLSubtypeSdoNamespaceAndName.
In the getFlexfieldSdoSupport and getFlexfieldStructureInstanceNumber methods,
replace getKffMAM1 with the name of the getter method for the nested
maintenance application module instance.
Example 25–18 Utility Methods for Flexfield Service Data Object Support
// Change method name as appropriate
public List<String> getFlexfieldSdoNamespaceAndName(
String structureInstanceCode) {
FlexfieldSdoSupport ss= getFlexfieldSdoSupport(structureInstanceCode);
if (ss == null) {
return null;
}
return Arrays.asList(ss.getSdoNamespace(), ss.getSdoName());
}
24. In the overview editor for the product application module, click the Service
Interface 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.
<Contents>oracle.apps.fnd.applcore.flex.test.kff1.model.ApplicationService</Conten
ts>
</StringRefAddr>
<StringRefAddr addrType="serviceEndpointProvider">
<Contents>ADFBC</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiName">
<Contents>ApplicationServiceBean#oracle.apps.fnd.applcore.flex.test.kff1.model.App
licationService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaName">
<Contents>ApplicationService.xsd</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaLocation">
<Contents>oracle/apps/fnd/applcore/flex/test/kff1/model/</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiFactoryInitial">
<Contents>weblogic.jndi.WLInitialContextFactory</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiProviderURL">
<Contents>t3://localhost:port_number</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiSecurityPrincipal">
<Contents>weblogic</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiSecurityCredentials">
<Contents>weblogic1</Contents>
</StringRefAddr>
</RefAddresses>
</Reference>
4. 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.
Note: The remote server class was generated when you exposed the
key flexfield as a web service in Section 25.4.4.1, "Exposing a Key
Flexfield Application Module as a Web Service." This class has a name
that ends with ServiceImpl.java
5. Optionally, create and run Java client programs to test invoking the web service.
Example 25–20 is an example of how a client test program would use the flexfield
service data object support utility methods that you added in Section 25.4.4.1,
"Exposing a Key Flexfield Application Module as a Web Service."
DataObject accountDo =
dataFactory.create(accountSdoInfo.get(0), accountSdoInfo.get(1));
System.out.println(accountDo);
accountDo.set(acctKffMaintService.getAcctSDOPath(),
acctKffMaintService.getAcctStructureInstanceNumber(
"CC_ACCT_LOC_PRJ_SI"));
System.out.println(segmentPaths);
25.4.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:
■ Preparing your development environment for desktop integration.
■ Creating a page definition file that will expose the Oracle ADF bindings for use in
Excel.
Note: The titles of the popup dialog components must be set to the
name of the key flexfield, such as "Account," to be consistent across
Oracle Fusion Applications.
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.
25.4.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
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.
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.
Example 25–21 Updating an Existing Row with a Key Flexfield Dynamic Column
You add this code as an application module method which will be invoked from the
UpdateRowActionId property of an ADF Table. This code will be invoked for every
row that is updated.
Row tempRow = null; //get KFF child row information based on your KFF View Link
Accessor
KFFViewRowImpl acctRow;
ViewRowImpl kffAcctRow = (KFFViewRowImpl)linerow.getAccountLineKff();
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(linerow, "AccountLineKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
//IF YOU NEED DYNAMIC INSERT (CREATING NEW SEGMENT COMBINATIONS) FROM ADFdi
Speadhseet
//make sure end user supplied valid value for at least one segment.
if (kffAcctId==null) {
// if there was not valid ccid obtained earlier, that means you
if (!acctSeg .equals(delim.toString())) {
linerow.setKeyFlexfieldCombinationID("AccountLineKff",
acctSeg);
kffAcctId =
linerow.getKeyFlexfieldCombinationID("AccountLineKff", acctSeg );
}
} //if kffAcctId is null
linerow.setDistCodeCombinationId(kffAcctId);
Example 25–22 Inserting a New Row with a Key Flexfield Dynamic Column
You add this code as an application module method which will be invoked from the
InsertAfterRowActionId property of an ADF Table. This code will be invoked for
every row that is inserted.
Row tempRow = null;
//Retrieve key flexfield child row information based on your KFF view link
accessor
ViewRowImpl kffAcctRow = (ViewRowImpl)linerow.getAccountLineKff();
//if not child row (for new row case or cases where KFF data is not
invalid/present for existing DB Row)
//get a dummy row from ADFdi 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 ADFdi
worksheet,
//make sure the end user supplies a valid value for at least one segment.
if (kffAcctId==null) {
String delimiter = FlexfieldViewDefImpl.getDelimiter(kffAcctRow.getViewDef());
List segments =
FlexfieldViewDefImpl.getFlexfieldAttributes(kffAcctRow.getViewDef());
if (!KFFViewRowImpl.getConcatenatedSegments(kffAcctRow).equals(delim.toString())){
linerow.setKeyFlexfieldCombinationID("AccountLineKff",
KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
kffAcctId =
linerow.getKeyFlexfieldCombinationID("AccountLineKff",
KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
}
}
//setting CCID column with CCID value
linerow.setDistCodeCombinationId(kffAcctId);
Example 25–23 Updating or Inserting a Row with a Key Flexfield Static Column
This code should be added to the setter of the transient attribute in your view object
RowImpl.
setAttributeInternal(TRANSIENTACCOUNT, value);
//get KFF child row information based on your KFF View Link Accessor
//if not child row (for new row case or cases where KFF data is not
invalid/present for existing DB Row)
//get a dummy row from ADFdi helper class
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(this, "AccountKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
Long kffAcctId = null;
//If you need dynamic insert (creating new segment combinations) in the ADFdi
worksheet,
//make sure the end user supplies a valid value for at least one segment.
if (value!=null){
if
(!KFFViewRowImpl.getConcatenatedSegments(kffAcctRow).equals(delim.toString()))
this.setKeyFlexfieldCombinationID("AccountKff",value);
Example 25–24 Applying Modified Segment Values to a Cell in a Key Flexfield Static
Column
You add this code as a custom application module method which 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 ADFdi
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(headerRow, "AccountKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
// Derive and assign value of segments to your transient attribute
// which is created for single cell display in the ADFdi table
headerRow.setTransientAccount(KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
■ All-segments partial 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 GL setup table for use in filling in missing
values in the subledger account engine.
The development tasks for key flexfields in partial mode consist of the following steps:
1. Complete the registration of a key flexfield partial usage (all-segments or
single-segment).
2. Create partial mode key flexfield business components based on the partial usage.
3. Create a view link between your product view object and the partial mode key
flexfield.
4. The remainder of the development process is essentially the same as the consumer
development process for key flexfield master usages. You skip the section on
creating key flexfield view links and continue with the tasks described in the
following sections:
a. Section 25.3.3, "How to Add an Instance of a Key Flexfield View Object to the
Product Application Module"
b. Section 25.3.2, "How to Nest an Instance of the Key Flexfield Application
Module in the Product Application Module"
c. Section 25.3.4, "How to Employ Key Flexfield UI Components on a Page"
For example, if the column names are A1 and A2 in the combinations table, then in
the partial usage they could again be A1 and A2, respectively, or with a prefix they
could be X_A1 and X_A2. They cannot be B1 and Y_B2, nor any variation that does
not end in the names of the combinations table columns.
2. Use the PLSLQL registration APIs in the FND_FLEX_KF_SETUP_APIS package to
register the partial usage.
To learn how to access documentation about using the APIs, see Section 25.2.1.6,
"What You May Need to Know About the Key Flexfield Setup API."
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 partial 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.
For more information about testing flexfields, see Chapter 26, "Testing and
Deploying Flexfields." For more information about sharing and importing
shared flexfields, see Section 25.2.5, "How to Share Key Flexfield Business
Components."
Note: This is not a role in the security sense. It exists only during this
procedure, for the purpose of specifying where your generated
flexfield business components should be stored.
Do not select a flexfield usage without a prefix in the Description field. For more
information about key flexfield partial usages, see Section 25.5.1, "How to Register
a Key Flexfield All-Segment Partial Usage."
10. Click Next. The Entity Object page appears, as shown in Figure 25–32.
Figure 25–32 Create Flexfield Business Components Wizard — Entity Object Page
11. Expand the tree of available models and select an entity object to use as the data
source for the key flexfield.
Because you selected a partial 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 partial 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.
12. 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,
select the checkbox labeled Use the entity attributes named after their
corresponding flexfield database columns. This checkbox is unselected by
default.
When a key flexfield entity object attribute is transient, there is no matching
underlying column name. When you select this checkbox, 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. Make sure 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 master 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.
Note: If the entity object with transient key flexfield attributes is not
based on the master 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 25.5.1, "How to Register a Key Flexfield All-Segment Partial
Usage."
Figure 25–33 Create Flexfield Business Components Wizard — Usage Settings Page
entity object must first be registered with that flexfield usage. Text on the Naming
page indicates whether this is the case:
■ If the selected entity object is registered with the flexfield usage, the Naming
page displays the package name and the object name prefix for the entity
object. Click Next and continue to Step 15.
■ If the selected entity object is not registered (as an ADF Business Components
usage) with the flexfield usage, the Naming page displays a message to that
effect. Take one of the following actions:
– Click Back to return to the Entity Object page and select an entity object
that has been properly registered.
– Click Cancel to exit this wizard and register the entity object that you
want to use, as described in Section 25.2.1.9, "Registering Entity Details
Using the Setup APIs."
15. 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.
16. Refresh the project to see the newly created flexfield business components in the
Application Navigator.
3. On the Name page, from the Package dropdown list, specify a package for the
view link.
4. In the Name field, enter a name for the partial mode view link.
5. Click Next. The View Objects page appears, as shown in Figure 25–35.
Figure 25–35 Create Flexfield View Link Wizard — View Objects Page
6. In the Select Source View Object tree, expand the available partial mode key
flexfield view objects from your current project and select a source partial mode
view object.
7. In the Select Destination Flexfield tree, expand the available flexfield view objects
from your project and select a destination base key flexfield 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 25–36.
Figure 25–36 Create Flexfield View Link Wizard — Source Attributes Page for Partial
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.
The partial mode key flexfield view link is generated.
When you apply this filter condition to the combinations table, the result listed in
Table 25–9 is presented:
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 combination filters that you can use in your application —
standard combination filters, combination filters for Oracle Business Intelligence (BI)
Publisher reports, and cross-validation filters.
Cross-Validation Filters
Cross validation rules leverage the code combination filter infrastructure to apply a pair
of filters to new code combinations that are proposed for a key flexfield by
administrators or end users, when you have enabled them to work with maintenance
mode or dynamic combination insertion.
After enabling cross validation for a key flexfield at registration time, you must build a
maintenance user interface that administrators can use to maintain the
implementation-specific filters that comprise each rule. All filter combinations that an
administrator defines for a given key flexfield are applied automatically to cross
validate new code combinations as they are entered.
To incorporate cross-validation filters, you follow much of the same process as you
would to implement standard filters. The 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."
25.6.1 How to Prepare the Database for Standard Key Flexfield Combination Filters
A database column of type XMLType is required to store filter data in your database.
This column is referred to as the filter-condition column. For standard combination
filters, you must define a filter-condition column for the filter data in your database
before you can associate combination filters with key flexfields in your application.
2. 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: You do not need to create a filter view object if you are
implementing one of the following types of filters:
■ If you are implementing combination filters for use in the key
flexfield filter repository for Oracle BI Publisher reports, use the
existing public entity object
oracle.apps.fnd.applcore.flex.kff.model.publicEntity.FndK
fEssFiltersPEO, which became available when you added the
Applications Core library to your data model project.
■ If you are implementing combination filters to support cross
validation rules, use the provided configured entity object:
oracle.apps.fnd.applcore.flex.kff.model.entity.KeyFlexfieldCros
sValidationRuleEO
7. Add the custom filter properties that are listed in Table 25–10 to the filter attribute.
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.
3. Expand the available flexfields in your current project on the right-hand list and
select a key flexfield to be filtered.
4. Enter a name for the filter accessor (with no spaces), then click OK.
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 make sure that all attributes appear.
3. Make sure the CreateInsert and Commit actions are included on the page.
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.
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 25–41 and Figure 25–42. If you want restrict the filter to match on
all conditions only, add the RestrictConjunctionToAND property and set it to
true, as shown in Example 25–25 and Example 25–26
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 25–43, and the conditions are automatically joined
with an AND conjunction.
25.6.3.2 What Happens When You Add a Filter Repository Filter to an Application
Page
When you add a filter based on the public entity object FndKfEssFiltersPEO to your
application page as an ADF Form, the resulting Oracle BI Publisher report submission
user interface appears as shown in Figure 25–44.
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 25–45.
When you click CreateInsert, a new row is added which 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 25–11.
When you click Commit, the new row is inserted in the FND_KF_ESS_FILTERS
database table.
Note: You can insert this data at any time after the filter-condition
column has been added to the product table, and before the filter is
invoked.
The operators supported for key flexfield combination filters are the operators
supported in the Query panel. This includes the following data types and their
operators:
■ STRING data type — EQUALTO, NOTEQUALTO, CONTAINS, DOESNOTCONTAIN, LIKE,
STARTSWITH, ENDSWITH, ISNULL, ISNOTNULL
Example 25–27 Scripts for Inserting Filter Conditions into the Application Database
Example of EQUALTO filter:
Insert into KFF1_FLTR values(
1, 'EqualToFilter',
XMLType('<?xml version ="1.0" encoding ="UTF-8"?>
<FndFilter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.oracle.com/apps/fnd/applcore/filter/FndF
ilter.xsd">
<KeyFlexFilter>
<keyFlexfieldCode>KFF1</keyFlexfieldCode>
<structureInstanceCode>VS_IND_CHR_ON_CHR</structureInstanceCode>
<applicationShortName>FND</applicationShortName>
<filterCriteriaRow>
<filterCriteriaItem>
<attributeName>_L10</attributeName>
<columnName>SEGMENT1_VARCHAR2</columnName>
<operator>EQUALTO</operator>
<conjunction>AND</conjunction>
<valueDataType>STRING</valueDataType>
<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>'));
ilter.xsd">
<KeyFlexFilter>
<keyFlexfieldCode>KFF1</keyFlexfieldCode>
<structureInstanceCode>VS_IND_CHR_ON_CHR</structureInstanceCode>
<applicationShortName>FND</applicationShortName>
<properties>
<property>
<name>TestKff</name>
<value>Valkff</value>
</property>
</properties>
<filterCriteriaRow>
<filterCriteriaItem>
<attributeName>_L10</attributeName>
<columnName>SEGMENT1_VARCHAR2</columnName>
<operator>NOTEQUALTO</operator>
<conjunction>AND</conjunction>
<valueDataType>STRING</valueDataType>
<value>Value02</value>
<properties>
<property>
<name>TestItemName</name>
<value>ValItem</value>
</property>
</properties>
</filterCriteriaItem>
<conjunction>AND</conjunction>
<properties>
<property>
<name>TestRowName</name>
<value>ValRow</value>
</property>
</properties>
</filterCriteriaRow>
</KeyFlexFilter>
</FndFilter>'));
Note: 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.
25.6.5 How to Apply Combination Filters Using the PL/SQL Filter APIs
You can take advantage of key flexfield 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.
The PL/SQL combination filter WHERE clause API is based on the signature shown in
Example 25–28.
/** ---------------------------------------------------------------------------
-- This procedure takes the Filter as XMLType in parameter, tablealias,
-- bindprefix and computes the WHERE clause associated to the filter
-- and provides it as out parameter
-- Params
-- IN Params
-- filter XMLType - Filter to be converted to sql snippet
-- tableAlias Varchar2 - Alias table name to be used in Sql snippet
-- bindPrefix Varchar2 - Bind Prefix
-- OUT Params
-- sin Number - Structure Instance Number
-- bindValues BIND_VAL_TAB - List of Bind Values
-- filterWhereClause Varchar2 - Whereclause sql snippet
----------------------------------------------------------------------------*/
Example 25–30, Example 25–31, and Example 25–32 demonstrate how to use the WHERE
clause API for an EQUALTO condition, a BETWEEN condition, and multiple conditions.
Example 25–30 Using the WHERE Clause API for an EQUALTO Condition
Suppose that a filter condition has been defined in a combinations table as follows:
■ Combinations table = FND_KF_TEST_CCT1
■ Filter column = SEGMENT1_VARCHAR2
■ Filter condition = 123
You would call the filter API as follows:
FND_KF_COMBINATION_FILTER_API.BuildWhereClause(
filter=>v_filter,
tableAlias => 'FKFF1',
bindPrefix => 'BND',
sin => v_sin,
bindValues => v_bind,
filterWhereClause => v_query);
The tableAlias value should be used in WHERE clause snippets to represent the
combinations table name, so in this example,
FND_KF_TEST_CCT1.SEGMENT1_VARCHAR2
should be entered as
FKFF1.SEGMENT1_VARCHAR2
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 25–31 Using the WHERE Clause API for a BETWEEN Condition
The following listing shows an example of a BETWEEN operator used as part of a
filter expression of the form "attribute BETWEEN value1 AND value2".
<?xml version ="1.0" encoding ="UTF-8"?>
<KeyFlexCodeCombinationFilter
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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 25–32 Using the WHERE Clause API for Multiple Conditions
The following listing shows an example of multiple operators used as part of a filter
expression of the form "attribute1 EQUALTO value1 AND attribute2 EQUALTO value2."
<?xml version ="1.0" encoding ="UTF-8"?>
<KeyFlexCodeCombinationFilter
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 - FKFF1.SEGMENT1_VARCHAR2 = :BND1
- FKFF1.SEGMENT2_VARCHAR2 = :BND2
sin - 12
bindValues - 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
PROCEDURE kff_filter
(p_lexical_name IN VARCHAR2,
p_application_short_name IN fnd_application.application_short_name%TYPE,
p_key_flexfield_code IN fnd_kf_flexfields_b.key_flexfield_code%TYPE,
p_filter_id IN NUMBER,
p_code_combination_table_alias IN VARCHAR2,
x_where_expression OUT nocopy VARCHAR2,
x_numof_bind_variables OUT nocopy NUMBER,
x_bind_variables OUT nocopy bind_variables);
Example 25–34 demonstrates how to use this API to obtain the WHERE clause and bind
variable information for a filter in the filter repository.
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);
DBMS_OUTPUT.PUT_LINE('filter Id: ' || filter_id.filter_id);
DBMS_OUTPUT.PUT_LINE('filter Where Clause: ' || l_filterWhereClause);
END LOOP;
END;
If the filter view object has more than one filter attribute with an accessor defined, you
will be presented with a list of those filter accessors. Select the one that you want to
remove.
This chapter discusses how to test your flexfield business components in Oracle
Fusion applications using Integrated WebLogic Server, how to deploy your flexfield
application to an instance of Oracle WebLogic Server (WebLogic Server) in order to test
the full lifecycle, 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 26.1, "Testing Flexfields"
■ Section 26.2, "Deploying Flexfields in a Standalone WebLogic Server Environment"
■ Section 26.3, "Using the WLST Flexfield Commands"
■ Section 26.4, "Regenerating Flexfield Business Components Programmatically"
■ Section 26.5, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup
Manager"
To test a flexfield:
1. From the Application menu, choose Application Properties.
2. In the Application Properties dialog, click the Deployment navigation tab and
click New to create a new deployment profile.
3. Select MAR File from the Archive Type dropdown list.
4. Enter a name for the profile, and click OK.
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 26–1, and click OK.
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 26–2, 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.
As soon as you select the package, Oracle JDeveloper automatically
selects the parents all the way to the top of the folder hierarchy, but
that does not mean everything under oracle is registered with Oracle
Metadata Services (MDS).
10. In the Application Properties dialog, expand Run and click the MDS navigation
tab.
11. Select the MAR profile that you created earlier, and click OK
Note: If you want to run the Business Component Browser with the
business components that you created for testing, you must create a
temporary user library that points to the test components, and include
the library in your project as the first library. This is because the
flexfield view objects are generated into a temporary directory outside
the scope of the application workspace.
Note: You might need to restart JDeveloper to ensure that the FLEX_
DEPLOY_ADDIN_ENABLED environment variable has taken effect and that
the flexfield packaging plugin is enabled.
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
"Deploying Fusion Web Applications" in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
■ From the command line, run the following ojdeploy command:
jdev_install\jdeveloper\jdev\bin\ojdeploy -profile deployment-profile \
-forcerewrite -workspace application-jws-path
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 26–1 shows sample tag
entries.
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.
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.
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 26–2 shows sample tag entries.
archive=getMDSArchiveConfig('ApplCore_Setup_EAR_file_pathname')
archive.setAppMetadataRepository(
'mds_jdbc_data_source',
'partition_name',
'DB',
'mds_datasource_JNDI',
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.
26.2.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. Execute the following commands to expand the EAR file.
mkdir tmpDir
cd tmpDir/
unzip ../FndSetup.ear
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. Change to the tmpDir folder.
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
26.2.2.5 Deploying the Product and Setup Applications to the Server Domains
After you have mapped the applications as described in Section 26.2.2.2, "Mapping the
EAR File to the MDS Partition" and Section 26.2.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 26.2.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 "Creating a WebLogic Domain" in Oracle
Fusion Middleware Creating Domains Using the Configuration Wizard. For information
about installing EAR files, see "Install an Enterprise Application" in the Oracle Fusion
Middleware Oracle WebLogic Server Administration Console Online Help.
Before you can use any WLST flexfield command from a development environment,
you must first prepare the environment as described in Section 26.3.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 26.3.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.
26.3.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.
application at a later time by repeating the process of creating the flexfield business
components.
To re-create the flexfield business components, you can use the Create Flexfield
Business Components wizard, which invokes the flexfield business component
modeler to generate (or regenerate) the business components. Alternatively, you can
create a Java program to invoke the flexfield business component modeler and thus
automate the creation of the business components without implementor interaction.
The flexfield business component modeler can be invoked through the Java
application programming interface (API) only in a deployed web application. You
must have the following artifacts:
■ 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 26–3 demonstrates appropriate Java code for updating the business
components for a descriptive flexfield.
Example 26–3 Java Code for Invoking the Flexfield Business Component Modeler
import oracle.apps.fnd.applcore.flex.runtime.util.BCModeler;
modelerArgs.put(BCModeler.Parameter.CONNECTION_URL,
"jdbc:oracle:thin:user/pass@dev1.us.oracle.com:1999:dev1");
Exception e = BCModeler.run(modelerArgs.getCommandLineArgs(false),
System.out);
if (e != null)
{
e.printStackTrace();
}
}
}
26.5 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.
Table 26–1 lists the flexfield setup task flows. To make these task flows available to
developers, implementors, or administrators, register the appropriate task. For more
information, see the Oracle Fusion Applications Common Implementation Guide.
For information about using the tasks for managing the flexfields, see the "Using
Flexfields for Custom Attributes" chapter in the Oracle Fusion Applications Extensibility
Guide. For more information about the Register Descriptive Flexfields task, see
Section 23.2.2, "How to Register and Define Descriptive Flexfields."
For related information about functional security actions and roles based on task
flows, see Chapter 50, "Implementing Function Security".
This part of the Developer's Guide provides information about the Oracle Enterprise
Crawl and Search Framework (ECSF). Oracle Enterprise Crawl and Search Framework
(ECSF) is an Oracle Fusion Middleware search framework that enables you to quickly
expose application context information on various business objects to enable full-text
transactional search.
The Getting Started with Oracle Enterprise Crawl and Search Framework chapter discusses
how to set up ECSF.
The Creating Searchable Objects chapter discusses how to create sets of data that make
view objects available for full text search.
The Configuring ECSF Security chapter discusses how to configure security for ECSF.
The Validating and Testing Search Metadata chapter discusses how to validate and test
the search metadata.
The Deploying and Crawling Searchable Objects chapter discusses how to deploy the sets
of data to the ECSF application and verify the crawl.
The Advanced Topics for ECSF chapter discusses the additional functionality that ECSF
offers to enhance the search experience.
This part contains the following chapters:
■ Chapter 27, "Getting Started with Oracle Enterprise Crawl and Search Framework"
■ Chapter 28, "Creating Searchable Objects"
■ Chapter 29, "Configuring ECSF Security"
■ Chapter 30, "Validating and Testing Search Metadata"
■ Chapter 31, "Deploying and Crawling Searchable Objects"
■ Chapter 32, "Advanced Topics for ECSF"
27
Getting Started with Oracle Enterprise Crawl
27
Getting Started with Oracle Enterprise Crawl and Search Framework 27-1
Introduction to Using Oracle Enterprise Crawl and Search Framework
Note: In ECSF, the generic term ACL (access control list) is used to
describe how Oracle SES and ECSF pass security information and
perform security checks by using the information described in the
ACL.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-3
Introduction to Using Oracle Enterprise Crawl and Search Framework
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. Connect to the database by performing one of the following tasks:
■ 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. Provide the path of the JPS Config file.
5. Create ECSF query proxy users. In order 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. (Optional) Configure the log settings.
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:
■ Execute the runCmdLineAdmin.bat script (Windows)
■ Execute the runCmdLineAdmin.sh script (Linux)
■ Start it as a Java program from a command line interface with the following
command:
java oracle.ecsf.cmdlineadmin.CmdLineAdmin
Enter a username and password when prompted.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-5
Setting Up and Running ECSF Command Line Administration Utility
Note: If you enter an invalid username and password, you can either
reconnect manually by using the connect command, or exit the ECSF
Command Line Administration Utility (type exit or press Ctrl-C)
and try again.
When you update passwords in the Lightweight Directory Access
Protocol (LDAP) credential store from the ECSF Command Line
Administration Utility, the jps-config-jse.xml file must contain the
same LDAP information as the jps-config.xml file. Java Platform
Security (JPS) does not propagate the changes from jps-config.xml
to jps-config-jse.xml automatically.
All commands, responses, and error messages in the ECSF Command Line
Administration Utility are logged.
To exit the ECSF Command Line Administration Utility, enter the exit command at
the prompt.
27.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. For information, see the "Adding ADF Library
Components into Projects" section in Oracle Fusion Middleware Fusion Developer's Guide
for Oracle Application Development Framework.
The application JAR file, which contains the searchable objects that are defined in your
application, is written to the deploy directory of the project.
In order 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 27.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 in order to add the searchable objects to the class
path.
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.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-7
Setting Up and Running ECSF Command Line Administration Utility
database or MBean server during startup. If you do not include the connection
information in the script, then you must manually create the connection to the Oracle
Fusion Applications database after you start the ECSF Command Line Administration
Utility. For information, see Section 27.2.4, "How to Manually Connect to the Oracle
Fusion Applications Database".
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.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-9
Setting Up and Running ECSF Command Line Administration Utility
If you choose not to supply the connection information before startup, you must
manually create the connection to the Oracle Fusion Applications database after you
start the ECSF Command Line Administration Utility.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-11
Setting Up and Running ECSF Command Line Administration Utility
The ECSF Command Line Administration Utility prompts you for the required
values.
■ connect to mbeanserver hostname port
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.
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.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-13
Setting Up Oracle Enterprise Manager and Discovering ECSF
Multiple developers can share one single Oracle Enterprise Manager application with
the Fusion Applications Control.
27.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
MBean server through a listener class
(oracle.ecsf.mbean.RegisterMbeanContextListener). All ECSF runtime operations
are invoked through the MBean.
If SearchDBDS is not listed, you must create a data source with jdbc/SearchDBDS as the
JNDI name and with the connection information to the database against which the
Fusion web application is running.
3. Click Farm_DefaultDomain.
Getting Started with Oracle Enterprise Crawl and Search Framework 27-15
Setting Up Oracle Enterprise Manager and Discovering ECSF
Note: You only need to discover the ECSF custom application target
in Oracle WebLogic Server once. Once it is discovered, you can
directly launch EM with the following URL:
http://your machine name:port/em
This chapter describes how to create searchable objects in Oracle Fusion Applications.
This chapter includes the following sections:
■ Section 28.1, "Introduction to Creating Searchable Objects"
■ Section 28.2, "Defining Searchable Objects"
■ Section 28.3, "Securing Searchable Objects"
■ Section 28.4, "Configuring Search Features"
■ Section 28.5, "Configuring Custom Properties for Searchable Objects"
Note: You can also package ECSF metadata into metadata archive
(MAR) files.
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,
only include attributes you intend to search).
■ Exclude locator objects (LOB) from searchable objects unless you intend to search
LOB contents.
■ Restrict the use of multilevel view objects to 5 levels to avoid causing severe feed
performance degradation.
■ Co-locate 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.
■ 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.
■ Attachments (Oracle Content Management or LOBs) require record by record
processing, and every record requires one additional network round-trip.
■ Store attributes only when necessary. Attributes stored in Oracle SES should be for
only the following purposes:
– Faceted navigation
– Advanced search
– Search result actions
– Primary keys
If the value of an attribute needs to be searchable, place it in the body of the
searchable object.
■ Use common attributes across Oracle Fusion Applications. Stored attributes
common to all the searchable objects must share the same name and data type. For
information about preventing conflicts, see Section 28.2.10, "What You May Need
to Know about Preventing Search Attribute Naming Conflicts".
hierarchies by using view links. ECSF supports multiple levels of a view hierarchy. By
defining additional view objects and linking the top level view object to the additional
view objects through a view link, parent, child, grandchild, and so on relationships are
formed. Once a view link is set, you can reference data in those successive objects for
indexing by using Groovy, a Java-like scripting language that is dynamically compiled
and evaluated at runtime.
Note: 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.
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. Only generate the
view link accessor 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 32.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 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
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 together. 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 28–1, which shows the accessors information on the Relationship
navigation tab of the view link editor, the name of the view link accessor is ZipLov.
Figure 28–1 Location of View Link Accessor Name for Child View Object
You can also find the name of view link accessors in the <ViewLinkAccessor> tags of
the XML source mode of the view object.
Alternatively, you can use the curdoc keyword to access the current document, as
shown in Example 28–1.
Example 28–1 Using curdoc to Access Child Documents and Their Attributes
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.
Example 28–2 Sample Groovy Expression to Determine Attribute's Java Data Type
'Hiredate type: ' + (Hiredate != null ? Hiredate.getClass().getName() : 'null');
The class name of the Hiredate attribute's value is displayed and can be viewed in the
Data Feed:
Hiredate type: java.sql.Date.
Once you determine the Java data type of a view object attribute, you can apply
standard Java formatting techniques to format its value. Example 28–3 shows a sample
Groovy expression for formatting a date.
Figure 28–3 Search Page for Configuring Search Properties of View Objects
Note: The Search page is not editable if the view object or existing
searchable object is read-only.
Note: 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.
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 28.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.
5. In the Keywords field, enter the keywords in the form of Groovy expressions. For
more information, see Section 28.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, and sent to
Oracle SES as part of the document for indexing. Once 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, leave it blank.
7. Complete the Search PlugIn field by using the Search PlugIn dialog. For more
information, see Section 28.2.3.3, "Using the Search PlugIn Dialog".
8. Save the view object.
Note: In order to save the changes made to the Primary Table, Title,
Body, and Keywords fields, you must move the focus from those
attributes (that is, click outside each field as you complete them).
Note: If the view object is open in JDeveloper when you update the
corresponding searchable object file (view_object_name_ECSF.xml),
you must close and reopen the view object to view the updates.
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. Type an alias for the primary table in the Table Alias field.
Note: 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.
6. Click OK.
Note: You must select a primary table from the Available Objects list
in order to save.
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.
3. If desired, enter a parameter name in the Parameter Name field and its
corresponding value in the Value field, then click Add.
4. To update an existing parameter, select the desired parameter in the table, change
its value, then click Update.
5. To delete an existing parameter, select the desired parameter in the table and click
Delete.
6. Click OK to save.
ECSF metadata can be packaged into an EAR file or a MAR file for consumption
during crawl time and query time.
28.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.
Note: The more attributes you make searchable, the larger the index
becomes, which slows the performance of the queries.
Use the Search page of the overview editor in JDeveloper, shown in Figure 28–6, to set
property values for view object attributes.
Figure 28–6 Search Page for Configuring Search Properties of View Object Attributes
Using the Search page, you can perform the following tasks on view object attributes:
■ Make view object attributes searchable.
■ Modify searchable attributes.
■ Delete searchable attributes.
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 28–1.
Note: 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: Only stored and secured view object attributes are available
for advanced search (that is, the Stored and Secure Attribute
checkboxes are selected).
5. Click OK.
6. Save the view object.
Note: If the view object is open in JDeveloper when you update the
corresponding searchable object file (view_object_name_ECSF.xml),
you must close and reopen the view object to view the updates.
5. Select or deselect the checkboxes to modify the property set for the searchable
attribute. For information about the searchable attribute properties, see Table 28–1.
6. Click OK.
7. Save the view object.
28.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.
28.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.
Note: 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.
■ 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, 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 won't 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.
28.2.10 What You May Need to Know about Preventing Search Attribute Naming
Conflicts
Because Oracle SES only supports facets on attributes of type STRING, if a facet is
defined on a non-string attribute 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. See
Section 28.2.10.1, "Checking for Stored Attribute Conflicts." Take 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:
You use the Search Designer to annotate a subset of these attributes (Name and
OrganizationId) to store in Oracle SES for search purposes.
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:
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, 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 if an
attribute is used for a facet or not. If it is used for a facet, 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. Navigate to the
JDeveloper ADF view object attribute editor and update the Alias property value, as
shown in Figure 28–8. 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.
facilitate 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. Set permissions for searchable objects
2. Create the security realm
3. Create the application policy store
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.
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 28–5.
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 28–6.
The application policy store includes the values that you specified.
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:
■ Add search result actions.
■ Modify search result actions.
■ Delete search result actions.
Use the Search navigation tab of the overview editor in JDeveloper, shown in
Figure 28–3, 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.6, "How to
Use the Actionable Results API with Oracle Fusion Applications Search".
2. Click the Add icon in the Search Result Actions table header to open the Search
Result Actions dialog, shown in Figure 28–10.
Note: No two actions can share the same name. This comparison is
case insensitive.
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.
Note: Only bounded task flows can be launched through the URL
mechanism.
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 28.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.
■ 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 28.4.1.4, "Defining Properties
for Bounded Task Flows".
6. 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 28.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: You can set only one action as the default action.
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.
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 28.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.
2. 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 28–10.
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 28.4.1.3, "Adding Search Result Actions".
Note: You must recrawl the data if you reference a new attribute that
is marked as stored.
6. Click OK.
7. Save the view object.
2. 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. Save the view object.
The search result actions you define during design time is parsed at runtime and
appear in a table on the search results page.
28.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 in order to save the action.
Note: 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.
3. In the Edit Attribute dialog for the stored attribute (StateID), select List of Values
and select Enable List of Values.
4. Create a mapping from a child attribute to the stored attribute.
Values from the child attribute are used to filter the parent view object.
5. Specify which attribute on the view object contains the display value.
■ 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.
6. Repeat Steps 1 to 5 to define a view object (CitiesView) to represent the stored
attribute that is defined as the child facet.
4. Map the StId bind variable on CitiesView to the StateId attribute of EmpView.
5. Ensure that the row-level bind values exist.
Note: If you require both custom SQL query and facets for a view
object, you must create the view object with the Updateable object
through entity objects option and select Expert for Query Mode on
the Query page.
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 28–3, 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.
2. Click the Add icon in the Facets table header to open the Facets dialog, shown in
Figure 28–12.
3. In the Facet field, enter a valid facet name for the root facet.
Note: No two facets can share the same name at the searchable object
level. This comparison is case insensitive.
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 28.4.4.5, "Using the Select Text Resource Dialog to Select a Matching Text
Resource" or Section 28.4.4.6, "Using the Select Text Resource Dialog to Create and
Select a New Text Resource".
Note: If no facet display name is specified, the label text of the view
attribute corresponding to the facet is used as the display name. If
there is no label text, then the view attribute name is used as the
display name.
You can use resource bundles to localize ECSF. For information, see Section 32.10,
"Localizing ECSF Artifacts".
5. From the Attribute Name dropdown menu, select a searchable attribute for the
root facet.
Note: The Attribute Name dropdown menu lists only the searchable
attributes whose isStored property is set to true. For information, see
Section 28.2.6.1, "Making View Object Attributes Searchable".
No two facets can share the same attribute at the searchable object
level.
Note: No two facets can share the same name. This comparison is
case insensitive.
8. Select an attribute for the child facet from the Attribute Name dropdown menu.
(see Figure 28–7) is populated with all the attribute names from the view links that are
associated with the current VO.
The code for querying for facets will not change.
At query time, a FacetPath will be converted to filters against the corresponding
Stored Attributes in the facet path. With this feature, some stored attributes will
contain multiple values, and the filter will select a search document if any of the
values in its stored attribute matches the value in the filter.
Facet counts will work without any changes. When a stored attribute contains more
than one value, each value will contribute to incrementing the count for that value.
2. 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. Create searchable attributes based on the attributes you created, including
transient attributes. Select the Stored option for the attributes.
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 28–7.
7. Define the facet hierarchy.
28.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.
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.
28.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.
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. Click Save and Select.
2. 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 28–12.
5. In the tree structure, select the facet you want to modify.
6. Make your desired changes:
■ Change the values of the Facet Attributes fields. For more information about
the fields, see Section 28.4.4.3, "Creating Search Facets".
■ Add child facets. For more information, see Section 28.4.4.3, "Creating Search
Facets".
■ Delete child facets. For more information, see Section 28.4.4.9, "Deleting Child
Search Facets".
7. Click OK.
8. Save the view object.
2. 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. Click the Delete (red X) icon in the Facets table header.
The root facet you selected on the Search navigation tab is removed from the table
of root facets.
5. Save the view object.
2. 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 28–12.
5. In the tree structure, select the facet you want to delete.
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. Save the view object.
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. Associate the LOV to the transient attribute.
4. Create a facet with the transient attribute in the facet definition.
28.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.
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.
<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. For
more information, see Oracle Fusion Middleware Application Security Guide.
To configure the application identities, you must complete the following tasks:
1. Make sure the SearchContext is set to FusionSearchContextImpl.
2. Create the application identities.
3. Make sure the permission policies for the identity store and the JPS
IdentityAssertion API are added to the jazn-data.xml file.
<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.
The grantee should be the users or roles that you want to authorize to use the search
feeds, as shown in Example 29–4.
The example shows how jazn-data.xml is modified to grant the permission to a role.
3. Create searchable objects. For information, see Chapter 28, "Creating Searchable
Objects".
4. Run the ECSF feed servlet. For information, see Section 30.3.1, "How to Run the
ECSF Feed Servlet".
Example 30–1 ECSF Feed Servlet, Feed Servlet Mapping, and Filter Mappings
<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>
Note: The web page is an RSS feed. Depending on the browser you
use, you may not be able to view the contents of the web page. If you
cannot view the RSS feed, navigate to View > Source in the browser
to view the feed.
You can click the Terminate (red square) button to stop the ECSF feed servlet.
<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 28.2.3,
"How to Make View Objects Searchable".
3. After adding the metadata, make sure to restart the Integrated WebLogic Server
instance.
<link>http://example.com:8988/approot/searchfeedservlet/runtime.EmpView/ControlFee
d</link>
<description>Control feed for Enterprise Crawl and Search
Framework</description>
<lastBuildDate>2008-04-06T19:20:08.159Z</lastBuildDate>
- <channelDesc xmlns="http://xmlns.example.com/orarss">
<feedType>control</feedType>
</channelDesc>
- <item>
- <link>
- <![CDATA[
http://example.com:8988/approot/searchfeedservlet/runtime.EmpView/DataFeed?tableNa
me=Emp&workUnitStart=AAHz%2BdADeAAA07UAAA&workUnitEnd=AAHz%2BdADeAAA07UAAV&type=RO
WID
]]>
</link>
</item>
</channel>
</rss>
<link>http://example.com:8988/approot/searchfeedservlet/runtime.EmpView/DataFeed</
link>
<description>RSS for Oracle Applications Search</description>
<lastBuildDate>2008-04-06T19:36:08.950Z</lastBuildDate>
- <channelDesc xmlns="http://xmlns.example.com/orarss">
<feedType>incremental</feedType>
</channelDesc>
- <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>
This chapter describes how to deploy searchable objects to the Oracle Enterprise Crawl
and Search Framework (ECSF) application.
This chapter includes the following sections:
■ Section 31.1, "Introduction to Deploying and Crawling Searchable Objects"
■ Section 31.2, "Deploying Searchable Objects and Dependencies"
■ Section 31.3, "Crawling Searchable Objects"
31.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 31–1, is automatically added to the WebLogic deployment descriptor file
(weblogic-application.xml).
31.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 together 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).
For more information, see Oracle Fusion Middleware Configuring Server Environments
for Oracle WebLogic Server.
2. Select the ECSF Shared Library Extension template (oracle.ecsf_11.1.1_
template.jar), which is located in
oracle/jdeveloper/common/templates/applications.
3. Configure the SearchDB data source by providing valid values for the following
fields:
■ DBMS Host
■ DBMS Port
■ SID
■ Username
■ User Password
For more information, see Oracle Fusion Middleware Configuring Server Environments
for Oracle WebLogic Server.
4. When a new version of the ECSF shared library is available, you must redeploy it.
a. Remove the old oracle.ecsf library.
For information, see Oracle Fusion Middleware Oracle WebLogic Server
Administration Console Online Help.
b. Install the library enterprise archive (EAR) file
(oracle/jdeveloper/ecsf/modules/oracle.ecsf_11.1.1/oracle.ecsf.ear)
with the name set as oracle.ecsf.
For information, see Oracle Fusion Middleware Oracle WebLogic Server
Administration Console Online Help.
Note: You can also redeploy the ECSF shared library by using the
Oracle Fusion Middleware Configuration Wizard. For more
information, see Oracle Fusion Middleware Configuring Server
Environments for Oracle WebLogic Server.
2. 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. Enter a value in the Application Package Prefix field.
6. Click Finish.
31.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.
■ 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 28.5, "Configuring Custom Properties for Searchable
Objects".
6. Click OK.
The run configuration is set to debug mode, and other ECSF system parameters
are set.
31.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:
■ For using ECSF for crawling and querying
– oracle/jdeveloper/soa/modules/oracle.soa.fabric_
11.1.1/fabric-runtime.jar
– oracle/wlserver_10.3/server/lib/wls-api.jar
■ For using ECSF for querying only
– oracle/jdeveloper/webservices/lib/soap.jar
You do not need to add the Java archive (JAR) files that are included in a library that
you have already added.
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 32.1, "Introduction to Advanced Topics for ECSF"
■ Section 32.2, "Enabling Search on Fusion File Attachments"
■ Section 32.3, "Enabling Search on WebCenter Tags"
■ Section 32.4, "Enabling Search on Tree Structure-based Source Systems"
■ Section 32.5, "Managing Recent Searches"
■ Section 32.6, "Setting Up Federated Search"
■ Section 32.7, "Federating Oracle SES Instances"
■ Section 32.8, "Raising Change Events Synchronously"
■ Section 32.9, "Using the External ECSF Web Service for Integration"
■ Section 32.10, "Localizing ECSF Artifacts"
■ Section 32.11, "Using ECSF Diagnostics"
■ Section 32.12, "Troubleshooting ECSF"
Note: 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.
3. On the searchable object, define a view link accessor that points to the view link.
For information, see Section 19.2.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 32–1 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 32–2 and Figure 32–3 illustrates
the difference between query time without a tag and query time with a tag.
In Figure 32–2, 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 32–3, 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.5, "How to Implement Tags in Oracle Fusion Applications Search".
Note: 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.
The view link must use the accessor name tagSVO so that the search extension can
navigate to the child object when it crawls.
2. Add tags to the indexable document.
3. Add tags to the query.
You can also perform the following tasks to customize search on WebCenter Portal
tags:
1. Modify the tags in the indexable document.
2. Register change listeners.
This extension adds three tags (Black, White, and Stripes) to a user named Zebra.
queryMetaData.setSearchGroups(sgs);
searchContext = ContextFactory.getSearchContext();
searchContext.bindUser("scott");
try
{
//clear tags so query tag through keywords
queryMetaData.clearTags();
queryMetaData.setQueryString("Black White");
searchHits = searchCtrl.runQuery(searchContext, queryMetaData);
//Zebra is found
//filter by tags
queryMetaData.setQueryString("%");
queryMetaData.addTag("White");
searchHits = searchCtrl.runQuery(searchContext, queryMetaData);
//Mickey is found
//filter by tags
queryMetaData.addTag("White");
queryMetaData.addTag("Black");
searchHits = searchCtrl.runQuery(searchContext, queryMetaData);
//Zebra is found
//filter by tag that exists and tag that does not exist
queryMetaData.clearTags();
queryMetaData.addTag("Stripes");
queryMetaData.addTag("Dots");
searchHits = searchCtrl.runQuery(searchContext, queryMetaData);
//no result is found
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);
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 32–4 illustrates the data flow for search on tree
structure-based source systems.
Figure 32–4 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 28.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 32.2, "Enabling Search on Fusion File Attachments".
Enable search on tree structure-based source systems by:
1. Crawling tree structures
2. Integrating search functionality for tree structures
3. Implementing administration using ECSF interfaces
field.setStored(true);
docdef.addField(field);
}
import java.util.Date;
import oracle.ecsf.IndexableDocument;
import oracle.ecsf.meta.PrimaryKey;
import oracle.ecsf.data.tree.CrawlableTreeNode;
//handle errors
}
}
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.
import oracle.ecsf.meta.SearchableObject;
security extension for the searchable object, it is used to serve as the authorization
module for indexed content in Oracle SES.
Note: 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.
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 32–7 illustrates the skeleton of a security extension.
import oracle.ecsf.SearchContext;
import oracle.ecsf.SecurityService;
import oracle.ecsf.util.SecurityServiceFactory;
The security extension is a Java class that implements a securable interface. There are
five methods available. Example 32–8 illustrates the skeleton of such class.
import oracle.ecsf.IndexableDocument;
import oracle.ecsf.SearchContext;
import oracle.ecsf.SearchSecurityException;
import oracle.ecsf.Securable;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import 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 AttachmentImpl() {
}
try {
FileReader fileReader = new FileReader(file);
BufferedReader br = new BufferedReader(fileReader);
String strd = br.readLine();
while (strd != null) {
stream.write(strd.getBytes());
strd = br.readLine();
}
} catch (IOException e) {
//Handle errors
}
}
//Contains configuration parameters needed to read the attachment
//This map can be an empty one as shown in this example.
public Map getParameters() {
Map parameters = new HashMap();
return parameters;
}
//Name value pairs need to identify a specific attachment.
public PrimaryKey getPrimaryKey() {
return primaryKey;
}
}
Once 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.
Example 32–11 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();
SearchableObject so = MetaDataManager.getSearchableObject(soName);
searchContext.setSearchableObject(so);
{
return null;
}
return searchHits;
}
/**
* Returns engine parameters in a hashmap for a given engine
* instance.
* @param engineId the engine instance id
* @return Hashmap configuration parameter
*/
public Map getEngineParameters(long engineId);
/**
* Returns a searchable group for a given search engine instance, by name.
* @param engineId The identification of the engine instance.
* @param name The name of the searchable group.
* @return a searchable group. Null if not found.
*/
public SearchableGroup getSearchableGroup(long engineId, String name);
/**
* Returns a searchable object for a given search engine instance by class
* name.
* @param engineId The identification of the engine instance.
* @param name The class name of the searchable object.
* @return a searchable object, null if not found.
*/
public SearchableObject getSearchableObject(long engineId, String name);
/**
* Returns a list of searchable groups for a given search engine instance.
* @param engineId The indentification of the engine instance.
* @return a list of searchable groups, empty if not found.
*/
public List<SearchableGroup> getSearchableGroups(long engineId);
/**
* Requests a reload of the configuration. Implementation should reload the
* objects from persistent storage.
*/
public void reload();
}
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;
}
{
return null;
}
}
else
{
return null;
}
}
catch (ClassNotFoundException e)
{
return null;
}
}
import oracle.ecsf.meta.AbstractDocumentDefinition;
import oracle.ecsf.meta.DocumentDefinition;
import oracle.ecsf.meta.FieldDefinitionImpl;
import oracle.ecsf.meta.SearchableObject;
import oracle.ecsf.util.ECSFLoggerFactory;
public EmpView()
{
super("");
setName(getClass().getName());
}
/**
* Override to initalize document.
* @param document
*/
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);
}
}
import java.util.HashMap;
import java.util.Map;
"http://sesserver.com:7777/search/api/admin/AdminService");
map.put("SES_QUERY_SERVICE",
"http://sesserver.com:7777/search/query/OracleSearch");
map.put("SES_QUERY_PROXY_USERNAME", "scott");
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;
}
■ RecentSearchManager Class
The RecentSearchManager will manage the creation, deletion and retrieval of
recent searches from the database.
■ SavedSearchManager Class
When a Saved Search is created, the SEARCH_TYPE column in the ECSF_
SVSEARCH database table will be set to the appropriate value, and the
SavedSearchManager will retrieve only searches that are of type SAVED.
■ ECSF_SVSEARCH Database Table
The existing ECSF_SVSearch database table will store the information for recent
searches, using the SEARCH_TYPE column to store the Search Type.
/**
* Returns a List of recent RecentSearch data objects for the
* current user defined in the SearchContext and the specified
* caller context
* @param ctx - the current SearchContext
* @param callerCtx - the caller context
* @return List<RecentSearch> - list of recent RecentSearches ordered
* from most recent to oldest
* @throws SearchException
*/
public List<RecentSearch> getRecentSearches(SearchContext ctx, String callerCtx)
throws SearchException
/**
* Creates a new recent search
*
* @param ctx - the SearchContext
* @param searchDescription - the description of the saved search
* @param queryDetails - recent saved search query information
* @return RecentSearch
* @throws SearchException
*/
public RecentSearch createRecentSearch(SearchContext ctx,
String searchDescription,
QueryMetaData queryDetails)
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
The call to get the Recent Searches will return a list ordered from most recent to oldest
recent search.
For performance, the list of recent searches returned will not contain the
RecentSearchDetails information for the Recent Searches. The fact that this information
is not available in the Recent Search dataobject is transparent to the client. When the
client wants the details and calls RecentSearch.getRecentSearchDetails() on the
Recent Search, the dataobject automatically will retrieve the RecentSearchDetails from
the database.
By default, the maximum number of Recent Searches for each user is limited to 10.
This number can be configured using a Java system property:
oracle.ecsf.recent.search.max.num
This property can be set using the Java -D option or the ecsf.properties file.
When Recent Search records are retrieved from the database, the SQL limits the
number of records based on the system property (or the default of 10), so that only the
most recent records are returned.
When the RecentSearchManager creates a new Recent Search, it first checks if the user
already has the maximum number of Recent Searches stored in the database. If the
user does not, a new Recent Search is created. If the user has exceeded the maximum
number of Recent Searches allowed, the oldest Recent Search record is deleted and
then the new Recent Search is saved into the database.
During the creation of a new Recent Search, at most one older Recent Search record
may be deleted. Because the maximum number of Recent Searches is configurable, if
this property is changed, there may be more Recent Search records in the database
than allowed per user, and the Recent Search records should be manually cleaned
from the database to clean up any extra records.
When a new Recent Search is created, due to the ECSF_SVSEARCH database table
constraint on the NAME being unique per user, the RecentSearchManager will
generate a unique name for the Recent Search using the database RowId for the new
record and the queryString input by the user:
String searchName = rowId + ": " + queryDetails.getQueryString();
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();
usual using federation. All of the necessary details for this are stored in the
queryMetaData object:
RecentSearchDetails recentSearchDetails = recentSearch.getRecentSearchDetails();
QueryMetaData qmd = recentSearchDetails.getQueryDetails();
SearchHits hits = searchCtrl.runQuery(qmd);
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.
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()
32.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.
32.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.
32.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 32–17.
<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.
2. 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.
32.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 32.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 32.6.6, "How to Package and Deploy the Search Application").
Oracle WebLogic Scripting Tool updates the files directly on the server you specify, so
no redeployment is necessary.
■ Under serviceInstances:
<serviceInstance name="keystore" provider="keystore.provider"
location="./default-keystore.jks">
<description>Default JPS Keystore Service</description>
<property name="keystore.type" value="JKS"/>
For more information, see Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
The key (in this example, test.user) for the new entry is used in connections.xml.
</port>
</service>
</model>
</wsconnection>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
<Reference name="{/oracle/ecsf/service/query/common/hcm/}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/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. For information, see Oracle Fusion Middleware Oracle WebLogic Server
Administration Console Online Help.
3. Save.
4. Redeploy the client application.
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.
ArrayList<SearchEngineInstance> engineInstances =
(ArrayList<SearchEngineInstance>)searchCtrl.getEngineInstances();
for (SearchEngineInstance engineInstance : engineInstances)
{
allGroups.addAll(engineInstance.getSearchGroups());
}
for (SearchGroup searchGroup : allGroups)
{
if (searchGroup.getName().equals("runtime.EmpView")
|| searchGroup.getName().equals("Service Request"))
{
searchGroups.add(searchGroup);
}
}
SearchGroup sgs[] = searchGroups.toArray(new
SearchGroup[searchGroups.size()]);
queryMetaData.setSearchGroups(sgs);
try
{
searchHits = searchCtrl.runQuery(ctx, queryMetaData);
}
catch (Exception e)
{
e.printStackTrace();
}
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.
Note: 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).
Example 32–22 illustrates how you can integrate federation across Oracle SES
instances.
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.
targetNamespace="/oracle/ecsf/service/query/common/"
xmlns:errors="http://xmlns.example.com/adf/svc/errors/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="/oracle/ecsf/service/query/common/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:types="/oracle/ecsf/service/query/common/types/">
<wsdl:import namespace="http://xmlns.example.com/adf/svc/errors/"
location="classpath:/META-INF/wsdl/ServiceException.wsdl"/>
<wsdl:types>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="/oracle/ecsf/service/query/common/types/"
schemaLocation="AppModuleSearchService.xsd"/>
</schema>
</wsdl:types>
<wsdl:message name="AppModuleSearchService_search">
<wsdl:part name="parameters" element="types:search"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_searchResponse">
<wsdl:part name="parameters" element="types:searchResponse"/>
</wsdl:message>
<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>
</complexType>
</element>
<element name="getSavedSearchDetails">
<complexType>
<sequence>
<element name="userName" type="string"/>
<element name="savedSearchRequest" type="string"/>
</sequence>
</complexType>
</element>
<element name="getSavedSearchDetailsResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
<element name="getSavedSearch">
<complexType>
<sequence>
<element name="userName" type="string"/>
<element name="savedSearchRequest" type="string"/>
</sequence>
</complexType>
</element>
<element name="getSavedSearchResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
<element name="getEngineInstances">
<complexType>
<sequence>
<element name="userName" type="string"/>
<element name="engineInstanceRequest" type="string"/>
</sequence>
</complexType>
</element>
<element name="getEngineInstancesResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
<element name="getDisplayName">
<complexType>
<sequence>
<element name="userName" type="string"/>
<element name="displayNameRequest" type="string"/>
</sequence>
</complexType>
</element>
<element name="getDisplayNameResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
<element name="deleteSearch">
<complexType>
<sequence>
<element name="userName" type="string"/>
<element name="savedSearchRequest" type="string"/>
</sequence>
</complexType>
</element>
<element name="deleteSearchResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
</schema>
<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>
The SavedSearch request XSD describes the set of rules that the request XMLs must
follow in order 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>
The QueryMetaData request XSD describes the set of rules that the request XMLs must
follow in order 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 in order 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>
When the query web service requests are successful, a response message is returned.
The XML strings for successful web service calls are based on the XSDs for the
following methods:
■ 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>
32.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>
32.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>
<xsd:element ref="savedSearch" maxOccurs="unbounded" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
32.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 32.9.4.1, "getSavedSearch()".
32.9.4.4 deleteSearch()
The web service response message for the method String deleteSearch(String
userName, String savedSearchRequest) is the string success.
32.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>
</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>
32.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"/>
use="required"/>
<xsd:attribute name="isleaf" type="xsd:boolean"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<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: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>
32.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>
<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>
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 oracle.ecsf.SearchException;
import oracle.ecsf.SearchHits;
import oracle.ecsf.client.SearchGroup;
import oracle.ecsf.client.dataobject.SavedSearch;
import 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;
public AppModuleSearchServiceSoapHttpPortClient()
{
initialize();
}
((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);
/**
* 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);
/**
* 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);
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");
return savedSearch;
}
try
{
fis = new FileInputStream(System.getenv("T_WORK") + File.separator +
"ecsf.properties");
prop.load(fis);
fis.close();
wlsHost = prop.getProperty("WLS_HOST");
wlsPort = prop.getProperty("WLS_PORT");
wlsPassword = prop.getProperty("WLS_PWD");
}
catch (FileNotFoundException e)
{
System.out.println("File not found exeception : " + e.getMessage());
}
catch (IOException e)
{
System.out.println("IO exception : " + e.getMessage());
}
}
The sample client class illustrates how each of the methods are called and how the
XMLs are deserialized.
2. Click the Add icon in the Custom Properties table header and select Translatable
Property to open the Select Text Resource dialog.
3. Select a resource bundle from the Resource Bundle dropdown menu.
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. Click Save and Select.
A new entry is added to the resource bundle, and the resource bundle is
associated to the view object.
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.
2. 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. Select a resource bundle from the Resource Bundle dropdown menu.
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. Click Save and Select.
A new entry is added to the resource bundle, and the resource bundle is
associated to the view object attribute.
There are many ways to configure LOVs for localization. Two of them are described
here: using the VL table and using resource bundles.
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.
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 28.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.
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 28.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.
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.
Localize the crawl management display names by translating the seed data that you
create in English. For information see Chapter 56, "Initializing Oracle Fusion
Application Data Using the Seed Data Loader".
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
Resource bundles are used to store language variations, while translation is the
responsibility of Oracle Fusion Applications i18n support infrastructure.
32.10.6.3 Crawl
You can specify the locale of the data to be indexed by using any of the following
methods:
■ Language field
■ Crawler's language preference
■ Java Virtual Machine (JVM) default locale
You can specify a view object attribute as a language field for a searchable object by
using the Search page. For information, see Section 28.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.
32.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 32–32, is used.
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.
Results
■ Searchable object configuration, including its display name, view object name, ID,
schema name, registered engine instance, associated schedule, and associated
categories.
■ Searchable object status including if it is deployed, if it is active, and if the latest
engine instance parameters have been applied to it. The deployment and crawl
statuses of the associated schedule are also displayed, along with the deployment
statuses of associated categories.
■ View object information, including the driving table, plugin class, if the plugin is
ACL enabled, view object SQL select statement, view object fields, and child
references.
■ Results of the body, title, keywords, and default action title validations.
■ Display of top-level facets. Actual data are obfuscated due to security reasons.
■ Searchable object actions.
Result
Searchable groups for this engine instance, along with their associated searchable
objects.
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.
■ Alternate keywords if any.
■ Top level facets including counts.
■ Search results: The title, body, and attribute values for the first page of results (up
to 10 records) will be shown.
Note: The engine instance crawl user is used for this test.
Results
■ SQL statement for the searchable object.
■ 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.
Results
■ SES admin endpoint.
■ ECSF service endpoint.
■ Result of proxy login into SES with stored credentials.
■ ECSF security service authentication status.
■ Search groups in ECSF.
■ Source groups in SES.
■ Index schedules in ECSF including the statuses in ECSF.
■ Index schedules in SES including the statuses in SES.
■ Searchable objects in ECSF.
■ Data sources in SES.
■ Number of configured proxy logins (federated trusted entities) in SES.
■ Configured identity plugin URL in SES.
Note: The engine instance crawl user is used for this test.
Result
Complete control feed (including list of data feeds).
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.
Result
Values of the search engine instance parameters. Usernames will be obfuscated for
security reasons.
Results
■ System properties that begin with "oracle.ecsf".
■ Location of the Java class for this test on the server.
Results
■ Displays if the application was able to obtain the connection successfully.
■ If connection is successful displays the connection URL.
Table 32–13 Parameter for Application Extension/ApplCore Session Locale (Protected) Test
Name Type Description
User Name Input (String) Specify the user for the test.
Results
■ Initializes the application extension session for the user.
■ Locale for the ApplCore session.
32.11.4 Security
These tests are used to diagnose issues in the security layer of the ECSF application.
Results
■ Checks that the user exists in the system.
■ Checks that the user has the given permission.
■ Checks that the user has access to the oracle.ecsf credential map.
■ Displays if the user has access to all ECSF services.
■ 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.
Result
Checks that the system can write to the credential store by creating and removing
credentials for a dummy user.
Results
■ Security attribute values for the user from the plugin.
■ Security principals for the user.
Problem
The Common-Model.jar file that you added to your project contains a dependency on
ECSF Runtime Server.
Solution
Remove the Common-Model.jar file.
Problem
After you initially crawl the data source, subsequent feed requests result in
incremental feeds (that is, feeds that contain only changes in data).
Solution
Override the incremental feed by performing one of the following tasks:
■ 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.
32.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.
32.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.
32.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. Go to the jdev cache directory /.jdeveloper/DefaultDomain/bin.
2. Open setDomainEnv.sh.
3. Locate the line that contains -XX:MaxPermSize=128m, and change it to
-XX:MaxPermSize=256m.
Problem
The ECSF Client library is missing from the project class path.
Solution
Update the project class path with the ECSF Client library.
Problem
SearchContext is implemented as a ThreadLocal variable, which is created when
ContextFactory.getSearchContext() is first called in the current Thread. All
subsequent calls to getSearchContext() within the same Thread results in that
instance being returned. Since the ThreadLocal variable remains associated with the
Thread, memory leaks occur.
Solution
After the completion of your Oracle Fusion Applications Search UI logic and before
results are returned to the UI for rendering, you must call the SearchContext.release
method.
32.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
Verify the details for SEARCH_DATA using this SQL statement:
select FILE_NAME, TABLESPACE_NAME, BYTES, MAXBYTES, BLOCKS, MAXBLOCKS from
sys.dba_data_files where TABLESPACE_NAME = 'SEARCH_DATA';
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 '/slot/ems7248/oracle/db/apps_
st/data/SEARCH_DATA_9.dbf';
The same steps can be used to add additional data files for other table spaces.
■ Click OK.
The user sales_admin now can be used for crawling.
Problem
The endpoints for the search applications are not up and running.
Solution
Set the correct search application endpoints in the connections.xml file of the client
application. Make sure the IS_ACTIVE parameter corresponding to this search engine
instance is set to "Y". Make sure the IS_ACTIVE parameter corresponding to this search
engine instance is set to "Y" in the ECSF_PARAMETER table.
Problem
If your search application only contains one category and the category is secured, the
Global Search UI will display this error message if this category does not pass the
permission check. In this case, no categories are available for search.
Solution
Usually this is because the permission set on the searchable object is not accessible to
the logged-in user, causing the secured category to not be returned by the search
application.
Problem
Search_Server1 is not up and running.
Solution
Bounce if required.
Problem
wsm-pm is not up and running. For example, wsm-pm is hosted in the SCM_
CommonServer for FSCM.
Solution
Bounce if required.
Problem
The identity management setup in SES administration is pointing to an invalid URL
combination and the proxy user cannot log into ECSF security service.
Solution
Change the identity management setup to point to the correct url using the correct
username and password.
Problem
The response from the Search servers may be very slow and the Search UI is unable to
fetch all the results.
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
Problem
In B16, the category drop-down is not displayed in the main UI page. The Global
Search UI does not load categories until an initial search is performed by clicking the
Search button. The Global Search UI will show this error if getting categories failed
against all the search applications. The endpoints for the search applications are not up
and running or the search applications are inactive in the database.
Solution
Set the correct search application endpoints in the connections.xml file of the client
application. Make sure the IS_ACTIVE parameter corresponding to this search engine
instance is set to "Y". Make sure the IS_ACTIVE parameter corresponding to this search
engine instance is set to "Y" in the ECSF_PARAMETER table.
Cause
If the search applications are up and running but this error is displayed, all the search
applications probably are returning errors.
Look for the following line in the messages logged in the client server log, such as
CustomerServer-diagnostics.log:
at
oracle.ecsf.service.query.ws.marshaller.ServiceUtil.toError(ServiceUtil.java:1499)
32.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.
Cause
This exception may occur on the SES when a user tries to run a schedule. This is
caused if the administration server and the manager servers are not started from the
correct locations. (Console/node manager)
Solution
The adminserver must be started using nodemanager and all other managed servers
must be started by using the Administration console.
32.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.
■ Run the command:
listCred(map="oracle.apps.security",key="FUSION_APPS_ECSF_SES_ADMIN-KEY")
Sample output:
Already in Domain Runtime Tree
[Name : searchsys, Description : null, expiry Date : null]
PASSWORD:welcome1
This part of the developer's guide describes the fundamental patterns that Oracle
Fusion application developers should use when building applications involving
Oracle Application Development Framework (Oracle ADF) and the Oracle SOA
platform. The majority of these use cases fall into three basic patterns:
■ The use of business events to initiate business processes
■ Orchestrating over business logic implemented with Oracle ADF, Java, PL/SQL,
and SOA composite applications
■ Modeling human task flows in ADF applications
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.
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:
■ Oracle ADF web application that includes ADF Business Components.
■ SOA composite application that includes an Oracle Mediator service component
and an additional service component to which the event can be routed (such as a
BPEL process service component).
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 33–1 illustrates how these work together.
Figure 33–1 Mediator Service Component Subscribes to an Event and Invokes BPEL
Service Component
33.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.
Note:
■ Event points can only be associated with Data Manipulation
Language (DML) operations.
■ Personally identifiable information (PII) is any piece of
information that can be used to uniquely identify a person. PII is
sensitive and must be protected from potential misuse.
When data is included in events or a BPEL flow, it is potentially
exposed. While the transport may be encrypted on the SOA side, the
data is not. The data in events, payload and BPEL variables is not
secured by the security restrictions for business objects. Consider what
data is to be exposed in the payload so as to prevent unauthorized
access.
Defining an event generates an Event Definition Language (.edl) file and XML
schema definition (.xsd). The EDL file contains all event definitions for the entity
and the XSD file defines the contents of an event's payload, in addition to other
objects needed by the BPEL process service component. These files together define
the contract between the Oracle ADF application and the SOA composite
application, as for a particular event, they identify the elements the SOA
composite expects. Both these files are placed in the events directory for the
project, and can be found in the Application Navigator as children to the
associated entity object.
In the example bug application, the BugReport entity object contains the
BugCreated event. This event carries all the attributes on the entity object as its
payload, and is published using the create operation as its event point.
2. 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.
a. Make sure that EDN data sources have been configured. Using Oracle
WebLogic Server Administration Console, verify that EDNDataSource and
EDNLocalTxDataSource have been configured.
Note: 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).
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 33–1to the
WEB-INF/web.xml file.
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 33–2.
<resource-description>
<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>
■ 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.
7. 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:
■ You select the initiate operation on the client of the BPEL process service
component as the target service, as shown in Figure 33–4.
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
SOA composite application to ensure it was properly deployed. For more
information about using Oracle Enterprise Manager Fusion Middleware Control
Console, see the chapter "Deploying SOA Composite Applications" in the Oracle
Fusion Middleware Developer's Guide for Oracle SOA Suite.
try {
super.beforeCommit(e);
Caution:
■ Do not use this pattern for a long running or asynchronous BPEL
process.
■ Make sure that synchronous services return immediately.
Synchronous services should be simple input/output payloads.
■ Do not use multi-record or N record services in which processing
time varies from seconds to minutes or longer.
For more information about this approach, see the chapter "Integrating Web Services
Into an Oracle 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 33–6.
(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 51, "Securing Web Services Use Cases."
<business-events>
<subscribe xmlns:sub1="/model/events/edl/BugReport"
name="sub1:bugCreated"
consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
</business-events>
</component>
2. To validate the subject propagation in the SOA composite application, add the
following code as shown in Example 33–8 to the BPEL file for the BPEL process
flow:
]]>
</bpelx:exec>
the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework. Be sure to enable ADF Business Components runtime
logging by setting the Java VM parameter in the run/debug profile to
jbo.debugoutput=console. Doing so logs the event and its payload in the
JDeveloper log console.
2. 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.
Launch Fusion Middleware Control Console using the following URL:
http://<hostname>:<port number>/em
5. Open Fusion Middleware Control Console to verify the process instance has been
created. Use the Audit tab to verify that the payload is correct.
33.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 33–9 and Example 33–10.
In Example 33–9, an empty event with namespace uuid:1111 and local name MyEvent
is sent to the event bus.
In Example 33–10, the event contained in the file AnEvent.xml is sent to EDN.
33.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.
33.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.
33.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).
Stored Procedure
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:
■ PL/SQL stored procedures
■ Event Delivery Network database
■ SOA composite application that includes Oracle Mediator and other components
as needed.
34.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
PAYLOAD);
END;
34.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:
■ Verify the deployment of the SOA composite.
■ Test the SOA composite.
■ Verify the SOA composite test results.
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
4. In the Flow Trace window that displays, click the Oracle Mediator component, as
shown in Figure 34–2.
34.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 prior to implementing your own version of this use case.
Running the sample ensures that the EDN database queue works as expected.
Services
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 36, "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:
■ SOA composite application that includes a BPEL process service component
■ Oracle ADF web application that includes ADF Business Components
Figure 35–1 SOA Composite Application Accesses ADF Business Components Using
SOAP
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.
35.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
4. Implement the security as described in Section 35.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. Make an Oracle WebLogic Server connection to the container.
Note: Skip this step if deploying the profile to the WLS container
included in the SOA installation.
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. Create a SOA composite application that includes a BPEL process service
component. For more information, see the chapter "Developing SOA Composite
Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's
Guide for Oracle SOA Suite.
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.
Figure 35–3 shows the composite.xml file for the sample application.
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. Wire the BPEL component to the Oracle ADF web service
Use a web service binding so that the ADF Business Components service can be
remotely deployed.
For more information about wiring references, see the chapter "Developing SOA
Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
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 35–4 shows the BPEL
flow for the sample application.
Figure 35–4 BPEL Flow for Invoking an ADF Business Components Service
13. Implement the security as described in Section 35.5, "Securing the Design Pattern".
For information about securing the design pattern, see Section 51, "Securing Web
Services Use Cases."
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 Applications" in the Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
35.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.
If you invoke ADF Business Components service operations that use event-raising
entities, those events are not raised.
Composite
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.
36.2 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
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.
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 36–1 shows the XML for a bind activity that establishes OrderId as the
key that will be passed to retrieve orders.
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
Once 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 36.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 Applications" 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.
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.
36.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.
36.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 as a result of 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 36–3 includes a locally declared entity variable.
Because the variable was defined locally within the scope myScope, once 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 36–4 shows an entity variable defined globally, hence its scope will
complete when the instance completes.
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
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 36–5 illustrates the verification of variable data integrity.
Note: 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.
36.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 35,
"Orchestrating ADF Business Components Services" can be easily combined.
Composite
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:
■ Business component that accesses a PL/SQL stored procedure, and is published as
a service.
■ SOA composite application which includes a BPEL process service component that
accesses the ADF Business Components service.
37.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
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.
Composite
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:
■ Business component that contains a service method, and is published as a service;
or a Java class published as a web service.
■ SOA composite application that includes a BPEL process service component that
accesses the ADF Business Components service or the Java class web service.
■ 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.
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.
38.3 Example
Download the sample code for this use case from the following location. Oracle SOA
Suite samples.
38.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.
Application
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 needs to be raised to the employee's manager so that he or she 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. Once 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.
Instead of using the worklist application, you could use a custom task application or
APIs.
39.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 needs to 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.
These procedures are detailed in the remainder of this section.
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 36, "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 "Designing Human Tasks" in the Oracle
Fusion Middleware Developer's Guide for Oracle SOA Suite.
Note the following:
■ 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.
6. 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.
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 39–1.
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. Use Oracle Enterprise Manager Fusion Middleware Control Console to check if an
instance of the SOA composite application has been created. The process should be
in running state and waiting at the human task step.
For more information about Fusion Middleware Control Console, see the chapter
"Deploying SOA Composite Applications" of the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
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.
39.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.
– 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:
– Determine if there were any deployment errors.
– Enable logging for ADF as described in Section 39.8.4, "Logging." Set the log
level to FINE and deploy the task flow again. Once 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
39.8.4 Logging
You can set logging for the Workflow application and for the ADF task flow.
<logging_configuration>
<log_handlers>
......
<log_handler name="oracle-bpel-services-handler"
class="oracle.core.ojdl.logging.ODLHandlerFactory">
<property name="path" value="../log/wls/bpel/services"/>
<property name="maxFileSize" value="10485760"/>
<property name="maxLogSize" value="104857600"/>
</log_handlers>
<loggers>
.......
</loggers>
</logging_configuration>
39.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
Applications" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite
and Oracle Business Process Management Suite.
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.
Working with Data from a Remote ADF Business Components Service 40-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.
40.3 Example
Currently, no example is available.
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.
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. Register the targeted service in your connections.xml file (found in Application
Resources > Descriptors > ADF META-INF). This entry is needed during runtime
to invoke the service. Note that this also requires that the targeted service be
hosted and running, since the registration requires the URL of where the service is
deployed. Example 40–1 shows sample code used in the connections.xml file.
<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.
Working with Data from a Remote ADF Business Components Service 40-3
Known Issues and Workarounds
SOA Composite
Figure 41–1 illustrates the process flow of BPEL process invoking an asynchronous
service.
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.
41.3 Example
An interface table is populated by third-party entities using legacy interfaces, such as
FTP and files. Once 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
Defining the service reference to the asynchronous web service endpoint involves the
following tasks:
1. Define the new web service reference.
2. Wire the BPEL process to the new service reference.
3. Invoke the asynchronous web service from the BPEL flow.
4. Deploying and testing the composite.
■ 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 41–3 shows an example of a completed Create Web Service dialog.
41.4.2 Wiring the BPEL Process to the New Web Service Reference
In order 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.
■ Define a partner link in the BPEL process editor.
■ Drag the interface pin from the BPEL process to the service reference.
Defining a partner link involves additional work as compared to the alternative
approach of dragging the interface pins. However, when creating a partner link for a
web service that has not yet been defined as a service reference in the composite,
Oracle JDeveloper automatically creates the composite service reference and wires the
BPEL process to that service.
Dragging the interface pin from a component to a service is a quick and easy way to
automatically create partner links and other service component integrations, such as
wiring a Mediator to a Business Rule component. Wiring components by clicking and
dragging automatically generates the metadata files and entries used to support the
interaction between the components.
2. In the right-hand swim lane of the BPEL process, right-click the area under Partner
Links.
The Create Partner Link dialog displays, as shown in Figure 41–4.
41.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. Add required resilience and logging.
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. Invoke the service.
6. Add invoke, receive and assign activities.
a. 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.
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.
Figure 41–6 shows a completed Invoke Activity dialog.
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. In the Receive Activity dialog, enter the following information.
■ Name: Enter a name for the invoke activity, such as Invoke<ServiceName>.
■ Interaction Type: Select Partner Link.
■ 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.
Figure 41–7 shows a completed Receive Activity dialog.
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.
10. Name each assign activity.
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,
configure the following.
■ Variable: Select the contents of an element from the source variable, such as
the default BPEL inputVariable, as shown in Figure 41–8.
Note: If you receive an "Invalid XML" error message, ensure that all
elements are namespace qualified within the context of the fragment
as BPEL process namespaces are not scoped into fragments.
■ Partner Link: The contents and properties of a Partner Link (useful for
dynamic partner links).
13. Save your files.
14. Deploy the SOA composite application to the SOA infrastructure. For more
information, see "Deploying SOA Composite Applications" in Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
15. Test the application. For more information, see the chapter "Automating Testing of
SOA Composite Applications" in Oracle Fusion Middleware Developer's Guide for
Oracle SOA Suite.
41.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.
http://host:port/em
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. Enter the payload fields as needed and click Initiate.
4. Navigate to Oracle Enterprise Manager Fusion Middleware Control Console using
the following URL format.
http://host:port/em
5. Login to Oracle Enterprise Manager Fusion Middleware Control Console and take
the following actions.
a. On the left side of Oracle Enterprise Manager Fusion Middleware Control
Console, expand the SOA tree node.
b. Expand the soa-infra node for the correct SOA server and select the name of
the deployed 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.
41.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.
41.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 41.6, "Verifying the Deployment."
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:
■ ADF Business Components service
■ A local ADF Business Components object (such as an application module or an
entity object), or from a UI via either a local ADF Business Components object or a
managed JavaBean
Synchronously Invoking an ADF Business Components Service from an Oracle ADF Application 42-1
Example
42.3 Example
Currently, no example is available.
<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>
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. In your ADF Business Components service or managed Java bean class, invoke the
desired service using ServiceFactory, as shown in Example 42–2.
Synchronously Invoking an ADF Business Components Service from an Oracle ADF Application 42-3
Securing the Design Pattern
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);
Notes:
■ To date, the only supported Oracle ADF UI components for Active
Data Service (ADS) update are outputText and image.
■ This pattern is in the process of being re-written for conformance
to Oracle WebLogic Server and Oracle Java Messaging Service
(JMS) guidance and, in the interim, should be implemented with
the understanding that a re-write is pending.
43.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, needs to 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.
Figure 43–1 Technology Flow Diagram (with Optional Oracle Enterprise Scheduler Job
Submission)
Note: This procedure assumes that the JMS Module does not already
exist.
1. In the Oracle WebLogic Server Console, navigate to Messaging > JMS Modules.
2. Click New to create the JMS Module.
3. Name the module "FusionAppsADSJMSModule" and click Next.
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. In the Summary of Resources table, click New.
7. Choose Connection Factory and click Next.
8. Name the connection factory FusionAppsADSJMSConnectionFactory, provide
the JNDI name jms/Prototype/MyQueueConnFactory, and click Next.
9. Click Finish.
10. Verify the new connection factory in the Summary of Resources table and click
New.
11. Choose Queue and click Next.
import java.io.Serializable;
/**
* 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();
}
import java.io.Serializable;
import java.util.List;
import java.util.Hashtable;
import javax.jms.JMSException;
import javax.jms.MessageListener;
import javax.jms.ObjectMessage;
import javax.jms.Queue;
import javax.jms.QueueConnection;
import 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;
private JMSHelper() {
try {
init();
} catch (Exception e) {
e.printStackTrace();
}
}
/**
* 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();
}
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) {
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:
■ It is necessary to delegate all collection model-related logic to the model returned
by the tree binding. Inside the collection handler, you must get a handle to the
collection model returned by the tree binding by looking up the binding container.
As you reference the collection model often, store it somewhere for optimal
performance. Make sure the managed JavaBean has a view scope while the
binding container, tree binding or collection model has a request scope. You
cannot store the collection model on the JavaBean. Instead, store the collection
model in the request scope. When accessing the collection model, look it up first in
the request scope. If the value is null—for example, at the beginning of the
request—retrieve the value from the binding container.
■ When pushing the ActiveDataEvent through ADS, only the UI is updated with
the new value. The binding layer is not aware that the underlying data source has
changed. If the page is refreshed at this time, the UI displays the old data from the
import java.util.HashMap;
import java.util.Map;
import oracle.adf.view.rich.event.ActiveDataEntry;
if (names != null) {
_attributes = names;
_values = values;
_changeType = change;
_path = path;
_insertPath = insertKeyPath;
import java.util.Collections;
import java.util.List;
import oracle.adf.view.rich.event.ActiveDataEntry;
import oracle.adf.view.rich.event.ActiveDataUpdateEvent;
_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;
}
43.4.3 Registering the Active Data Collection Model with the Oracle ADF UI Page
In order to enable the active data feature and "hook" your collection model, you need
to register the class as a managed JavaBean.
ADS requires UI components to have the same model across requests. Therefore,
register the ActiveDataCollectionModel as a view scoped managed JavaBean. As
long as you stay on the same page, the table is based on the same model.
2. Add the managed JavaBean named adsBean and provide the package to your
collection model class, as shown in Example 43–8.
43.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. In order 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.
The table component requires the managed JavaBean shown in Example 43–9.
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 oracle.adf.model.OperationBinding;
import oracle.adf.model.binding.DCBindingContainer;
import oracle.adf.share.ADFContext;
import oracle.adf.view.rich.component.rich.data.RichTable;
import oracle.jbo.Key;
import org.apache.myfaces.trinidad.model.RowKeySet;
public TableHandlerBean() {
super();
}
FacesContext.getCurrentInstance().addMessage(null, msg);
}
}
rowBandingInterval="0"
filterModel="#{bindings.EmpView1Query.queryDescriptor}"
queryListener="#{bindings.EmpView1Query.processQuery}"
filterVisible="true" varStatus="vs"
selectionListener="#{bindings.EmpView1.collectionModel.makeCurrent}"
rowSelection="multiple" id="t1" width="100%"
binding="#{tableBean.table}">
43.4.6 Creating the Data Model and Adding Application Module Methods
The data model should exist before the page is built in order 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.
.
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.
■ changeType: enum (UPDATE, REFRESH). Currently, there is no use case for
INSERT.
■ key: Object[]
■ insertKey: Object[]
■ attributeNames: String[], a list of names of changed attributes
■ attributeValues: Object[], a list of new values for the changed attributes
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 43–12.
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 43–13 shows a simplified event
definition, while Example 43–14 shows an event schema definition.
</xsd:schema>
Note: It is critical that the event name and namespace are consistent
throughout the code and metadata definitions in the subscribing SOA
composite.
Subject name:
Enqueing complete
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:
■ Java code, such as an Oracle ADF application module or Oracle Enterprise
Scheduler Java job
■ SOA Domain with deployed human task
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:
■ Federated query support,
■ Programmatic access supports custom UI requirements and ADF Business
Components services and Oracle Enterprise Scheduler job integration.
44.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.
Example 44–1 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 oracle.bpel.services.workflow.IWorkflowConstants;
import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.repos.Ordering;
import oracle.bpel.services.workflow.repos.Predicate;
import oracle.bpel.services.workflow.repos.TableConstants;
import oracle.bpel.services.workflow.task.IInitiateTaskResponse;
import oracle.bpel.services.workflow.task.ITaskService;
import 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;
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(wscct, logger);
taskSvc = wfSvcClient.getTaskService();
querySvc = wfSvcClient.getTaskQueryService();
44.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 in order 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).
Example 44–4 Getting the Single Task Object with the Task ID
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 44–5 shows how to use STDOUT calls to display the various task attributes
through the task API.
44.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. Once 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.
■ Import libraries into the Java project.
■ Import code packages into the Java project.
■ Declare and obtain task query service object references.
■ Manage query and task outcome states.
Example 44–6 Declaring and Obtaining Task Query Service Object References
ITaskService taskSvc = null;
ITaskQueryService querySvc = null;
IWorkflowContext wfCtx = null;
try {
java.util.logging.Logger logger = Logger.getLogger("oracle.apps");
WorkflowServicesClientConfigurationType wscct =
getWorkflowClientConfigObject("FIN_SOA_RMI);
if ( wscct == null ) { // Log incident
return "FAILED!"; }
}
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(wscct, logger);
taskSvc = wfSvcClient.getTaskService();
querySvc = wfSvcClient.getTaskQueryService();
44.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:
■ Import libraries into the Java project.
■ Import code packages into the Java project.
■ Create a list of servers for a parallel federated query.
■ Declare task and query service references, and create the workflow client service
object.
■ Obtain the workflow service client.
■ Implement exception handling for federated queries.
■ Manage query and task outcome states.
Example 44–8 shows sample code in which a list of servers is created for a parallel
federated query.
44.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 44–9.
Example 44–9 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);
44.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:
■ Determine query service search criteria.
■ Construct the predicate for the queryTasks() method.
■ Arrange the order of results returned by the queryTasks() method.
■ Construct the list of display columns for the queryTasks() method.
■ Construct a list of OptionalInfo items for the results of the queryTasks() method.
■ Invoke the queryTasks() method with the attribute lists.
■ Iterate through the result set.
■ Programmatically set the task outcome.
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 44–1 and Table 44–2.
You can then query the WFTASK table using the task ID shown in the first column of
Table 44–1, as shown in Example 44–14.
The results of the entire table are too large to print, but the selected columns shown in
Table 44–3 may be useful.
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.
44.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 44–19 shows sample code that constructs a list of
display columns for queryTasks().
The queryTasks() method returns a list of tasks that match the predicate and
ordering criterion.
Example 44–22 shows how to invoke queryTasks() using the previously constructed
attribute lists.
Example 44–22 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.")
Example 44–25 Setting the Outcome of the Task Reference on the Single Server Task
Service
'APPROVE'.taskSvc.updateTaskOutcome(wfCtxt, t, "APPROVE");
Example 44–26 Setting the Outcome of the Task Reference on the Single Server Task
Service
'REJECT'.taskSvc.updateTaskOutcome(wfCtxt, t, "REJECT");
Example 44–27 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 44–28 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 44–29 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)
This ensures that the SOA composite has been deployed before creating a task
instance. For more information, see "Deploying SOA Composite Applications" in the
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
44.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.
Human Task
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:
■ Oracle ADF task flow for human tasks
■ Human task service component
45.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
45.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:
■ Creating an Oracle ADF task flow.
2. 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.
This creates the task flow containing a View component with the default name
taskDetails1_jspx, as shown in Figure 45–1. 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.
Note: Use the Property Inspector to add the template to the page, as
shown in Figure 45–2.
Do not modify the code in the first column, which corresponds to the first
<trh:cellFormat> with id="cf1", as shown in Figure 45–7.
Do any or all of the following:
■ If required, change the text attribute for the <af:showDetailHeader> component.
The default is set to "#{resources.DETAILS}", for example, Details.
■ If your page does not display product-specific information in this section, skip this
section and continue to the next section.
■ If your page displays product-specific information, add it to the third
<trh:cellFormat> component, which corresponds to the <trh:cellFormat>
with id="cf6" shown in Example 45–2.
■ 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.
Example 45–5 Oracle ADF code for the application specific content section
<af:showDetailHeader size="1" id="applicationContentHeader" text="<PLACE
APPLICATION SPECIFIC CONTENT HERE>" disclosed="true">
<af:panelGroupLayout id="payload_panel" layout="vertical"
shortDesc="#{resources.CONTENTS}">
<af:panelFormLayout id="pfl1">
<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="it3">
<f:validator binding="#{bindings.PayloadInput1.validator}"/>
</af:inputText>
</af:panelFormLayout>
</af:panelGroupLayout>
</af:showDetailHeader>
■ Add links to the bottom of this section, as shown in the pattern. The link
implementation instructions are discussed in Section 45.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.
...
</af:showDetailHeader>
<af:showDetailHeader size="1" id="historyHeader"
text="#{resources.HISTORY}"
disclosed="false">
...
</af:showDetailHeader>
■ 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 45.4.3.5,
"How to Implement Links."
– 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 a switcher component in the JSPX page to ensure that only supported
components are rendered in the email version. For more information, see
Section 45.4.5.3, "Using a Switcher Component."
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. Modify the transition value to closeTaskFlow.
2. Add a router.
a. Add a new router activity and rename it appropriately.
b. In the property inspector, set the default Outcome attribute to online.
c. Add two cases, as shown in Example 45–12.
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.
3. Set the newly introduced router as the default activity, as shown in Figure 45–10.
■ 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.
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 62, "Creating Customizable Applications."
Example 45–15 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.
Note: The provider URL refers to the soa-infra application, not the
domain. Do not change soa-infra.
...
<library-ref>
<library-name>oracle.soa.workflow.wc</library-name>
</library-ref>
...
</weblogic-application>
If your SOA runtime and task detail UI are running on different domains during
development, set the value to never for testing purposes only.
Pattern
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
■ Oracle Aqueue Adapter
■ The composite with the event subscription can be deployed to the Oracle SOA
Suite cluster which publishes the event.
46.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 46–1 lists the HCM composite components and values.
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
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:
■ FinInfrZxXFamilySubComposite. In this example, the LBA short name is FinInfr
and the Zx product subscribes to the cross-family event.
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.
<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 46–1.
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.
6. Open the composite.xml file and search for the following line.
<binding.jca config="EnqueueEventMessage_aq.jca"/>
7. Replace the binding.jca element with the code shown in Example 46–3.
8. Add standard fault policies to the composite just above the <component> elements
in the composite.xml file, as shown in Example 46–4.
<property name="oracle.composite.faultBindingFile">
oramds:/apps/oracle/apps/fnd/applcore/soa/fault/fault-bindings.xml</property>
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 46–5.
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. In the source tab, add a /child:node() element after <xsl:copy-of
select="/msg_out:FusionXFamilyEvent/msg_out:Payload>.
The XSL file should look similar to that shown in Example 46–6.
<?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
apps.context.header property, as shown in Figure 46–3.
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. In Fusion Applications Control, verify that an instance of the composite is
running.
b. Verify that a message is being enqueued (ensure the XFamilySub composite is
not deployed) by looking at the contents of the FUSION.ACR_XFAMILY_EVENTS_
QT table. The body of the message displays in the USER_DATA column. For
example:
select user_data from fusion.acr_xfamily_event_qt;
The statement should return the following results. Ensure SELECT, UPDATE, ENQUEUE,
and DEQUEUE privileges are returned, as shown in Example 46–11.
If any of these privileges are not defined in your environment, run the appropriate
command listed in Example 46–12.
This statement should return the results shown in Table 46–3. Confirm that the
ENQUEUE_ENABLED and DEQUEUE_ENABLED columns are set to YES for ACR_XFAMILY_
EVENT_Q.
If the queue is not enabled for enqueue or dequeue, run the command shown in
Example 46–14.
46.6.3 AQ_INVALID_QUEUE_TYPE
If you encounter the error message, shown in Example 46–15, take the following steps.
This error indicates that FUSION_RUNTIME does not have the appropriate privileges to
enqueue messages in the aqueue. Take the steps described in Section 46.6.1, "Privileges
to FUSION_RUNTIME."
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.
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:
■ Chapter 47, "Getting Started with Security"
■ Chapter 48, "Implementing Application User Sessions"
■ Chapter 49, "Implementing Oracle Fusion Data Security"
■ Chapter 50, "Implementing Function Security"
■ Chapter 51, "Securing Web Services Use Cases"
■ Chapter 52, "Securing End-to-End Portlet Applications"
47
Getting Started with Security
47
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:
■ Section 47.1, "Introduction to Securing Oracle Fusion Applications"
■ Section 47.2, "Authentication Techniques and Best Practices"
■ Section 47.3, "Authorization Techniques and Best Practices"
47.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.
Figure 47–1 depicts the components in the Oracle Fusion Applications security
approach.
■ Oracle Fusion Applications security policies for function security. For more
information, see Chapter 50, "Implementing Function Security."
Some of the technologies have an additional layer of security on top of the main
security technologies.
Figure 47–2 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 47–2, 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.
Figure 47–3 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 48, "Implementing Application
User Sessions."
47.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
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.
47.1.2.1.1 Users Test users created during development within Oracle JDeveloper
enable testing applications in development. These test users are not migrated with the
completed application. Rather, they are for testing purposes only. Enterprise users are
added by a system administrator who defines users/groups in the enterprise identity
store.
47.1.2.1.2 Roles Users are not assigned permissions directly, rather access is assigned
to roles. Roles group particular permissions required to accomplish a task; instead of
assigning individual permissions, roles match users with the permissions required to
complete their particular task.
There are two main types of roles, enterprise and application. Oracle Identity
Management Repository contains enterprise roles that are available across
applications. These are created as groups in LDAP, making them available across
applications. Application roles are stored in the application-specific policy store.
Functional roles include job, duty, data, abstract and privilege roles. Role are enforced
by a role hierarchy. In Oracle Identity Management Repository, these logical roles are
translated into technical Oracle Platform Security Services roles.
47.1.2.1.4 File-Based Identity Store The data in the file-based identity store
(jazn-data.xml file) is used when authenticating within Oracle JDeveloper running
Integrated WebLogic Server. The identity data in the jazn-data.xml file should not be
synchronized with the identities in the LDAP staging server. By default, the
deployment configuration disables data synchronization between the jazn-data.xml
file and the LDAP server. This setting should not be modified.
47.1.2.1.5 File-Based Policy Store The data in the file-based security policy store
(jazn-data.xml file) is used when authorizing within Oracle JDeveloper running
Integrated WebLogic Server. Changes to the security policies in the jazn-data.xml file
must be migrated to the LDAP staging server by a security administrator. By default,
the deployment configuration disables data synchronization between the
jazn-data.xml file and the LDAP server. This setting should not be modified.
47.1.2.1.6 ODI ODI has its own concept of identities such as ODI role and stores in the
ODI schema. For authentication, OPSS is used and the OPSS principals are mapped to
the ODI identities.
Audit Identity
When switching to the application identity, in order to preserve the submitting
identity for auditing purposes, you must propagate the identity to be audited.
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 47–1
illustrates the syntax of this method.
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 47–2.
47.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.
Roles
The jazn-data.xml file identity store contains the application roles specific to a given
application. These roles are not visible outside the application. The policies are created
against an application role. Permissions are grouped into a permission sets for
administrative purposes. And permission sets are granted to the application roles.
Developers must not allowed to modify role hierarchy or remove privileges defined by
the permission sets granted to existing application roles.
Design Time
During development, you can interact with the jazn-data.xml file policy store using
the tools and user interfaces provided in Oracle JDeveloper.
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.
Runtime
When Oracle ADF security is enabled in an application, the Web container uses the
policies in OPSS application policy store for authorization. Oracle ADF security
enforcement logic checks whether the user, represented by the JAAS subject, has the
correct permissions to access the resource.
The subject contains the user's principals, which include a user principal with the
user's name and list of role principals, as well as enterprise roles and application roles
obtained from the policy and identity stores. The principal is created to represent all of
the user's memberships in application roles defined in the policy store. In turn, each
application role may have multiple granted permissions in OPSS application policy
store.
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.
Design Time
During development, developers can interact with the Oracle Fusion Data Security
repository through the Oracle Authorization Policy Manager.
Runtime
Data security relies on session information for the user identity. When a user session is
created at runtime, the user information for that session and the flattened list of roles
for the user are propagated to the database. This information is used to identify the
user and the user's access level based on the policies in Oracle Fusion Data Security
repository.
Data security is not automatically enforced, rather developers must enforce data
security either declaratively on the entity object or view object, or programmatically,
using API calls.
47.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 in the Oracle Fusion
Middleware Application Security Guide.
For more information regarding data role templates, see the "Data Security" chapter in
the Oracle Fusion Applications Security Guide.
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:
■ Section 48.1, "Introduction to Application User Sessions"
■ Section 48.2, "Configuring Your Project to Use Application User Sessions"
■ Section 48.3, "Accessing Properties of the Applications Context"
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 48.3, "Accessing Properties of
the Applications Context."
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 in order to change the ordering of the filter mapping, you
must modify the web.xml file directly.
4. Save all changes.
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 50.3, "Adding
Function Security to the Application."
48.2.3 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 48.3,
"Accessing Properties of the Applications Context."
For details about enforcing security and granting access to application resources while
testing the applications, see Section 50.3, "Adding Function Security to the
Application."
attributes as they are defined in the session context. Note that developers can add their
own custom attributes as well.
Language attributes:
■ LANGUAGE - The language tag representing the current language.
■ NLS_LANG - The two-letter database language code. Derived from the language.
■ NLS_LANGUAGE - The database language. Derived from the language.
■ NLS_SORT - String sorting logic in database. This is from linguistic sorting support
project.
■ TERRITORY - Listed above as part of the customization context.
■ DATE_FORMAT - Format mask pattern for date parsing and formatting.
■ TIME_FORMAT - Format mask pattern for time parsing and formatting. This includes
time zone formatting.
■ GROUPING_SEPARATOR - Grouping separator for number formatting.
■ DECIMAL_SEPARATOR - Decimal separator for number formatting.
■ TIME_ZONE - User's preferred time zone in Oracle E-Business Suite (EBS) R12.
■ CURRENCY - The current currency code.
■ CLIENT_ENCODING - Client native encoding used for file uploading, downloading,
export, and attachment.
Miscellaneous attributes:
■ TRACE_LEVEL - The current tracing level when tracing is turned on.
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 a
number of attributes they wish to store on the session. Developer may currently
choose among the following APIs for initializing namespaces:
■ Java: ApplSession.initializeNamespace(String namespaceName)
■ PL/SQL: fnd_global.initialize_namespace (namespace_name IN VARCHAR2);
The Java and PL/SQL initializeNamespace routines are identical, just invoked from
different layers—these 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.
throws exception
{
//
// Create a session for the OPERATIONS user
//
List<String> roleGuids = new ArrayList<String>(1);
List<String> roleNames = new ArrayList<String>(1);
roleGuids.add("1807EDD02DBB11DDBFDC91643D402C34");
roleNames.add("operationsRole");
ApplSession session =
ApplSessionUtil,initializeSession("43B84790D5F011DCAF4F5FFD8462C8E7",
"OPERATIONS", roleGuids, roleNames, null);
}
@AfterClass
public static void tearDownAfterClass()
throws exception
{
//
// note that if a connection to the 'initializeSession' call had been passed
// in, it would would have to be freed here. Since null is passed in, the
// connection that was obtained in that call will be freed automatically.
//
ApplSessionUtil.terminateSession();
}
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. Example 48–4 shows a mechanism for getting generic attributes.
Example 48–5 shows the API you use to fetch attributes from a particular namespace.
session.releaseConnection(conn);
}
}
}
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.
Whenever the TestVO view object is displayed, by default it will include the
current user name field.
Example 48–9 uses the SysadminInfo field that was added to the TestVO view object to
display a value when running the FND product.
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:
■ Section 49.1, "Introduction to Oracle Fusion Data Security"
■ Section 49.2, "Managing Data Security Artifacts in the Oracle Fusion Data Security
Policy Tables"
■ Section 49.3, "Integrating with ADF Business Components"
■ Section 49.4, "Using Oracle Fusion Data Security to Secure New Business
Resources"
■ Section 49.5, "Getting Security Information from the Application User Session
Context"
■ Section 49.6, "Understanding Data Security Performance Best Practices"
■ Section 49.7, "Validating Data Security with Diagnostic Scripts"
■ Section 49.8, "Integrating with Data Security Task Flows"
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,
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.
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 Oracle Fusion
Applications Security Guide.
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 needs to 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.
Figure 49–1 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.
49.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: The action name alone is not unique on the table; the
combination of an action name and resource is what makes it unique.
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 49.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.
49.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.
49.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 Oracle Fusion Applications Common
Implementation Guide.
If data security task flows are used in a web application, that web application must be
configured to use ADF Security in order 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 50,
"Implementing Function Security."
Table 49–1 lists the task flows and their parameters.
49.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
49.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.
Note: 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.
For details about managing data security, see the "Managing Oracle
Fusion Applications Data Security Policies" chapter in the Oracle
Fusion Middleware Oracle Authorization Policy Manager Administrator's
Guide (Oracle Fusion Applications Edition).
49.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.
Table 49–2 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.
Example 49–1 Making the Oracle Fusion Data Security Provider the Data Security
Provider
dataSecurityProviderClass=
"oracle.apps.fnd.applcore.dataSecurity.util.FndDataSecurityProvider"
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 once 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 49.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 needs to be done, you
must use a custom action.
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 adf-config.xml when you secure the read operation on the entity
object), to identify the WHERE clause (if any) that needs to be added to the SQL
statement for the entity object. This is done prior to executing the query.
Once 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.
2. In the overview editor for the entity object, click the General navigation tab and
expand the Security section.
3. In the Security section, select the read action.
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.
4. Select Both for the Query Execution Mode, as shown in Figure 49–4.
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 Figure 49–5.
Alternatively, you can apply the view criteria at runtime in your code by calling
the view object's applyViewCriteria(viewCriteriaName) API.
Figure 49–5 Application Module Overview Editor — Edit View Instance Dialog
49.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 in order to 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 Example 49–3.
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.
49.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.
■ Example 49–4 shows the Expression Language expression to use on ADF bindings
for view object attributes.
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 Example 49–5.
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 Example 49–6 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 Example 49–5
with a custom action.
Do not use the expression shown in Example 49–8 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 Example 49–7 with a
custom action.
■ 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.
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 Example 49–9 if the
view object is an updateable view object based on an entity object.
■ When using Groovy expressions, use the expression shown in Example 49–10 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.
Example 49–11 shows an EL expression to conditionally render the UI component
for the Gender attribute:
<af:inputText value="#{bindings.TransientGenderAttr.inputValue}"
label="#{bindings.TransientGenderAttr.hints.label}"
required="#{bindings.TransientGenderAttr.hints.mandatory}"
columns="#{bindings.TransientGenderAttr.hints.displayWidth}"
maximumLength="#{bindings.TransientGenderAttr.hints.precision}"
shortDesc="#{bindings.TransientGenderAttr.hints.tooltip}"
rendered="false"
id="it1">
</af:inputText>
<f:facet name="footer">
<af:panelGroupLayout layout="vertical" id="pgl1">
<af:panelGroupLayout layout="horizontal" id="pgl2">
<af:commandButton actionListener="#{bindings.First.execute}"
text="#{applcoreBundle.FIRST}"
disabled="#{!bindings.First.enabled}"
partialSubmit="true" id="cb3"/>
<af:commandButton actionListener="#{bindings.Previous.execute}"
text="#{applcoreBundle.PREVIOUS}"
disabled="#{!bindings.Previous.enabled}"
partialSubmit="true" id="cb1"/>
<af:commandButton actionListener="#{bindings.Next.execute}"
text="#{applcoreBundle.NEXT}"
disabled="#{!bindings.Next.enabled}"
partialSubmit="true" id="cb4"/>
<af:commandButton actionListener="#{bindings.Last.execute}"
text="#{applcoreBundle.LAST}"
disabled="#{!bindings.Last.enabled}"
partialSubmit="true" id="cb5"/>
</af:panelGroupLayout>
<af:commandButton text="#{applcoreBundle.SUBMIT}" id="cb2"/>
</af:panelGroupLayout>
</f:facet>
</af:panelFormLayout>
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.
49.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.
Table 49–3 lists the document category definitions for the table.
5. Identify aggregate actions for which policies are made for this entity:
■ Create an aggregate action named FND_DEMO_ATTACHMENT_VIEW for the read
operation, which contains actions named read and FND_DEMO_ATTACHMENT_
VIEW.
■ Create an aggregate action named FND_DEMO_ATTACHMENT_ADMIN, which allows
a user to administer this resource. It has read, update, and delete actions. This
aggregate action contains read, update, delete, FND_DEMO_ATTACHMENT_VIEW,
FND_DEMO_ATTACHMENT_UPD, and FND_DEMO_ATTACHMENT_DEL actions.
6. Compile the menus in the database by executing:
fnd_function.compile_all_from_scratch;
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.
Integer Equality:
Example 49–13 shows the correct Integer equality format to use.
Example 49–14 shows Integer equality formats that you should NOT use.
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.
Integer Range:
Example 49–15 shows the correct Integer range format to use.
Example 49–16 shows Integer range formats that you should NOT use.
Float Equality:
Example 49–17 shows the correct Float equality format to use.
Example 49–18 shows Float equality formats that you should NOT use.
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:
Example 49–19 shows the correct Float range format to use.
Example 49–20 shows Float range formats that you should NOT use.
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:
Example 49–21 shows the correct Date equality format to use.
Example 49–22 shows Date equality formats that you should NOT use.
Date Range:
Example 49–23 shows the correct Date range format to use.
Example 49–24 shows Date range formats that you should NOT use.
In this case, you can use to_char() with a format mask because the canonical format
maintains proper ordering of the character domain.
Example 49–25 Oracle Platform Security Services (OPSS) XML Policy Store
<?xml version="1.0" encoding="windows-1252" standalone="yes" ?>
<jazn-data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oraclass/schema/jazn-data-1
1_0.xsd">
<jazn-realm default="jazn.com">
<realm>
<name>jazn.com</name>
<users>
<user>
<name>admin</name>
<credentials>{903}Qh3td3z2HHlun9ROrbvE6bYJDnNaoGir</credentials>
</user>
<user>
<name>joeUser</name>
<credentials>{903}FarN3p4C9IU9PZODN5RLmrpHf45eCw+W</credentials>
</user>
</users>
<roles>
<role>
<name>adminRole</name>
<members>
<member>
<type>user</type>
<name>admin</name>
</member>
</members>
</role>
<role>
<name>regularUserRole</name>
<members>
<member>
<type>user</type>
<name>admin</name>
</member>
<member>
<type>user</type>
<name>joeUser</name>
</member>
</members>
</role>
</roles>
</realm>
</jazn-realm>
</jazn-data>
49.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 "Securing Oracle
Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.
49.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 Example 49–26.
Where DataContext is a container class that represents the resource and optionally
the primary keys of that resource for which data security check needs to be done.
It has the following attributes: ObjectName, PK1, PK2, PK3, PK4, PK5.
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 Example 49–27.
■ Get all the actions available on a given row instance for the current user, as shown
in Example 49–28.
■ Get all the aggregate actions available on a given row instance for the current user,
as shown in Example 49–29.
As shown in Example 49–30, static APIs are also provided in the DataSecurityAMImpl
class for the above core methods that take in a DBTransaction object.
49.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.
/* (Optional) */
);
performance problems with queries that apply data security to more than 100 rows,
the query needs to be made more selective. Blind queries against tables secured with
data security are not allowed.
Note: There are no plans to provide any APIs to answer the question
"What users have access to a particular function on a particular row
instance?" The reason being is that the condition predicates can
reference context that can be driven by the user, like profiles. The only
way to answer that question would be to loop through every user and
set up their context (including profiles, and so on), and then see if they
had access. That is not practical given the large number of users that
are possible. For the same reason, data security does not try to answer
the question "Does a particular user have access to a particular function?"
Note: The data security diagnostic scripts may be run in the WLST
scripting environment or from the Diagnostic Dashboard application
of any Oracle Fusion application. The Diagnostic Dashboard provides
administrators with a graphical user interface to execute and monitor
diagnostic tests. For more information about the Diagnostic
Dashboard, see the "Standard Diagnostic Testing Administration
Tasks and Tools" section in the Oracle Fusion Applications
Administrator's Guide.
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.
Note: If you only want the script to perform the application configuration
validation and the database metadata validation checks, you can skip this step by
pressing Enter when prompted to enter the value for session cookie.
■ Connects to the database and validates the FUSION.FND_SESSION_MGMT PL/SQL
package to check for its consistency. The script checks whether a valid package
header and package body is defined for the package and outputs the result to the
output file ApplsessionDiagResults.out.
example, these task flows can give Human Resources managers the ability to secure
employee records to grant HR representatives access to defined groups of employee
records.
Oracle Fusion Middleware Extensions for Applications data security task flows use
Oracle Fusion Applications security technology to implement data security policies in
Oracle Fusion Applications FND tables and function security policies in the LDAP
policy store. At runtime, the task flows implementation performs the necessary
backend operations to both secure data exposed by a business object (data security)
and to secure the user interface (function security) that displays the business objects.
The following task flows are available and may be integrated using Oracle JDeveloper:
■ 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.
49.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.
Table 49–4 Data Security Task Flows and Their Input Parameters
Task Flow Name Task Flow XML Parameters Passed Behavior
Object-centric task /WEB-INF/oracle/apps/fnd/ Specify the name of the object for which Create and
flow (also referred applcore/dataSecurity/ui/ the grant will be managed: manage grants to
to as taskflow/ObjectLevelFT.xml multiple
objectName
(ObjectLevelTF) application roles
Specify the list of role categories from for a single
which the available application roles will business object.
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
Table 49–4 (Cont.) Data Security Task Flows and Their Input Parameters
Task Flow Name Task Flow XML Parameters Passed Behavior
Role-centric task /WEB-INF/oracle/apps/fnd/ Specify the list of role categories from Create and
flow (also referred applcore/dataSecurity/ui/ which the available application roles will manage grants to
to as ProfileTF) taskflow/ProfileTF.xml be fetched: a single
application role
roleCategories
profile for
Specify the list of securable actions to be multiple
displayed in the UI for the object: 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
Instance-level task /WEB-INF/oracle/apps/fnd/ Specify the name of the parent object Confer existing
flow (also referred applcore/dataSecurity/ui/ from which the object instance will be grants for a
to as taskflow/ObjectInstTF.xml fetched: single instance of
ObjectInstTF) a business object
objectName
to another user
Specify the primary key of the object (or user group).
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 /WEB-INF/oracle/apps/fnd/ Specify the list of role categories from Create and edit
task flow (also applcore/dataSecurity/ui/ which the available application roles will custom
referred to as taskflow/RoleManagementTF. be fetched: application roles.
RoleManagementTF) xml roleCategories
Specify the title of the task flow UI:
title
49.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.
49.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.
Example 49–33 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.
<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>
Example 49–34 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 49–35 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.
</task-flow-call>
2. 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 49.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 49–33.
■ If you dropped the role-centric task flow (the activity references task flow
<id>ProfileTF</id>), add the input parameter values from Example 49–34.
■ If you dropped the role management task flow (the activity references task
flow <id>RoleManagementTF</id>), add the input parameter values from
Example 49–35.
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.
49.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:
■ Initialize the input parameters of the data security task flows.
■ 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.
Example 49–36 shows the additional source code that your managed bean must
include to initialize the object-centric (ObjectLevelTF) task flow.
//for action1
List<String> instanceSets1 = new ArrayList<String>();
instanceSets1.add("TEST_EMP_IS1");
instanceSets1.add("TEST_EMP_IS2");
instanceSets1.add("TEST_EMP_IS3");
//for action 2
List<String> instanceSets2 = new ArrayList<String>();
instanceSets2.add("TEST_EMP_IS2");
instanceSets2.add("TEST_EMP_IS3");
instanceSets2.add("TEST_EMP_IS4");
Example 49–37 shows the additional source code that your managed bean must
include to initialize the role-centric (ProfileTF) task flow.
//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"));
//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"));
pageFlowScope.put("roleCategories", roleCategories);
pageFlowScope.put("actions", actions);
pageFlowScope.put("disableViewAll", false);
pageFlowScope.put("disableUpdateAll", false);
Example 49–38 shows the additional source code that your managed bean must
include to initialize the role management (RoleManagementTF) task flow.
Example 49–39 Button Component with Action Attribute to Invoke Bean Method
<af:commandButton text="Manage Roles" id="cb1"
action="#{backingBeanScope.roleManageBean.initializeRoleManagement}"/>
For details about creating the control flow case in your application's task flow, see
Section 49.8.2.1, "Creating a Task Flow Call Activity in Your Application's Task
Flow."
49.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. Example 49–40 uses the bean identifier roleManageBean to match the Action
attribute definition specified on the button component shown in Example 49–39.
Example 49–40 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>
2. 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 Example 49–40.
49.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
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. In the web page, drop an ADF command button component.
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.
49.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 49–42.
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.
Example 49–41 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 49–42 Button Component with Show Popup Operation to Invoke Dialog
...
<af:panelHeader id="phl12" text="Test Instance UI">
<af:panelGroupLayout id="pgl13" layout="horizontal">
<af:commandButton id="cb6" text="Launch Object Instance Popup"
partialSubmit="true">
<af:showPopupBehavior popupId="objInst"/>
</af:commandButton>
<af:popup id="objInst" contentDelivery="lazyUncached"
popupFetchListener="#{backingBeanScope.objectInstanceBean.launchPolicy}"
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>
2. 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. In the task flow diagram, enter the outcome value.
The value of the outcome should match the return value of the initialization
method you create in the managed bean used to populate the data security input
parameters. For details about the managed bean, see Section 49.8.2.2, "Initializing
the Data Security Task Flow Using a Managed Bean."
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 49–33.
■ If you dropped the role-centric task flow (activity will show task flow
reference <id>ProfileTK</id>), add the input parameter values from
Example 49–34.
■ If you dropped the role management task flow (activity will show task flow
reference <id>RoleManagementTF</id>), add the input parameter values from
Example 49–35.
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.
ActionMap.getActionMapForInstanceUI("Delete", "DELETE_EMP_M");
actions.add(action4);
ActionMap action5 =
ActionMap.getActionMapForInstanceUI("CustomFSOnlyAction",
"CUSTOMFSONLYACTION_EMP_M");
actions.add(action5);
pageFlowScope.put("instancePK1", "2");
pageFlowScope.put("instancePK2", null);
pageFlowScope.put("instancePK3", null);
pageFlowScope.put("instancePK4", null);
pageFlowScope.put("instancePK5", 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");
Example 49–44 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 49–42.
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 49–42).
6. In the method definition, create the save operation by copying and pasting from
Example 49–44 into the new save grants method definition.
Copying from the sample ensures the method saveInstanceGrants() is called
exactly as shown.
49.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. Example 49–45 uses the bean identifier objectInstanceBean to match the bean
references specified in the listener properties shown in Example 49–42.
Example 49–45 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>
2. 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 Example 49–45.
49.8.4 How to Grant the End User Access to the Data Security Task Flows
The data security task flows, once 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. Example 49–46
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
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.
2. In the source for the jazn-data.xml file, add the permission definition shown in
Example 49–46 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. Save the jazn-data.xml file.
49.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. Example 49–47 shows the code source grant where
<application-name> is the application name specified in the jazn-data.xml policy
store.
Example 49–47 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
Example 49–47 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. Save the jazn-data.xml file.
2. In the source for the web.xml file, add the web application initialization parameter
shown in Example 49–48 beneath the JPS filter.
The application name you enter must match the application name identified in the
policy store definition.
3. Save the web.xml file.
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 for the purpose of 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.
Note: The term protected in this chapter refers to the default Oracle
Fusion application condition that denies end users access to database
resources and application artifacts. In contrast, the term secured refers
to resources that have been made accessible to end users through
security policies created for this purpose. Therefore, a security policy
specifically enables access to the resource based on the access rights it
confers to the end user.
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 50.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 Oracle Fusion
Applications Policies" chapter in the Oracle Fusion Middleware Oracle Authorization
Policy Manager Administrator's Guide (Oracle Fusion Applications Edition).
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 "Managing Policies and Policy
Objects" chapter in the Oracle Fusion Middleware Oracle Authorization Policy Manager
Administrator's Guide (Oracle Fusion Applications Edition).
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 "Securing Oracle Fusion Applications" chapter in
the Oracle Fusion Applications Administrator's Guide.
13. Continue testing the application in the staging environment before deploying the
application to production and merging the policies into the production
environment application policy store.
For details about how to modify the application to use the identity store and
policy store of the staging environment, see Section 50.3.8, "What You May Need
to Know About Testing."
In cases where a resource should be publicly accessible, you will not need to aggregate
multiple resources to define a particular duty. Instead, you can create a resource-based
function security policy with a single resource /action pair defined as the grantable
entity.
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.
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 in the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
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.
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.
11. You can repeat these steps to add other resources and make grants on those
resources to the same entitlement for the same custom application role.
<jazn-data>
<policy-store>
<applications>
<application>
<name>MyApp</name>
<app-roles>
<app-role>
<name>AppRole</name>
<display-name>AppRole display name</display-name>
<description>AppRole description</description>
<guid>F5494E409CFB11DEBFEBC11296284F58</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
</app-role>
</app-roles>
<role-categories>
<role-category>
<name>MyAppRoleCategory</name>
<display-name>MyAppRoleCategory display name</display-name>
<description>MyAppRoleCategory description</description>
</role-category>
</role-categories>
<resources>
<resource>
<name>MyResource</name>
<display-name>MyResource display name</display-name>
<description>MyResource description</description>
<type-name-ref>APredefinedResourceType</type-name-ref>
</resource>
</resources>
</permission-sets>
It may also be helpful to understand the details of the ADF Security containment
model. For more information, see Section 50.3.9, "What You May Need to Know About
Security Best Practices."
You will need to complete this task:
■ 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 50.2,
"Function Security Implementation Process Overview."
2. 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:
■ anonymous-role means the resource will be accessible to anyone who visits
the site. A grant to this role is necessary if you want to make web pages
backed by securable ADF artifacts accessible before an end user logs in. For
example, you would grant to anonymous-role for an ADF bounded task flow
that manages customer registration.
■ authenticated-role means the resource will be accessible only to authenticated
users (ones who visit the site and log in). For example, you would grant to
authenticated-role for an ADF bounded task flow that manages employee
registration.
6. In the Select Application Roles dialog, click OK.
7. In the Resource Grants page of the overview editor, in the Actions column, select
the desired action.
Figure 50–2 shows the overview editor with the View action selected for the task
flow and granted to authenticated-role.
</grant>
...
</jazn-policy>
</policy-store>
To enforce authorization:
1. In the main menu, choose Application and then Secure > Configure ADF
Security.
2. Update the wizard pages as follows:
ADF Security: Select ADF Authentication and Authorization (default), as shown
in Figure 50–3. Click Next.
50.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.
■ Add or remove entitlement grants on predefined application roles (those supplied
by Oracle).
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.
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 "Securing Oracle
Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.
50.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 once 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 single 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 once ADF
Security is enabled. Therefore, it should never be deployed, since it grants access
to the application for non-authenticated users.
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:
■ Section 51.1, "Introduction to Securing Web Services Use Cases"
■ Section 51.2, "Understanding Oracle Web Services Manager Best Practices"
■ Section 51.3, "Attaching Policies Globally"
■ Section 51.4, "Attaching Policies Locally"
■ Section 51.5, "Authorizing the Web Service with Entitlement Grants"
■ Section 51.6, "What Happens At Runtime: How Policies Are Enforced"
The Mediator can invoke various BPEL processes based on the incoming event. It
can also transform the event to the payload that BPEL process takes.
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).
Figure 51–1 illustrates the possible event generation use cases for Oracle Fusion
applications. The main use case flow—ADF Business Components-generated
events—is 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).
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: All Oracle Fusion application Web services should use global
policy attachment wherever possible. For complete details about how
a system administrator attaches policies globally, see the
"Understanding Oracle WSM Policy Framework" chapter in Oracle
Fusion Middleware Security and Administrator's Guide for Web Services.
■ 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 needs to 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.
Table 51–1 Recommended Oracle Web Services Manager Policies for Oracle Fusion Applications
Profile Service Side Policy Client Side Policy Features
Authentication wss_saml_or_username_ Username: Performance: High
(AuthN) token_service_policy wss10_saml_token_ Security: Low
client_policy - Authentication: password in clear,
SAML: SAML token is unsigned.
wss10_saml_token_ - Wire level security: No
client_policy - Hardening: no
Configuration: Easy. No key stores to
set up.
Interoperability:
- Username: High interoperates easily
with many different stacks, including
.NET, SOAP-UI, and more.
- SAML: Low. Unsigned SAML SV
does not interoperate with most stacks.
Table 51–1 (Cont.) Recommended Oracle Web Services Manager Policies for Oracle Fusion Applications
Profile Service Side Policy Client Side Policy Features
SSL Profile wss_saml_or_username_ Username: Performance: Medium
token_over_ssl_ wss10_saml_token_ Security: Medium
service_policy client_policy - Authentication: passwords
SAML: encrypted because of 1-way-SSL,
SAML token is signed by virtue of
wss10_saml_token_
2-way-SSL.
client_policy
- 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 OHS
URI must be set up for both 1-way and
2-way-SSL and the client certificate
needs to be set propagated from OHS
to Oracle WLS. For details, see the
Oracle Fusion Middleware Security and
Administrator's Guide for Web Services.
Interoperatiblity:
- Username: High
- SAML: Medium
Message wss11_saml_or_ Username: Performance: Medium
Security username_token_with_ wss10_saml_token_ Security: High
message_protection_ client_policy
service_policy - Wire level security: Transport level
SAML:
- Hardening: High. Not only each
wss10_saml_token_ server, but each Web service can have
client_policy its own separate key.
Configuration: Medium. Key stores
need to be set up.
Interoperatiblity:
- Username: Medium
- SAML: Medium
No Behavior oracle/no_ oracle/no_ No security. Service will be accessible.
authentication_ authentication_
service_policy client_policy
For more information about directly attaching the no behavior policy to a Web service
endpoint, see the "Creating and Managing Policy Sets" chapter in the Oracle Fusion
Middleware Security and Administrator's Guide for Web Services.
In the case of an ADF Business Components Web service, you can enter service
annotations in the Web service implementation class to specify the no behavior policy,
as shown in Example 51–1.
Example 51–1 Enabling No Behavior Policy for an ADF Business Components Web
Service
@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 in 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 in the Oracle Fusion Middleware Security
and Administrator's Guide for Web Services.
Note: Even though you need to use LPA on the client side to
perform configuration overrides, you can still use GPA on the service
side. This is because on the service side you do not need a
configuration override to set up a particular user name, instead you
just attach the saml_or_username policy which will accept either user
names (for identity escalation) or saml (for identity propagation).
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 Example 51–2
Example 51–2 Attaching a Local Policy for an ADF Business Components Web Service
@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.
51.4.3 How to Provide Additional Security Hardening for Web Service Clients
Typically, Fusion Web services use a common domain wide key, which should be
used 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 in the Oracle Fusion Middleware Security and Administrator's Guide for Web
Services.
2. Enforce ADF Security authorization for the Web service in the Web service
implementation class.
<app-roles>
<app-role>
<name>AppRole</name>
<display-name>AppRole display name</display-name>
<description>AppRole description</description>
<guid>F5494E409CFB11DEBFEBC11296284F58</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
</app-role>
</app-roles>
<role-categories>
<role-category>
<name>MyAppRoleCategory</name>
<display-name>MyAppRoleCategory display name</display-name>
<description>MyAppRoleCategory description</description>
</role-category>
</role-categories>
<resource-types>
<resource-type>
<name>WebserviceResourceType</name>
<display-name>WebserviceResourceType</display-name>
<description>Webservice Resource</description>
<provider-name />
<matcher-class>oracle.wsm.security.WSFunctionPermission</matcher-class>
<actions-delimiter>,</actions-delimiter>
<actions>invoke</actions>
</resource-type>
</resource-types>
<resources>
<resource>
<name>http://xmlns.oracle.com/apps/financials/subledgerAccounting
/accountingMethodSetup/accountRulesService/AccountRulesService#*
</name>
<type-name-ref>WebserviceResourceType</type-name-ref>
</resource>
<resource>
<name>http://xmlns.oracle.com/apps/contracts/termsAuthoring/deliverables
/service/DeliverableService#findDeliverableByDeliverableId
</name>
<type-name-ref>WebserviceResourceType</type-name-ref>
</resource>
</resources>
<principal>
<class>
oracle.security.jps.service.policystore.ApplicationRole
</class>
<name>AppRole</name>
<guid>F5494E409CFB11DEBFEBC11296284F58</guid>
</principal>
</principals>
</grantee>
For details about the ADF Security, see the "Enabling ADF Security in a Fusion Web
Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
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, as long as 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 Example 51–4.
Example 51–4 Enforcing Authorization with ADF Business Components Policy Interceptor
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 Example 51–5.
Example 51–5 Configuring the JPSInterceptor for the Application in the ejb-jar.xml File
<?xml version = '1.0' encoding = 'windows-1252'?>
<ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/j2ee/ejb-jar_3_0.xsd" version="3.0"
xmlns="http://java.sun.com/xml/ns/javaee">
<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 in the Oracle Fusion
Middleware Developer's Guide for Oracle Application Development Framework.
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 52.1, "Introduction to Securing End-to-End Portlet Applications"
■ Section 52.2, "Securing the Portlet Service"
■ Section 52.3, "Securing the Portlet Client"
■ Section 52.4, "Registering the Key Store and Writing to the Credential Store"
The requirements for the client counterparts for each of these ports is exactly 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.
Table 52–1 summarizes the policies attached to the portlet service and the client.
Table 52–1 Recommended Oracle Web Services Manager Policies for Oracle Fusion
Portlets
Port Service Side Policy Client Side Policy
WSRP_v2_Markup_Service No local policy. Inherits from No local policy. Inherits from
GPA, which by default is GPA, which by default is
oracle/wss_saml_or_username_ oracle/wss_saml_or_
token_service_policy. username_token_client_
policy.
WSRP_v2_ Local anonymous policy: Local anonymous policy:
PortletManagement_ oracle/no_authentication_ oracle/no_authentication_
Service service_policy client_policy
WSRP_v2_Registration_ Local anonymous policy: Local anonymous policy:
Service oracle/no_authentication_ oracle/no_authentication_
service_policy client_policy
WSRP_v2_ Local anonymous policy: Local anonymous policy:
ServiceDescription_ oracle/no_authentication_ oracle/no_authentication_
Service service_policy client_policy
To override GPA and secure end-to-end portlet applications with a locally attached
policy:
■ Secure the portlet service.
■ Secure the portlet client.
■ Register the key store.
■ Write to the credential store.
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.
2. Verify the existence of the entry shown in Example 52–2. This code should be
configured out of the box.
3. Make sure the default context references the key store and credential store service
instances as shown in Example 52–3.
Example 52–3 Default Context References to the Credential Store and Key Store
<jpsContext name="default">
<serviceInstanceRef ref="credstore"/>
<serviceInstanceRef ref="policystore.xml"/>
<serviceInstanceRef ref="audit"/>
<serviceInstanceRef ref="idstore.ldap"/>
<serviceInstanceRef ref="keystore"/>
</jpsContext>
Once 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 Example 52–4.
Example 52–5 shows an entitlement grant enabling access to the task flow.
<app-roles>
<app-role>
<name>AppRole</name>
<display-name>AppRole display name</display-name>
<description>AppRole description</description>
<guid>F5494E409CFB11DEBFEBC11296284F58</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
</app-role>
</app-roles>
</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>
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
specify a Default User in the producer registration, using a valid guest user account, as
described in Section 52.3, "Securing the Portlet Client."
52.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.
52.4.1 How to Register the Key Store and Write to the Credential Store
■ 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
■ Key Alias: Enter the name of the signature key.
■ Signature Password/Confirm Password: Enter the required password, then
confirm the password.
Encryption Key
■ Crypt Alias: Enter the name of the encryption key.
■ Crypt Password/Confirm Password: Enter the required password, then
confirm the password.
7. Restart your domain.
52.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.
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.
Oracle Fusion Middleware Application Seed Data is 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.
This part contains the following chapters:
■ Chapter 53, "Running and Deploying Applications on Oracle WebLogic Server"
■ Chapter 54, "Creating Repository Connections"
■ Chapter 55, "Defining Profiles"
■ Chapter 56, "Initializing Oracle Fusion Application Data Using the Seed Data
Loader"
■ Chapter 57, "Using the Database Schema Deployment Framework"
■ Chapter 58, "Improving Performance"
■ Chapter 59, "Debugging Oracle ADF and Oracle SOA Suite"
■ Chapter 60, "Designing and Securing View Objects for Oracle Business Intelligence
Applications"
■ Chapter 61, "Implementing ADF Desktop Integration"
■ Chapter 62, "Creating Customizable Applications"
■ Chapter 63, "Working with Extensions to Oracle Enterprise Scheduler"
■ Chapter 64, "Oracle Enterprise Scheduler Security"
53
Running and Deploying Applications on
53
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 for the purpose of performing
end-to end testing of new applications. If you are deploying customizations or
extensions, see the Oracle Fusion Applications Extensibility Guide.
This chapter includes the following sections:
■ Section 53.1, "Introduction to Deploying Applications to Oracle WebLogic Server"
■ Section 53.2, "Running Applications on Integrated WebLogic Server"
■ Section 53.3, "Preparing to Deploy Oracle ADF Applications to an Administration
Server Instance of WebLogic Server"
■ Section 53.4, "Deploying Your Oracle ADF Applications to an Administration
Server Instance of WebLogic Server"
■ Section 53.5, "Deploying Your SOA Projects to an Administration Server Instance
of WebLogic Server"
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.
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 as
long as 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 53.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 53.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.
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 53–3.
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:
■ Administration Server - Oracle ADF (includes ESS libraries)
■ Administration Server - Oracle ADF + ESS Runtime
■ Administration Server - Oracle ADF and Managed Server - ESS Runtime
■ Administration Server - Oracle ADF and Managed Server - SOA
■ Administration Server and Managed Server - SOA
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 53–5.
To terminate the server, select the server name, as shown in Figure 53–6.
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.
– Understand LDAP-based stores. For more information, see Section 50.3.8,
"What You May Need to Know About Testing."
Caution: Make sure that there are no blank spaces between the tag
<library-ref> and the actual entry as they will cause problems.
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. Once 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
of WebLogic Server. For more information about registering MDS, see the Oracle Fusion
Middleware Administrator's Guide.
j. Click Finish to close the wizard and create your application server connection.
To deploy an application:
1. Deploy your project to the application server:
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
Note: If you are deploying an Oracle ADF application, do not use the
Deploy to all instances in the domain option.
e. Click Finish.
2. Verify the run-time application as:
http://httpHost:httpPORT/<CONTEXT>/faces/<landing jspx
For example,
http://server06.us.company.com:7001/UIPatternsDemo/faces/ServiceRequest
http://server12.company.com:7001/D7Build1-ViewController-context-root/faces/TreeHom
ePage.jspx
The basic steps to deploying your SOA project from within JDeveloper are:
1. Define a connection. For instructions to create an application server connection,
see the "To create an application server connection" section of the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
2. 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. Check the deployed SOA Project.
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:
■ Section 54.1, "Creating a Content Repository Connection"
■ Section 54.2, "Creating an Oracle Data Integrator Repository Connection"
■ Section 54.3, "Creating Oracle Business Activity Monitoring Server Repository
Connection"
Content Server credential store, and then you use the Create Content Repository
Connection wizard to set up a content server-based content repository connection.
For information about using the WLST command-line scripting interface, see Oracle
Fusion Middleware Oracle WebLogic Scripting Tool.
Note: If the keys do not exist, use the following commands instead:
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()
8. Click Test Connection and verify that the status returned is Success!
Note: If the test is unsuccessful, verify that the values that you
entered are correct and try again.
9. Click OK.
10. From the Application Resources panel, expand the Connections node to see the
new content repository connection, as shown in Figure 54–2.
Configuration Parameters: Enter values for the parameters shown in Table 54–2.
With the exception of the RIDC Socket Type parameter, all values shown are
examples only. If a parameter is not listed in the table, leave the value blank.
Contact your system administrator to obtain the correct information.
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. Enter the following information, as shown in Figure 54–4.
Login URL: Paste the URL for the login page. (Contact your system
administrator for this information). For example:
http://abc.example.com:2244/abc/abcplg?AbcService=LOGIN&Action=GetT
emplatePage&Page=HOME_PAGE&Auth=Internet
User Name/ID Field Name: Enter the field name for the user name or ID, such
as username.
Password Field Name: Enter the field name for the password, such as
password.
Tip: The User Name and Password field names are derived from the
HTML input field names.
Note: If the test is unsuccessful, verify that the values that you
entered are correct and try again.
4. Click OK.
5. From the Application Resources panel, expand the Connections node to see the
new content repository connection, as shown in Figure 54–5.
2. Select the General > Connections category, then select BAM Connection. Click
OK to open the Oracle BAM Connection wizard, as shown in Figure 54–6.
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:
■ Section 55.1, "Introduction to Profiles"
■ Section 55.2, "Integrating Profiles Task Flows into Oracle Fusion Functional Setup
Manager"
■ Section 55.3, "Setting and Accessing Profile Values"
■ Section 55.4, "Managing Profile Definitions"
■ Section 55.5, "Managing Profile Categories"
■ Do not use profiles to cache temporary session attributes. Profiles are permanent
user preferences and system configuration options.
55.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 50,
"Implementing Function Security."
For more information about task flows, see theOracle Fusion Applications Common
Implementation Guide.
Table 55–1 lists the task flows related to profiles and their parameters.
55.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 55–1.
Notes:
■ Any change you make to a profile option has an immediate effect
on the way your applications run for that session. And, when you
log on again, changes you made to your User-level options in a
previous session are still in force.
■ When a profile value is changed, the user setting the value will
always see the update immediately. Other users may not see the
changed value until logging out and back in.
Note: You can also select Reset to clear your entries and start again,
or Save to save the entries for a future search.
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 the Applications Core
Library to Your Data Model Project."
...
fndDiagnostics = Profile.get("AFLOG_ENABLED");
Once the bean is defined, you can refer to any profile value as:
# {Profile.values.PROFILE_OPTION_NAME}
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:
■ System administrators should set site-level profile values before
specifying values at any other level.
■ The profile values specified at the site-level work as defaults until
profile values are specified at the other levels. Profiles are
enterprise-striped. In a multi-tenant environment, VPD policies
restrict the profile values to only those defined in the relevant
enterprise. As a result, in a multi-tenant environment, a site-level
profile value behaves like an enterprise-level profile value.
2. In the Search Results: Profile Options section, highlight a profile option and do
any of the following:
■ Use the Actions or View options
■ Create a new profile option
■ Edit an existing profile option. The Edit window is shown in Figure 55–4.
2. In the Search Results: Profile Categories section, highlight the required profile
category and do any of the following:
■ Use the Actions or View options
■ Create a new profile category
■ Edit an existing profile category. The Edit window is shown in Figure 55–6.
This chapter discusses the Seed Data Loader and using it from within Oracle
JDeveloper.
This chapter includes the following sections:
■ Section 56.1, "Introduction to the Seed Data Loader"
■ Section 56.2, "Using the Seed Data Loader in JDeveloper"
■ Section 56.3, "Translating Seed Data"
Note: Each entity type, such as Profile and Messages, will have its
own dedicated utility. See Table 56–1, " Available Seed Data Loaders".
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-1
Using the Seed Data Loader in JDeveloper
Legend
■ Loader: Location of a seed loader-enabled application module. Assume a prefix of
oracle.apps.fnd.applcore.
■ VO: Driving view object.
■ Is the Module Striped?: Does this view object require a module argument?
docseq.docSeqService.applicationModule.DocSeqServiceAM DocSequenceAudit N
docseq.docSeqService.applicationModule.DocSeqServiceAM DocSequenceUsers N
flex.dff.category.categoryService.applicationModule.Ca Category N
tegoryServiceAM
flex.dff.descriptiveFlexfieldService.applicationModule DescriptiveFlexfield Y
.DescriptiveFlexfieldServiceAM
flex.dff.descriptiveFlexfieldService.applicationModule DescriptiveFlexfieldSecondaryUsage Y
.DescriptiveFlexfieldServiceAM
flex.kff.keyFlexfieldService.applicationModule.KeyFlex KeyFlexfield Y
fieldServiceAM
flex.kff.keyFlexfieldService.applicationModule.KeyFlex KeyFlexfieldSecondaryTableUsage Y
fieldServiceAM
flex.vst.valueSetService.applicationModule.ValueSetSer ValueSet Y
viceAM
lookups.lookupService.applicationModule.LookupServiceA LookupView1 Y
M
lookups.lookupService.applicationModule.LookupServiceA StandardLookupType1 Y
M
lookups.lookupService.applicationModule.LookupServiceA CommonLookupType1 Y
M
lookups.lookupService.applicationModule.LookupServiceA SetIdLookupType1 Y
M
messages.messageService.applicationModule.MessageServi Message Y
ceAM
nls.currencyService.applicationModule.CurrencyServiceA Currency N
M
nls.isoLanguageService.applicationModule.IsoLanguageSe IsoLanguage N
rviceAM
nls.languageService.applicationModule.LanguageServiceA Language N
M
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-3
Using the Seed Data Loader in JDeveloper
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-5
Using the Seed Data Loader in JDeveloper
The Seed Data Configuration wizard launches and displays the Driver Definition
Panel.
This panel, shown in Figure 56–2, initially shows the available view objects in the
root level of the application module data model that can serve as Driver view
objects.
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
during this session. Only one driver view object can be configured during a
single editing session.
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/updates exist (such as through PL/SQL code), the seed data
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-7
Using the Seed Data Loader in JDeveloper
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 is required to 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 could also 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: 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 define 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 56–4, to declare surrogate attributes of
the view objects of the Seed Data Configuration.
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.
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 PK
has many attributes and one of them is being marked as a surrogate, all the other
attributes in the PK, 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 PK 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. Select the Surrogate Attribute and click the shuttle button.
Click Reference Panel.
Use the Reference Panel, shown in Figure 56–5, to declare the Data Upload Mode
for the Seed Data Configuration. Provide reference information on reference view
objects.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-9
Using the Seed Data Loader in JDeveloper
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. Add a reference in the current application module to this application module
by clicking the shuttle button.
Note: If there are any Service Foreign Key LOVs defined in your
model, review the different scenarios in Table 56–2, " Service Foreign
Key LOV Scenarios" and verify that the steps listed for the scenario
corresponding to your FK LOV are followed. Failure to follow the
instructions in the document can cause problems during Seed Data
Extract and Upload processes.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-11
Using the Seed Data Loader in JDeveloper
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-13
Using the Seed Data Loader in JDeveloper
Note: If you change the name of a seed data file after Extract, you
also must manually update any references to that file name also.
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.
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:
■ From JDeveloper using the Seed Data Framework Console
■ By using an external Command Line Interface, as shown in Section 56.2.4.2, "Using
the Extract Seed Data Command Line Interface"
If there are multiple database connections in the workspace, the Seed Data Console –
Select Database dialog, shown in Figure 56–7, displays.
Although this is not the normal case, if a developer needs to debug data on two
different databases, this lets him or her choose which one to use.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-15
Using the Seed Data Loader in JDeveloper
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 56–8, displays.
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.
Note: The Seed Data Console does not specify the last applied
version of the seed data file. As a result, users always will see a
warning message indicating incremental uploads have been turned
off. This is harmless and can be ignored.
In the log, the warning will appear similar to:
[WARNING] 14:38:58 : -cfver parameter not passed,
incremental uploads turned off
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.
Functional Design
When starting the Extract process, if a Taxonomy Partition Attribute is found in the
Driver view object, Extract will show the Taxonomy Partition selection dialogs. See
"Determining the Taxonomy Partitioning Attribute" for steps taken by Extract to find
the Taxonomy partition attribute, if any.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-17
Using the Seed Data Loader in JDeveloper
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.
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.
Figure 56–12 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.
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 56–13 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.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-19
Using the Seed Data Loader in JDeveloper
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 56–5.
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.
Table 56–3 Application Module Custom Property for a View Object Instance
Application Module Custom
Property Name Value Example
SD_DEPENDENT_FILES_<View <product>:<path>:<filename>, Property: SD_DEPENDENT_FILES_
object instance name> <product>:<path>:<filename>,.. TimeDefinition1
The static dependent file location Value:
consists of three parts separated by HCM:HCM/Per:LookupsSD.xml,FND:F
colons: ND:ValueSetSD.xml
■ product: Product short name.
■ path: Relative path from the
product folder where the file exists.
■ filename: name of the seed xml file
that contains the referenced data.
Multiple static external references
should be separated by a comma.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-21
Using the Seed Data Loader in JDeveloper
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.
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.
This will ignore the FCM value entry, but keep others intact. A sample
PartitionKeyNames command line option is shown in Example 56–2.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-23
Using the Seed Data Loader in JDeveloper
scriptiveFlexfieldServiceAM
-VO DescriptiveFlexfield
-ExtractRootPath /home/seed/data
-PartitionKeyNames HCM, invoices, cashManagement
-loglevel FINER
Example 56–3 shows the contents of the sample Seed Extract Command Property File,
located at /home/extract.properties:
In addition to the Load Seed Data option, discussed in Section 56.2.5.1, "Uploading
Seed Data," three other options are available:
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.
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: When you upload files, if the row already exists in the
database and if it has been customized (last_updated_by <> 0), a
"Skipped" message will be placed in the log and the row will not be
updated. To correct this, change last_updated_by to 0 in both the
database and the file before uploading.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-25
Using the Seed Data Loader in JDeveloper
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 56–16.
You may see warning messages about columns being not updateable. Review these
messages to determine if you can ignore them for your specific case.
56.2.5.1.1 How to Upload Seed Data Using the Command Line Interface
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 56–6, is set to a valid
JDeveloper installation directory. Include the jdeveloper sub folder if you are using
JDeveloper integrated with WebLogic Server.
Table 56–6 Environment Variables for the Seed Data Upload CLI
Variable name Required? Purpose
JDEV_HOME No Should point to the full path to the JDeveloper installation.
APPLSEED_ No Used to add additional classpath entries to the loader (in
CLASSPATH addition to the regular CLASSPATH setting which might
not be modifiable in certain circumstances). This
parameter is expected to include folders where Apps EAR
archives are available in an exploded format (typically the
product family level deploy folders). If the same ADF
library is available from multiple locations, only one will
be added to the classpath.
APPLSEED_TS_ No Used to add additional classpath entries to the loader (in
CLASSPATH addition to the regular CLASSPATH setting which might
not be modifiable in certain circumstances). This
parameter is expected to include folders where techstack
libraries are made available. On a provisioned system, it
should include at least these directories:
fmw1/atgpf/atgpf/modules/oracle.applcore.model_
11.1.1
fmw1/oracle_common/modules
fmw1/atgpf/modules
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-27
Using the Seed Data Loader in JDeveloper
Example 56–5 Sample Command Line Invocation for a KFF Application Module
java -cp $jdev_
install/jdeveloper/jdev/oaext/lib/oracle.apps.fnd.applseed-rt.jar:$jdev_
install/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar
oracle.apps.fnd.applseed.rt.loader.Loader
56.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
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.
■ What is deleted when -clean is used?
– 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.
■ Customizations and -clean
The -clean mode currently does not preserve customizations. The seed framework
identifies customized records by a non-zero last_updated_by. Such records are not
updated by the seed framework and a warning is issued that the record has been
customized in the database. The clean mode, however, does not currently honor
this principle and deletes even the customized records.
■ When are deletes committed?
The cleanup and the subsequent loading run in a single transaction. Therefore, a
failure during the loading will roll back the deletes. Because the seed framework -
by default - commits after every top level record, the cleanup - by default - is
committed or rolled back along with the very first top level record. If subsequent
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-29
Using the Seed Data Loader in JDeveloper
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.
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.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-31
Using the Seed Data Loader in JDeveloper
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.
Users can choose an available application module and click OK to display the familiar
Seed Data console to perform and extract or upload activities.
only those records from the seed data file that have changed since the file was last
loaded on a given database. The Seed Data Framework provides an optional feature
that allows product teams to incrementally update their seed data.
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 only to US language seed data XML files
and is not enabled by default. For translated seed data, there is no provision to do
incremental updates.
To enable 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 true to turn on incremental updates.
SD_INCR_MIDTIER_ValueSetVO true
Note that the incremental updates feature requires new metadata, in the form of
checksums, to be embedded into the seed data file. As a result, 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.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-33
Translating Seed Data
56.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 single unit.
There is metadata in the files to ensure that the base and XLIFF files match and were
extracted together.
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.
Initializing Oracle Fusion Application Data Using the Seed Data Loader 56-35
Translating Seed Data
Framework
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.
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.
4. In the Create Offline Database dialog, enter a name for the offline database, as
shown in Figure 57–2. 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
■ Materialized View Log
■ 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
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.
■ Active Constraint or Index's Columns Checking
Check the status of a column to which an active constraint or index refers. If its
value is obsolete, an error message be displayed and block the work flow.
■ Index for Unique Constraint
Check if an index of unique constraint exists. If not, add one automatically.
■ Constraint Deployment Violation Checking
If a constraint is defined as disabled, but its UDP isLogical is set to N, a warning
message will be displayed, because this case will cause a deployment error.
■ 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.
Table 57–8 (Cont.) User Defined Properties for Materialized View Log
UDP Display Name Values in JDeveloper
objectOwner MV Log Owner N/A
Materialized view log
owner.
adxml ADXML
The value of this UDP is
patch metadata used by
the patching tool.
useExistingAdxml Y Y: Generate ADXML comment using
existing ADXML value from ADXML UDP.
This UDP is mandatory. N (default)
N (default): Regenerate ADXML comment
and update ADXML UDP.
■ Right-click the offline database object that you wish to edit and choose Properties.
Or double-click the offline database object.
The Edit offline database object dialog opens. For more information at any time,
press F1 or click Help from within the Edit dialog.
■ 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 57–4.
2. Select the Project and Offline database to which the objects from the target
database need to be imported, as shown in Figure 57–5.
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 57–6, you can:
■ Enter characters in the Name Filter to filter the list of available objects by
name. The Name Filter is case sensitive.
■ When there are a large number of objects, you can turn off Auto-Query and
click Query once you have entered the filter you want to use.
■ Select the object types you want to view.
57.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 57–7.
■ Deploying multiple database object files (Bulk Deployment). Several items are
selected, as shown in Figure 57–8.
■ Deploying offline schema object (and thereby deploying the entire designed data
model), as shown in Figure 57–9.
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 57–10.
■ Deployment Parameters. Figure 57–11 shows how the dialog appears for single
database deployment parameters.
Figure 57–12 shows how the Deployment Parameters dialog appears for multiple
database deployment parameters.
– 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.
– Db Object Mode: A single database object can be deployed independently in
table and in tablefk mode.
In case of bulk and schema deployment, the database objects first will be
deployed in table mode and then tablefk mode, by default.
This is standard for bulk and schema deployment; therefore, the Db Object
Mode is not displayed on the wizard.
– 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
deployment will report on the differences but will not actually apply the
changes to the database.
– Force Mode: If this option is selected, any additional column, index or
constraints that are present in a target database, but not in the current object
file, will be dropped.
57.2.9.1.2 How to Use the Database Object Deployment Command Line Interface Use this
command and parameters shown in Example 57–1 to deploy a database object from
the command line.
Mandatory Arguments
■ owner_un: Oracle schema name in which the object exists or should be created.
■ apps_un: Oracle schema name of the current APPS schema.
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.
■ jdbc_protocol: The JDBC protocol (thin or oci8).
■ jdbc_db_addr: JDBC tns information, either formatted as a Net8 connect string
enclosed in double quotes, or as hostname:port:oracle_sid.
■ xdf_mode: The object type information - table, qtable, mview, mviewlog,
sequence, type, trigger, view, policy, bootstrap.
■ xdf_file_name: The XDF file name, which contains the object definition. It is not
mandatory if the xdf_mode is bootstrap.
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
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:
– index_category=small and unused dbms block size greater than parallel_
index_threshold
– index_category=large and unused dbms block size less than parallel_index_
threshold
■ parallel_index_threshold: Parallel index threshold, default is 0.
■ no_error: This option is used when you add a not-null column to an existing table
with data, or change a null column to a not-null column. XdfSchemaDeploy
results in FAILURE without this option. XdfSchemaDeploy results in WARNING
if you have no_error=y. Default value is "n."
■ idxnolog: Pass idxnolog=y to add a NOLOGGING clause in the Index creation to
improve the performance of creation. The default value is "n."
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.
To add a not-null column to an existing table with data, or change a null column
to a not-null column:
There are two options to add a not-null column to an existing table with data, or
change a null column to a not-null column.
■ Option 1
■ Adding a not null column to an existing table with data
Product teams can specify an RDBMS default value for the column which will
be used by the databases to successfully alter the table to add the not-null
column.
■ Modifying a null column to not-null in a table with data
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.
57.2.9.5.1 Making a Database Object Obsolete Use this information to correctly make a
database object obsolete. It is applicable after the release of the initial version of the
product to customers.
Modeling database schema for new releases or upgrades to new releases may involve
making certain database objects or certain attributes of the database object, such as
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. Status User Defined Property will be captured in the Applications/XDF data
dictionary as part of deploying XDF to the database.
These steps ensure that:
■ 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.
57.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 needs to be
used to synchronize the XDF dictionary.
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. 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.
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. The tbname parameter is optional. If it 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. The delname parameter is optional. 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 all table, view, or sequence information 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.
execute fnd_cleanup_pkg.fndcleanup
■ 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
■ 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)
■ Drop View view1 from the database if it is marked as obsolete.
execute fnd_drop_obsolete_objects.drop_object(view1)
■ 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_%')
57.2.9.5.4 Frequently Asked Questions Use this information when dropping an object in
the database.
■ How do I make an object obsolete?
1. Select the object in JDeveloper.
2. Right-click and select Properties > User Properties.
3. Change the Status to Obsolete.
■ 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 JDeveloper to remove the definition of these secondary objects from
the offline database file definition.
– Use the force_mode optional parameter to deploy the object to the target
database.
■ If the object is a primary object, such as a table, sequence or view:
– Drop the object obj from sqlplus.
– Execute this command from sqlplus:
execute fnd_cleanup_pkg.fndcleanup(' obj')
■ 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.
– Execute this command from sqlplus:
execute fnd_drop_obsolete_objects.drop_object(' obj')
– Execute this command from sqlplus:
execute fnd_cleanup_pkg.fndcleanup(' obj')
■ 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.
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
■ How do I remove obsolete columns/indexes in objects from FND data?
Execute this command from sqlplus.
execute fnd_cleanup_pkg.fndcleanup
■ How do I remove all table/view/sequence name LIKE HZ% in fnd_tables/fnd_
views/fnd_sequences tables that do not exist in the database?
Execute this command from sqlplus.
execute fnd_cleanup_pkg.fndcleanup('HZ%')
■ How do I drop table/view/sequence name xyz in fnd_tables/fnd_views/fnd_
sequences tables from the database if it is marked as obsolete?
Execute this command from sqlplus.
execute fnd_drop_obsolete_objects.drop_object('xyz')
■ How do I drop table/view/sequence name LIKE HZ% in fnd_tables/fnd_
views/fnd_sequences tables from the database if it is marked as obsolete?
Execute this command from sqlplus.
execute fnd_drop_obsolete_objects.drop_object('HZ%')
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 58.1, "Introduction to Improving the Performance of Applications"
■ Section 58.2, "ADF Business Components Guidelines"
■ Section 58.3, "ADF ViewController Layer Guidelines"
■ Section 58.4, "SOA Guidelines for Human Workflow and Approval Management
Extensions"
■ Section 58.5, "Oracle Fusion Middleware Extensions for Applications Guidelines"
■ Section 58.6, "General Java Guidelines"
■ Section 58.7, "Caching Data"
■ Section 58.8, "Profiling and Tracing Oracle Fusion Applications"
■ Section 58.9, "Set up a Debug Breakpoint"
58.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.
Figure 58–2 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. Figure 58–3 illustrates an
example profiler output showing addRowSet being expensive.
Before you decide to retain association accessor, you should try the guideline
Section 58.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.
For user interface (UI) driven queries, the FIRST_ROWS(10) hint should be used to
instruct the optimizer to pick a plan that is optimized to return the first set of rows.
You should set this hint for view objects that are used for UI components, which
typically just displays 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.
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 should be 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.
58.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, in order 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))
For those attributes that do not need to be part of the key, deselect the Key Attribute
option in the View Object Attribute Editor.
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: These events are not related to the business events that you
may have defined in the entity object.
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 Example 58–1.
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).
supposed to be the driving filter. You should make sure there are appropriate function
indexes to support case-insensitive searches.
58.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.
58.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.
view criteria, the indexes cannot be used efficiently, resulting in poor query
performance. Use an "Equals" or "Starts With" operator instead.
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.
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.
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.
other hand, Application Session exists at the ADF Model layer and is per application
module instance, so state cached in it can not be across HTTP requests once the
application module instance switching happens.
It is strongly suggested to avoid saving a lot of custom session states in HTTPSession
because it increases memory usage and impacts scalability. This is the exact problem
that application module state management and application module pooling is
expected to solve.
To handle custom session states, you need to override passivateState() and
activateState() functions in your ApplicationModuleImpl class or relevant VOImpl
class.
For more information about how to manage custom user information, see the
"Application State Management" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
The following is sample code from the Pathfinder Application to passivate and
activate the UserLoginPrincipal object. Example 58–2 shows one way that you can
passivate custom state.
try{
ObjectOutputStream oos = new ObjectOutputStream(baos);
oos.writeObject(principal);
oos.flush();
}
catch(IOException e)
{}
if (nl != null) {
for (int i=0, length = nl.getLength(); i < length; i++)
{
Node child = nl.item(i).getFirstChild();
if (child != null) {
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.
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.
58.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.
Example 58–3 is sample code showing how to create a find criteria.
fc.setFilter(vc);
58.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: If you use nested application modules, you can not pull data
from different databases.
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.
Caution: When you disable the estimated row count, the scrolling
behavior of your table is different. The user can scroll forward only
one range at a time.
If IDs are specified for other naming containers (such as tables), a length of 3 or fewer
is best. Using short naming for container IDs helps to reduce the size of each response,
as well as network traffic, because the IDs of the parent naming containers are
appended to a child's generated ID.
Example 58–6 shows how to use this technique with lazy popups.
regionNavigationListener="#{testBean.navigationListener}"/>
</c:if>
</af:panelWindow>
serverListener -->
<af:clientListener method="popupClosedListener" type="popupClosed"/>
</af:popup>
58.3.1.18 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.
58.3.1.20 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. Set the following properties to "deferred":
■ The childCreation property on the popup.
■ The activation property on the task flow binding. (This is under the
Executables section in the page definition file.)
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 as long as 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.
58.3.1.22 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"/>
58.3.1.23 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
example, do not access an application module instance by calling the
Configuration.createRootApplicationModule() API from a backing bean. This results
in creating additional application module instances which are distinct from the
application module instance that is automatically checked out and in by the Oracle
ADF data binding layer, used by UI pages and task flow method call activities. This
can lead to performance and memory issues if your backing bean calls
Configuration.createRootApplicationModule() API without calling
releaseRootApplicationModule().
You should use an ADFM action binding to invoke a client interface method
declaratively on an application module instead. This approach requires no code and
often prevents the need for a backing bean. It also ensures that any exceptions are
handled in a consistent way as if Oracle ADF had invoked the method declaratively.
You should also ensure that your backing bean is invoked in a context where a
pageDef has been defined.
The following code excerpt is an example that follows our recommendation:
private ComponentReference<RichTable> allocationTableRef;
public void setAllocationTable(RichTable allocationTable) {
if( this.allocationTableRef == null)
this.allocationTableRef =
ComponentReference.newUIComponentReference(allocationTable);}
public RichTable getAllocationTable() {
return allocationTableRef==null ? null : allocationTableRef.getComponent();
view-scope or page flow-scope beans, be careful about when to invalidate the cached
results.
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.
try {
profileService = ProfileServiceAMImpl.getInstance();
String value = profileService.getProfileValue("<ProfileOptionName>");
}
finally {
Configuration.releaseRootApplicationModule(profileService, false);
}
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}"
58.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 no removed for the duration of the session, regardless of any
navigation or closing tab. This is due to the fact that Main TF and Regional TF in the
UI shell has 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.
58.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:
■ A new StringBuilder is created.
■ The two arguments are added to it with append().
■ The final result is converted back with a toString().
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.
For the sake of simplicity, it is acceptable to do String concatenation using "+" for
debug log messages, as long as 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:
The hashCode method is another common place where you do String concatenation.
Example 58–8 uses the hashCode implementation and requires String concatenation on
every call.
Note: This example was taken from the book Effective Java.
Plan carefully before deciding to concatenate Strings. There are often alternative ways
to implement the intended logic without concatenation.
replacement until you have found a fragment that needs to be replaced. For more
information, see the "Application Module Design Considerations" section in the Oracle
Fusion Middleware Performance and Tuning Guide.
Example 58–10 shows how the compiled code basically creates a new Integer object
based on the int value:
If this piece of code is called repeatedly, then each call creates one Integer object and
could have adverse performance impact.
58.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();
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();
stmt.setString(1,fileInfo.getNodeName());
stmt.setString(2,fileInfo.getPath());
ResultSet rs = stmt.executeQuery();
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;
}
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 Example 58–13.
...
}
catch
{
...
<process any exceptions>
...
}
finally
{
...
try
{
<close the statement>
}
catch
{
<process any exceptions>
}
...
}
expensive to retrieve from the database or data source, and expensive to create. Data
suitable for caching should have some or all of the following characteristics:
■ 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.
58.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.
58.7.3.1.1 How to create objects if only the data from the base table needs to 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.
58.7.3.1.2 How to create objects if only the data from the _TL table needs to be shared
1. Create the entity object on top of the _TL table.
This is required by MLS Framework. For more information, see Section 9.2, "Using
Multi-Language Support Features."
2. Create a view object on top of the _TL entity object.
3. 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.
58.7.3.1.3 How to create objects if both the data from the base table and the _TL table needs to
be shared
1. Create the entity object on top of the _TL table.
This is required by MLS Framework. For more information, see Section 9.2, "Using
Multi-Language Support Features."
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.
58.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.
58.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.
58.7.3.2.2 How to create objects if only data from the _TL table is required
1. Create a view object that joins to the _TL entity object.
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.
58.7.3.2.3 How to create objects if data from both the base table and the _TL 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 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.
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 in order 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.
58.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.
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.
To reduce resource consumption, you should set appropriate filters to
include only the classes you are interested in.
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.
2. Select the Save Logs to File option and specify the Log directory, as shown in
Figure 58–12.
After running your project, you can find the console logged to a file in the
specified directory.
Suite
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.
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.
59.2.2.3.1 Enabling Database Tracing Enable database tracing before you start your test
flow.
2. From the Help menu in the work area of the Oracle Fusion application, choose
Troubleshooting and select Troubleshooting Options.
3. In the Options dialog, select the Database trace checkbox.
This option enables SQL trace for all database connections used by the current
user session.
You can also select options to enable the SQL trace option to capture bind variables
and wait events.
59.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.
Note: 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.
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.
2. Log in as an administrator.
3. Click the ampool metric.
4. Scroll your browser to the right to view all the statistics.
59.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 UI libraries are in the WEB-INF/lib directory of the WAR file.
■ 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
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.
59.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 59.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.
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: Only one developer can debug at a given time on a specific port.
Problem
The open file limit on local Linux servers has been exceeded.
Solution
Increase the open file limit.
For information, see Section 2.2.1.2, "Increasing Open File Limit on Local Linux
Servers".
Problem
A reference to an Oracle ADF business component or Java class in an Oracle ADF
library cannot be resolved, such that it does not exist or is incompatible with the
existing reference.
Solution
All references to components contained in Oracle ADF libraries are resolved when the
workspace is loaded in JDeveloper. 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.
59.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.
Problem
If you consume the components from another project in the same workspace and run
in debug mode, you can open the source Java classes from the referenced project in the
JDeveloper edit window and set breakpoints. However, if you consume the
components at runtime through an Oracle ADF library, the compiled objects from the
Oracle ADF library may not be synchronized with the source if you made changes
since you last deployed the Oracle ADF library. If you are using a build output
dependency, then you are not affected by this issue.
Solution
Redeploy the Oracle ADF library to synchronize the source code.
Problem
The Data Controls panel in JDeveloper was not opened in a new view or refreshed
following changes made to the data bound Applications Core component.
Solution
If using the Applications Core wizards to create an applications panel, applications
table, or other data bound Applications Core component, you must open the Data
Controls panel in JDeveloper at least once in a new view, or at least once after deleting
the system directory, before launching the Applications Core wizards. If necessary you
should refresh from the Data Controls panel before launching the Applications Core
component wizards.
Problem
You have more than one UI project (for example, task flows referenced from an Oracle
ADF library) when the DataBindings.cpx files are merged at runtime.
Solution
Make sure that each instance of DataBindings.cpx resides in its own package.
Problem
The DataBindings.cpx file was moved because the default package was set incorrectly.
Solution
Make sure that the package defined in the Application tag of DataBindings.cpx
matches the current package location.
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.
Problem
There is a second version of the ADF component erroneously included when the
Oracle ADF libraries and WAR or EAR files were built.
Solution
Check the EAR file to make sure that the missing component is actually present in the
expected location.
Problem
A second copy of that component is incorrectly referenced in another Oracle ADF
library via a build output reference.
Solution
Perform one of the following tasks to resolve the problem:
■ 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.
■ Force recompilation by right-clicking the JSP and selecting Build, then Clean All,
then rebuild and redeploy.
Problem
The Oracle WebLogic Server Java process may be CPU intensive.
Solution
Use kill –3 pid to write a Java thread dump to the administration console for
Integrated WebLogic Server or to the server log file for standalone WebLogic Server.
kill –3 pid is the same as kill –QUIT pid, which sends SIGQUIT to the process.
The Java process implements a signal.
Problem
The Model project is missing the Applications Core library.
Solution
Add the Applications Core library to the Model project.
Problem
The Applications Core (ViewController) tag library is missing.
Solution
Add the Applications Core (ViewController) library to your project to automatically
add the Applications Core (ViewController) tag library. You may need to close the
Project Properties dialog, save the changes, and reopen the Project Properties dialog
before you see all the dependent changes made when adding the Applications Core
library.
Problem
The page or page fragment is invalid. In the source editor, you can see that there are
errors in the page, often because of malformed XML (for example, missing or
mismatched XML tags) or some other error reported by the design time audits. This
can occur if you cut and paste directly into the XML source. JDeveloper allows you to
run the page even though it is invalid.
Solution
In the Preferences option of the Tools menu, you can set an audit to run during
compilation. If there are failures, it will prevent the run. However, the audit only
executes during compilation. The first time you try to run, it may need to compile and
the audit kicks in and it fails, which causes the run to stop. The second time you try to
run, everything that needs to compile may have already successfully compiled. In this
case, there is no compilation, so there is no audit.
Problem
The settings for ApplicationDB are not configured correctly.
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>
59.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. Launch the Administration Server instance of Oracle WebLogic Server
(http://localhost:7101/console).
2. Log in using your username and password.
3. Go to Domain Structure, choose Service.
4. Go to Services and select JTA.
5. Increase the value of the Timeout Seconds property based on the expected
completion time of the longest transaction. The default value is 300.
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:
■ Section 60.1, "Introduction to View Objects for Oracle Business Intelligence
Applications"
■ Section 60.2, "General Design Guidelines"
■ Section 60.3, "Understanding Oracle Business Intelligence Design Patterns"
■ Section 60.4, "Designing and Securing Fact View Objects"
■ Section 60.5, "Designing and Securing Dimension View Objects"
■ Section 60.6, "Designing Date Dimensions"
■ Section 60.7, "Designing Lookups as Dimensions"
■ Section 60.8, "Designing and Securing Tree Data"
■ Section 60.9, "Supporting Flexfields for Oracle Business Intelligence"
■ Section 60.10, "Supporting SetID"
■ Section 60.11, "Supporting Multi-Currency"
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-1
General Design Guidelines
Oracle BI Enterprise Edition (Oracle BI EE) needs to efficiently access data from two or
more master/detail-linked view objects in order 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, in order 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.
SQL Bypass
■ Full SQL can be obtained at runtime using vo.getQuery().
■ There is no support for transient attributes.
■ View objects must not contain bind parameters.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-3
General Design Guidelines
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.
■ 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:
– The POLinesVO includes both the HeaderEO and the LinesEO.
– The LinesEO is specified as the primary entity on POLinesVO. The HeaderEO is
specified as a reference entity.
– This view object includes HeaderId attributes from both HeaderEO and
LinesEO.
– To avoid duplication of attributes across Header and Lines entities, an entity
object alias is specified. For example, Header and Lines for HeaderEO and
LinesEO respectively.
– 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.
■ Use the following guidelines to resolve view object foreign keys:
– If the foreign key is a dimension, Oracle Business Intelligence requests a
dimension view object and a view link to the dimension view object.
– If the foreign key is a warehouse domain, Oracle BI Applications requests a
view object for ETL. No view link is requested. Oracle BI EE lookup
functionality is used to resolve foreign keys.
– 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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-5
Understanding Oracle Business Intelligence Design Patterns
■ LEFTOUTER
■ RIGHTOUTER
■ FULLOUTER
■ INNER (default)
For more information, see "Working with Multiple Tables in a Master-Detail
Hierarchy" 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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-7
Understanding Oracle Business Intelligence Design Patterns
Entity objects can be included in flattened view objects as required, as long as the view
object grain does not change.
Note: View links are not required between these view objects.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-9
Designing and Securing Fact View Objects
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"
60.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:
■ Role Incentive Compensation Paysheet Management Duty can see Incentive
Compensation paysheets for the participants for whom they are responsible.
■ Role Incentive Compensation Process Management Duty can see Incentive
Compensation paysheets for the business units for which they are authorized.
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.
Note: This is a data role grant and the role and grant is generated
during the implementation phase using the data role template.
4. Use privilege View Incentive Compensation Paysheet Data in data security view
criteria in Incentive Compensation Paysheet. The view criteria should be like
Example 60–1 assuming IC_INCENTIVE_COMPENSATION_PAYSHEET is the object
registered in FND_OBJECT and ICPAY is the alias used for the entity object.
For Oracle BI Applications, the UNION effect for the above example, based on Oracle
Fusion Incentive Compensation Management reporting (Access by Participants and
access by business units), must be achieved in Oracle BI EE based on the OR join for
individual dimensions. This can potentially be achieved by using two separate groups
(one for business unit and another for participants) and having a user access to both
groups (since predicates are ORed across Oracle BI EE groups).
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-11
Designing and Securing Fact View Objects
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 end 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.
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.
As a result, 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:
■ There is a degenerate dimension, Dimension A on top of Fact A.
■ Dimension A is used in Fact B as a reference.
■ 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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-13
Designing and Securing Dimension View Objects
Note: The above example uses the Person model with a person
having address and phone. Keep in mind that Transactional Business
Intelligence models only the primary address and phone number
while Oracle BI Applications can model more than one address and
phone number per person.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-15
Designing Lookups as Dimensions
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.
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 60-17
Designing and Securing Tree Data
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 60–2, 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 60–3.
Note: In practice, you would never have single node trees. However,
root nodes 2.0 and 3.0 are in Figure 60–2 to simply illustrate multiple
top-nodes.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-19
Designing and Securing Tree Data
Think of the tree in Figure 60–2 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 60–5, assuming the same "pad toward leaf values"
scheme as with the value-based tree.
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).
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.
Note: 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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-21
Designing and Securing Tree Data
60.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 60–3 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 60-23
Designing and Securing Tree Data
Figure 60–4 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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-25
Designing and Securing Tree Data
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.
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
Table 60–6 Mapping Oracle Business Intelligence Hierarchy Levels to Application Tree
Levels
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 60-27
Designing and Securing Tree Data
■ 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.
Table 60–8 Column-Flattened Result Set with Data Security and DescendantOf Operator
C0 C1 C2 C3 C4 Distance
1.0 1.0 1.0 1.0 1.0 0
1.1 1.1 1.1 1.1 1.0 1
1.2 1.2 1.2 1.2 1.0 1
1.2.1 1.2.1 1.2.1 1.2 1.0 2
1.2.1.1 1.2.1.1 1.2.1 1.2 1.0 3
1.2.1.1.1 1.2.1.1 1.2.1 1.2 1.0 4
1.2.2 1.2.2 1.2.2 1.2 1.0 2
1.2.2.1 1.2.2.1 1.2.2 1.2 1.0 3
1.2.2.2 1.2.2.2 1.2.2 1.2 1.0 3
2.0 2.0 2.0 2.0 2.0 0
3.0 3.0 3.0 3.0 3.0 0
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-29
Supporting Flexfields for Oracle Business Intelligence
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.
60.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.
Designing and Securing View Objects for Oracle Business Intelligence Applications 60-31
Supporting Multi-Currency
This chapter describes how to combine third party desktop applications with Oracle
Fusion web applications.
The chapter includes these sections:
■ Section 61.1, "Oracle Application Development Framework Desktop Integration
Standards and Guidelines"
■ Section 61.2, "Skinning Excel ADF Desktop Integration Workbooks"
■ Section 61.3, "Configuring the WebLogic Server Frontend"
| | |-- 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 61–1 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:
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 61–2 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:
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
Note: 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.
■ 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. Select your user interface project in the application navigator pane.
3. Expand the connection you just created (FileSystem > <connection name>).
4. Right-click the library AdfFinFunPublicDeclarativeComponentsDi.jar and select
Add to Project.
5. To make sure the library was added, open Project Properties > Libraries and
Classpath > ADF Library. You should see an entry for
AdfFinFunPublicDeclarativeComponentsDi.jar.
Once 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.
Figure 61–1 Example of ADF Desktop Integration Look and Feel in Excel
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. To activate these changes, in the Change Center of the Administration Console,
click Activate Changes. Not all changes take effect immediately; some require a
restart.
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:
■ Section 62.1, "Introduction to Creating Customizable Applications"
■ Section 62.2, "Preparing an Application for Customizations"
■ Section 62.3, "Enabling Runtime Customization of Pages and Components"
Some customizations, such as changes to the model or to task flow roles, must be done
from Oracle JDeveloper, as described in the "Using JDeveloper for Customizations"
chapter in the Oracle Fusion Applications Extensibility Guide. Customizations made
from JDeveloper are referred to as design-time customizations. Design-time
customizations that are created and shipped with Oracle Fusion Applications are
known as seeded customizations.
Note: End users with the correct permissions can also customize
some menus, such as the Navigator menu. For more information, see
the "Customizing the Navigator Menu" chapter in the Oracle Fusion
Applications Extensibility Guide.
For more information about customization, and the "Customizing and Extending
Oracle Fusion Applications" chapter in the Oracle Fusion Applications Extensibility
Guide.
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.
62.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 a 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.
5. Click OK.
3. Add the filter and filter-mapping elements for the WebCenterComposerFilter class
as shown in bold in Example 62–1.
4. Enable sessions for the JSPX pages and task flows that you create in your view
project as described in Section 48.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.
5. Click Open.
6. Select the Overridden check box.
7. Click OK to save your changes.
8. Open the adf-config.xml file, which is located in the Application Resources >
Descriptors > ADF META_INF folder.
9. Add the resource-string-editor element shown in Example 62–2 to the
page-editor-config section to enable resource string editing.
Each of the customization classes supplied in the list must be valid and configured
in the adf-config.xml file, as shown in Figure 62–2.
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 62–3, 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.
5. Click OK.
6. Open the page definition file for the page fragment.
7. In the editor window, click the Source tab.
8. Add the <methodAction> element shown in Example 62–4 to the <bindings>
element. The id attribute must be set to custNavigate, which is the key to the
customizeUIShellTemplate operation that you dropped on the page in Step 3.
Is
Can the Does Does the page
component’s the user have the user have personalizable
attribute be administrative role administrative role in Page Composer?
persisted or privilege or privilege (default = false)
? ? ?
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.
3. If you are enabling the runtime addition of content, set up a resource catalog.
4. (Optional) Set up a default catalog definition file to facilitate testing.
62.3.4 How to Authorize the Runtime Customization of Pages and Task Flows
As illustrated in Figure 62–3 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.
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 62–4.
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.
Enterprise Scheduler
This chapter explains how to use extensions to Oracle Enterprise Scheduler to manage
job request submissions in the context of Oracle Fusion Applications.
■ Section 63.1, "Introduction to Oracle Enterprise Scheduler Extensions"
■ Section 63.2, "Standards and Guidelines"
■ Section 63.3, "Creating and Implementing a Scheduled Job in JDeveloper"
■ Section 63.4, "Creating a Job Definition"
■ Section 63.5, "Configuring a Spawned Job Environment"
■ Section 63.6, "Implementing a PL/SQL Scheduled Job"
■ Section 63.7, "Implementing a SQL*Plus Scheduled Job"
■ Section 63.8, "Implementing a SQL*Loader Scheduled Job"
■ Section 63.9, "Implementing a Perl Scheduled Job"
■ Section 63.10, "Implementing a C Scheduled Job"
■ Section 63.11, "Implementing a Host Script Scheduled Job"
■ Section 63.12, "Implementing a Java Scheduled Job"
■ Section 63.13, "Elevating Access Privileges for a Scheduled Job"
■ Section 63.14, "Creating an Oracle ADF User Interface for Submitting Job
Requests"
■ Section 63.15, "Submitting Job Requests Using the Request Submission API"
■ Section 63.16, "Defining Oracle Business Intelligence Publisher Post-Processing
Actions for a Scheduled Job"
■ Section 63.17, "Monitoring Scheduled Job Requests Using an Oracle ADF UI"
■ Section 63.18, "Using a Task Flow Template for Submitting Scheduled Requests
through an Oracle ADF UI"
■ Section 63.19, "Securing Oracle ADF UIs"
■ Section 63.20, "Integrating Scheduled Job Logging with Fusion Applications"
■ Section 63.21, "Logging Scheduled Jobs"
63.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 easily
integrated into an Oracle Fusion application. Once a job request is submitted through
the interface, Oracle Enterprise Scheduler Service runs the job as scheduled.
The extensions to Oracle Enterprise Scheduler Service provide the following execution
types:
■ 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 (BIP)
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 (Oracle Fusion Applications Edition), and the Oracle Fusion Middleware
Developer's Guide for Oracle Business Intelligence Publisher (Oracle Fusion Applications
Edition).
■ HostJobType: for job definitions that run as host scripts executed from the
command line.
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 63.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 A boolean parameter that enables or disables the accumulation of time statistics
(Y or N).
enableTrace A numerical value that indicates the level of tracing control for the job. Possible
values are as follows:
■ 1: Database trace
■ 5: Database trace with bind
■ 9: Database trace with wait
■ 13: Database trace with bind and wait
■ 16: PL/SQL profile
■ 17: Database trace and PL/SQL profile
■ 21: Database trace with bind and PL/SQL profile
■ 25: Database trace with wait and PL/SQL profile
■ 29: Database trace with bind, wait and PL/SQL profile
LOOP
del_pos := INSTR(incrProcArgs, ',', prev_pos);
EXIT WHEN del_pos = 0;
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;
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 63.14.2, "How to Add a Custom Task Flow to an Oracle ADF User
Interface for Submitting Job Requests."
reportID The BIP report value specified in the Oracle BI Publisher repository. Required
parameter for Oracle BI Publisher jobs only.
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 63.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 63.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:
■ Name: Enter a name for the job.
■ JobType: Select the job type from the drop-down list.
Click Finish. The new job definition displays.
6. 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
b. For the value of the property, enter a list of comma-separated file management
groups, where each file group is prefixed by an L or O to indicate a layout or
output file group, respectively. A sample file group property is shown in
Example 63–1.
Example 63–2 File Group Regular Expression Filtering for All Files with the Suffix XML
MYXML = '.*.\xml$'
Example 63–3 File Group Regular Expression Filtering for All Files
ALL = '.*$'
Example 63–4 File Group Regular Expression Filtering for All Files with the Suffix PDF
PDF = '.*.\pdf$'
Example 63–5 File Group Properties with File Group Regular Expression Filtering
Program.FMG = L.MYXML, O.ALL, O.PDF
MYXML = '.*.\xml$' ALL = '.*$' PDF = '.*.\pdf$'
6. In a text editor, create a file called tnsnames.ora that includes the lines shown in
Example 63–9.
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 63–11.
--
errbuf out NOCOPY varchar2,
retcode out NOCOPY varchar2,
-- 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 in varchar2 default 'BASIC',
duration in varchar2 default '0',
p_num in varchar2 default NULL,
p_date in varchar2 default NULL,
p_varchar in varchar2 default NULL) is
begin
-- Write log file content using FND_FILE API
FND_FILE.PUT_LINE(FND_FILE.LOG, "About to run the sample program");
The sample shown in Example 63–13 illustrates a PL/SQL job with a sub-request
submission. The no_requests argument identifies the number of sub-requests that
must be submitted.
-- Update the parent request with the state of the sub-request, 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 Service.
errbuf := fnd_message.get("FND", "COMPLETED NORMAL");
retcode := 0;
end if;
end;
/* ----------------------------------------------------------------------*/
DECLARE
errbuf varchar2(240) := NULL;
retval boolean;
run_mode varchar2(200) := '&1';
BEGIN
DBMS_OUTPUT.PUT_LINE(run_mode);
FND_FILE.PUT_LINE(FND_FILE.LOG, '
');
FND_FILE.PUT_LINE(FND_FILE.LOG, '-----------------------------------------
-----------------------');
FND_FILE.PUT_LINE(FND_FILE.LOG, 'Printing a message to the LOG FILE
');
FND_FILE.PUT_LINE(FND_FILE.LOG, '-----------------------------------------
-----------------------');
FND_FILE.PUT_LINE(FND_FILE.LOG, '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; Fusion Applications SQL*Plus Jobs must not exit.
The Fusion application calls Oracle Enterprise Scheduler using the provided APIs.
Oracle Enterprise Scheduler runs the job, and the final job status—SUCCESS, WARNING,
BUSINESS ERROR or FAILURE—is 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.
2. Enter the full path of the data file as the first submit argument to the job.
3. Store the control file under PRODUCT_TOP/$APPLBIN.
4. Configure the spawned job environment as described in Section 63.5, "Configuring
a Spawned Job Environment."
5. Test the file.
2. 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:
■ writeln(): Write a message to the log file.
■ timestamp(): Write a timestamped message.
3. To enable the Perl job to connect to a database, use /@$TWO_TASK as a connection
string without specifying a username or password.
4. Configure the spawned job environment as described in Section 63.5, "Configuring
a Spawned Job Environment". The context provides values for the following:
■ reqid: The request ID.
■ outfile: The full path to the output file.
■ logfile: The full path to the log file.
■ username: The name of the user submitting the job request.
use strict;
if ($ARGV[1] =~ /\D/) {
print "** Argument #1 is not a valid number, unable to sleep!\n\n";
} else {
printf("Sleeping for %d seconds...\n", $ARGV[1]);
sleep($ARGV[1]);
}
}
# -- Arguments
print_header("Arguments");
my $i = 1;
foreach (@ARGV) {
print "Argument #", $i++, ": $_\n";
}
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();
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";
sub print_header {
my $msg = shift;
print "\n\n", "-" x 40, "\n", $msg, "\n", "-" x 40, "\n";
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
■ FDP_ERROR: System Error
■ FDP_BIZERR: Business Error
boolean afpend (text *outcome, dvoid *handle, text *compmesg);
fdpfrs 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
afreqstate fdpfrs (text *request_id, text *errbuf);
fdpgrs Get request status. For a given request, retrieve the current status and
completion text.
afreqstate fdpgrs (text *request_id, text *status, text *errbuf);
fdplck 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);
fdpwrt 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.
Example 63–18 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 username> 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 63–19.
Example 63–19 Running a C Job from the Command Line for Testing Purposes
program username/password@my_db MYUSER L <parameter1> <parameter2> ....
#ifndef AFSTR
#include <afstr.h>
#endif
#ifndef AFCP
#include <afcp.h>
#endif
#ifndef SQLCA
#include <sqlca.h>
#endif
#ifndef AFUPI
#include <afupi.h>
#endif
#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 *use_curs;
word errcode;
use_curs = NULLCURSOR;
use_curs = afuopen (NULLHOST, NULLCURSOR, (dvoid *)
sqltext,
UPISTRING);
if (use_curs == NULLCURSOR) {goto upierror;}
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 os_user[31];
VARCHAR session_user[31];
VARCHAR db_name[31];
nullterm(os_user);
nullterm(session_user);
nullterm(db_name);
– 0 for SUCCESS
– 2 for WARNING
– 3 for BUSINESS ERROR
// Finish work.
// ... work ...
}
You can retrieve the executing user by running either of the methods shown in
Example 63–22 and Example 63–23.
Given a request ID, you can retrieve the submitting and executing users of a job
request.
Example 63–24 Retrieving the Submitting and Executing Users of a Job Request Using
the RuntimeService EJB
// Lookup runtimeService
To retrieve the submitting and executing users of a job request from within an
Oracle Fusion application:
■ Example 63–25 shows a code snippet for retrieving the submitting and executing
users of a job request from within an Oracle Fusion application.
Example 63–25 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()
63.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.
63.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.
63.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.
5. In the Project Properties dialog, in the left pane, click Business Components.
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:
■ Connection Exists in: Application Resources
■ Connection Type: Oracle (JDBC)
■ Username/Password: Fill in the relevant username and password for the
database.
■ Driver: thin
■ Host Name: Enter the host name of the database server.
■ JDBC port: Enter the port number of the database.
■ SID: The unique Oracle system ID for the database.
Click OK.
7. In the file weblogic.xml, import oracle.applcp.view.
8. In the file weblogic-application.xml, import the following libraries:
■ oracle.applcore.attachments (for ESS-UCM)
■ oracle.applcp.model
■ oracle.applcp.runtime
■ oracle.ess
■ oracle.sdp.client (for notification)
■ oracle.ucm.ridc.app-lib (for ESS-UCM)
■ oracle.webcenter.framework (for ESS-UCM)
■ oracle.xdo.runtime
■ oracle.xdo.service.client
■ oracle.xdo.webapp
The libraries oracle.applcp.model and oracle.applcp.view are deployed as part
of the installation while running the config.sh wizard.
9. Create a new 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
System, select New File System Connection, and do the following:
a. Provide a connection name and directory path for the Oracle ADF Library files
(<jdev_install>/jdev/oaext/adflib).
b. Click Test Connection and click OK once the connection is successful.
11. Expand the contents of the SRS-View.jar file to display the list of available task
flows that can be used in the application, as shown in Figure 63–4.
12. To include the job request submission page in the application, select the
ScheduleRequest-taskflow from the Resource Palette and drop it onto the JSF
page in the area where you want to create a call to the taskflow. Create the
taskflow call as a link or button.
For example, to invoke the job request submission page from within a dialog box
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 showpopup.
c. From the Component Palette, drag and drop a Popup component with a
dialog component onto the form.
d. To enable submitting a job request, drag and drop ScheduleRequest-taskflow
onto the dialog component as a dynamic region.
To enable submitting a job set request, drag and drop
ScheduleJobset-taskflow onto the dialog component.
Figure 63–5 displays the task flows in the Resource Palette.
Figure 63–5 Including the Job Request Submission Page in the Application
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 prior to 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 Service 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 63–27.
b. Specify control UI hints, for example set the display label for Attribute1 to
Run Mode and for Attribute2 to Duration.
As a result, the parameters tab in the job request submission UI renders with
the input fields Run Mode and Duration.
c. In order 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 63–7 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 Enterprise Scheduler Service metadata and job implementations.
18. In the Scheduler project, add the Enterprise Scheduler Extensions library to the
classpath. Right-click the Scheduler project and select Project Properties >
Libraries and Classpath > Add Library > Enterprise Scheduler Extensions.
19. Deploy the libraries oracle.xdo.runtime and oracle.xdo.webapp to the Oracle
Enterprise Scheduler UI managed server. These libraries are located in the
directory $MW_HOME/jdeveloper/xdo, where MW_HOME is the Oracle Fusion
Middleware home directory.
20. Deploy the application.
63.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 63.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:
■ "Getting Started with ADF Task Flows"
■ "Working with Task Flow Activities"
63.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.
Follow this procedure to enable context-sensitive parameter support in the UI.
■ 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.
63.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
Enterprise Scheduler Extensions library in conjunction with a JSF application that
includes a task flow in which a job is scheduled and saved.
2. Drag and drop SaveSchedule-taskflow 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 Enterprise Scheduler Service metadata and job implementations.
5. In the Scheduler project, add the Enterprise Scheduler Extensions library to the
classpath. Right-click the Scheduler project and select Project Properties >
Libraries and Classpath > Add Library > Enterprise Scheduler Extensions.
6. Deploy the application as described in the Oracle Fusion Middleware Developer's
Guide for Oracle Enterprise Scheduling Service.
7. Launch the application using the following URL:
http://<machine>:<http-port>/<context-root>/faces/<page>
8. Enter a schedule name, description and package name with the namespace
appended, as shown in Figure 63–8.
3. Click the Schedule tab. In the Run option field, select the Use a Schedule radio
button.
4. From the Frequency drop-down list, select Use a Saved Schedule.
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.
A notification includes two components: the user or group to whom the notification is
to be delivered, and the completion status of the job that triggers the notification. For
example, notifications can be sent upon the successful completion of a job, or when a
job completes in an error or warning state.
63.14.7 What Happens When You Create an Oracle ADF User Interface for Submitting
Job Requests
The Oracle ADF interface is integrated with the 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.
63.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 Service to run the job. The 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 Fusion application to Oracle Enterprise Scheduler.
Context-Sensitive Parameters
When launching the SRS UI to submit a job or job set request with context-sensitive
parameters, contextParametersVO 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 setConextAPI by passing the context parameters. The context is set at the
database level and the remaining parametersVO job parameters are rendered.
When the context-sensitive parameters are modified, end-users must click Next in
order 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 or groups using the User Messaging Service. Groups
receive notifications via e-mailed, whereas 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.
For more information about defining post-processing actions for scheduled jobs, see
"Creating a Business Domain Layer Using Entity Objects" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Example 63–31 Location of the File for Setting Up Oracle BI Publisher Reporting and
Seeding the Database
$BEAHOME/jdeveloper/jdev/oaext/adflib/PPActions.jar
Additional methods used by the ReportRequest object are shown in Table 63–6.
import oracle.apps.fnd.applcp.request.postprocess.PostProcess;
import oracle.apps.fnd.applcp.util.ESSContext;
import oracle.apps.fnd.applcp.util.PostProcessState;
import oracle.as.scheduler.*;
ArrayList myOutputFiles;
ArrayList getOutputFileList()
{
return myOutputFiles;
}
rService = ESSContext.getRuntimeService();
if (rService != null) rHandle = rService.open();
if (rHandle != null) rDetail = getRequestDetails(rHandle, requestID);
if (rDetail != null) rParam = rDetail.getParameters();
if (rParam != null) outDir = rParam.getValue("outputWorkDirectory");
if (outDir == null)
{
3. Create a native ADF Business Components view object to collect the parameters to
be used in the post-processing action. Follow the procedure described in
Section 63.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 Applications Core Session attributes that may be retrieved using
the ApplSession standard API.
63.16.3 What Happens When You Define Oracle BI Publisher Post-Processing Actions
for a Scheduled Job
Depending on the FMG property set for the job definition, the relevant post-processing
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 post-processing action.
For web service clients, you invoke the method using a proxy, as in Example 63–35.
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
Scheduling Service.
ppAction.setOnError(false);
ppAction.getArguments().add("argument1");
ppAction.getArguments().add("argument2");
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. In Common Properties, enter the following values:
■ id: MonitorNode
■ focusViewId: /Consumer
10. In Advanced Properties, enter Monitor Processes in the label field.
11. Right-click the itemNode you just added and select Go to Properties.
12. In the Property Inspector, select Advanced and do the following:
■ 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}
■ Task Type: defaultRegional
■ taskFlowId:
/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/Ta
sksList.xml#TasksList
14. Right-click adfc-config.xml and select Link ADF Menu to Navigator.
15. Configure Oracle JDeveloper Integrated Oracle WebLogic Server for development
with Oracle Enterprise Scheduler extensions.
16. Deploy and test the application.
■ Displaying multiple links in the task flow UI that each display a pop-up
window with a different job definition. The recommended approach is to create
a single page fragment that contains the scheduled request submission task flow
within an Oracle ADF region. This page is re-used by each link to display a
different job definition in the scheduled request submission UI. For each link, be
sure to pass the relevant parameters such as the job definition name, package
name, and so on. This approach ensures that the UI session creates and uses a
single instance of the task flow.
■ Displaying the correct name given the metadata name and display name
attributes. By default, the display name takes precedence and displays in the UI. If
the display name is not defined, then the UI displays the job or job set name.
■ Resolving name conflicts between a job metadata parameter name and a request
parameter with the same name. Oracle Enterprise Scheduler uses the following
rules to resolve parameter name conflicts.
– 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.
– 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 or not 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 63–8.
■ Fixing an Oracle BI Publisher report that does not generate, even though the
Oracle Enterprise Scheduler schema REQUEST_PROPERTY table contains all the
relevant post-processing parameters. Verify that the post-processing parameters
begin with index value of 1. If a set of parameters begins with an index value of 0
(such as 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 post-processing 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 is
invalid. This error may occur as a result of any of the following.
– The object oracle.as.scheduler.JobDefinition may be unavailable to the
scheduled request submission UI, which attempts to query the object using the
MetadataService API.
– 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 in order 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.
method call activity as the default activity of a custom bounded task flow so as to
initialize the parameters view object and flex filters defined in that task flow.
When using page navigation between two view activities and custom bounded task
flows with a default method call activity, switching between basic and advanced
modes might re-initialize the related view objects and entity objects. If this happens,
any data entered in basic mode is lost when changing to advanced mode.
The task flow template enables switching between basic and advanced modes in the
scheduled request submission Oracle ADF UI without losing data.
63.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 63–37 shows a sample implementation of the task flow template.
<router id="defaultRouter">
<case id="routerCaseID">
<expression id="routerExprID">#{pageFlowScope.shouldInitialize}</expression>
<outcome id="outcomeID">initializeTaskflow</outcome>
</case>
<default-outcome id="defOutcomeID">skip</default-outcome>
</router>
<control-flow-rule id="ctrlFlwRulID">
<from-activity-id id="FrmAc1">defaultRouter</from-activity-id>
<control-flow-case id="CtrlCase1">
<from-outcome id="FrmAct3">initializeTaskflow</from-outcome>
<to-activity-id id="ToAct1">initActivity</to-activity-id>
</control-flow-case>
<control-flow-case id="CtrlCase2">
<from-outcome id="FrmAct2">skip</from-outcome>
<to-activity-id id="ToAct2">defaultView</to-activity-id>
</control-flow-case>
</control-flow-rule>
<use-page-fragments/>
</task-flow-template>
</adfc-config>
63.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 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 63–38 to the task flow XML
file.
Note: Make sure that your bounded task flow does not define any
default activity.
2. Implement the activity IDs defined in the template, which are invoked by the
router activity in the template.
■ initActivity: The ID of the method call activity.
■ defaultView: The ID of the default view activity.
To do this, to the task flow drag and drop the createInsert method from the VO
used in the defaultView. This creates a pagedef file and adds the binding details in
DateBinding.cpx.
3. Define a control flow rule to navigate from initActivity to defaultView. This
navigation depends on the outcome of initActivity, as well as individual use
cases.
Example 63–39 shows a sample implementation of a control flow rule.
</control-flow-case>
</control-flow-rule>
63.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.
63.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 requires-transaction, 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 as long as the data controls
are shared.
Note: 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: Do not use the request log for debugging and internal error
reporting. For Oracle Enterprise Scheduler jobs, the request log is
equivalent to the end-user UI for online applications. When writing
Oracle Enterprise Scheduler job code, you should ideally log only
translatable end user-oriented messages to the request log. You should
not use the request log for debug messages or internal error messages
that are oriented to system administrators and/or Oracle Support.
Please keep in mind that the audience for debug messages and
detailed internal error messages is typically system administrators
and Oracle Support, not the end user.
Therefore, debug and detailed internal error messages should be
logged to FND_LOG only.
For Oracle Enterprise Scheduler jobs, the request log is equivalent to the end user
interface for web applications. When developing an Oracle Enterprise Scheduler job,
make sure to log to the request log only translatable end-user oriented messages.
For example, if an end user inputs a bad parameter to the Oracle Enterprise Scheduler
job, a translated error message logged to the request log is displayed to the end user.
The end user can then take the relevant corrective action.
Example 63–40 shows how to set log messages using the request log.
FND_MESSAGE.SET_MODULE('fnd.plsql.mypackage.myfuntionA');
fnd_file.put_line( FND_FILE.LOG, FND_MESSAGE.GET );
If the Oracle Enterprise Scheduler job fails due to an internal software error, log the
detailed failure message to 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: Do not use the output file for debugging and internal error
reporting.
/*
/*
** Writes a message to the log file if this level and module
** are enabled.
** The message gets set previously with FND_MESSAGE.SET_NAME,
** SET_TOKEN, etc.
** The message is popped off the message dictionary stack,
** if POP_MESSAGE is TRUE.
** Pass FALSE for POP_MESSAGE if the message will also be
** displayed to the user later.
** Example usage:
** FND_MESSAGE.SET_NAME(...); -- Set message
** FND_MESSAGE.SET_TOKEN(...); -- Set token in message
** FND_LOG.MESSAGE(..., FALSE); -- Log message
** FND_MESSAGE.RAISE_ERROR; -- Display message
*/
PROCEDURE MESSAGE(LOG_LEVEL IN NUMBER,
MODULE IN VARCHAR2,
POP_MESSAGE IN BOOLEAN DEFAULT NULL);
/*
** Tests whether logging is enabled for this level and module,
** to avoid the performance penalty of building long debug
** message strings unnecessarily.
*/
FUNCTION TEST(LOG_LEVEL IN NUMBER, MODULE IN VARCHAR2)
RETURN BOOLEAN;
Example 63–44 shows how to log a message in PL/SQL after the AOL session has been
initialized.
Example 63–44 Logging a Message in PL/SQL After the AOL Session Has Been
Initialized
begin
Note: For PL/SQL in a forms client, use the same APIs. Use FND_
LOG.TEST() to check whether logging is enabled.
Using Logging in C
Example 63–47 illustrates the use of logging in a C application.
/*
** 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 username in its state */
void afloginit();
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 64.1, "Introduction to Oracle Enterprise Scheduler Security"
■ Section 64.2, "Configuring Metadata Security for Oracle Enterprise Scheduler"
■ Section 64.3, "Configuring PL/SQL Job Security for Oracle Enterprise Scheduler"
■ Section 64.4, "Elevating Privileges for Oracle Enterprise Scheduler Jobs"
■ Section 64.5, "Configuring a Single Policy Stripe in Oracle Enterprise Scheduler"
■ Section 64.6, "Configuring Oracle Fusion Data Security for Job Requests"
Figure 64–1 Design Time Metadata Security for Oracle Enterprise Scheduler
64.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.
Ensure the security related files are included with EAR file:
1. In Oracle JDeveloper, select Application > Application Properties.
2. In the Application Properties page, in the Navigator select Deployment.
3. In the Deployment Profiles area, select the EAR file Deployment descriptor.
4. Click Edit.
The Edit EAR Deployment Profile Properties page displays.
5. In the Edit EAR Deployment Profile Properties page, expand File Groups >
Application Descriptors > Filters.
6. In the Filters area, select the Files tab.
7. Ensure that the files jazn-data.xml, jps-config.xml, and
weblogic-application.xml are selected under the META-INF folder.
8. Click OK to save the descriptor.
■ Enterprise roles: These are defined directly in Oracle WebLogic Server either using
the Oracle WebLogic Server console, using the WLST scripts, or using the ADF
Security Wizard in Oracle JDeveloper.
■ Application roles: These can be defined in the jazn-data.xml file or using the
ADF Security Wizard.
64.2.3 How to Create Grants with Oracle Enterprise Scheduler Metadata Pages
Access to all metadata is controlled by grants. In order 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 63.4, "Creating a Job Definition."
Using Oracle JDeveloper, you can add security grants to Oracle Enterprise Scheduler
metadata objects.
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 64–2.
6. Repeat for as many roles as needed.
11. With the new role selected in the Principals tab, make sure the Type is role.
13. For the Name field, enter a full permission string or a partial string with
wildcards; see Table 64–1 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
in the Actions Field.
15. Click OK to save the grant.
Table 64–1 Sample Permission Grants for Security Using Oracle ADF
Name Actions Effect
package-part.JobDefinition EXECUTE Grants the ability to submit requests
.MyJavaSucJobDef for a single metadata item.
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.
<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 64–2 shows a code
sample.
</web-app>
data exposed to Oracle Fusion Applications (see Section 64.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.
Table 64–3 Mapping Oracle Fusion Applications Schema Synonyms to Oracle Enterprise Scheduler
Schema Views and Relevant Columns
Link to Oracle Enterprise
Oracle Fusion Scheduler Schema View Columns
Applications Schema
Synonym
ess_request_history request_history_view See table for the QueryField and View Column
mapping.
ess_request_property request_property_view create or replace view request_property_view
as
select
requestid,
name,
scope,
datatype,
value,
lobvalue,
lobflag
from request_property
with read only;
Table 64–6 lists the required data privilege (form_function) for a user to perform an
Oracle Enterprise Scheduler runtimeService operation.
Table 64–8 lists the Oracle Fusion Data Security policies available for use with Oracle
Enterprise Scheduler out of the box.
Table 64–8 Oracle Fusion Data Security Policies for Oracle Enterprise Scheduler
Oracle Fusion Data Security Policy Description
ESS_REQUEST_SUBMITTER_ADMIN_SUBMITTED_ The submitter of the job request is permitted to view and
REQUESTS administer the requests they submitted.
ESS_REQUEST_SUBMITTER_ADMIN_SUBMITTED_ The submitter of the job requests and subrequests is permitted to
REQUESTS_SUBREQS view and administer on the requests they submitted.
ESS_REQUEST_RUNASUSER_ADMIN_EXECUTED_ The runAs user is permitted to view and administer the requests
REQUESTS they execute.
ESS_REQUEST_RUNASUSER_VIEWOUTPUT_ The runAs user is permitted to view the output of the job requests
EXECUTED_REQUESTS they executed.
For more information about the runAs user, or elevating access privileges, see
Section 63.13, "Elevating Access Privileges for a Scheduled Job."
64.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 chapter "Managing Policies and Policy Objects" in the Oracle Fusion Middleware
Oracle Authorization Policy Manager Administrator's Guide (Oracle Fusion Applications
Edition).
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. From the Actions menu, click New.
c. Define a resource with the resource type ESSMetadataResourceType, as well
as the name and display name of the Oracle Enterprise Scheduler component
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:
■ Appendix A, "Working with the Application Taxonomy"
■ Appendix B, "ECSF Command Line Administration Utility"
Beta Draft
Beta Draft
A
AWorking 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:
■ The theory of the application taxonomy
■ How to view the taxonomy
■ How to extract taxonomy data from a table and how to insert taxonomy data into
a table
This appendix includes the following sections:
■ Section A.1, "Introduction to the Oracle Fusion Application Taxonomy"
■ Section A.2, "Working with Objects and Methods in the Application Taxonomy"
■ Section A.3, "Understanding Taxonomy MBeans"
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 A–1:
Seed Data
The Oracle Fusion Applications Design Repository (ADR) team has provided
Taxonomy seed data for the following levels in the hierarchy: Application Line,
Family, Application, and Logical Business Area (LBA).
You can create as fine-grained an application taxonomy as you wish. You can break up
an application into sub-applications or pseudo applications. For example, there are
many setup use cases where an overall process is made up of many smaller
subordinate processes.
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.
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 A–1 lists
the task flow and its parameters.
Who Columns
All tables containing seeded or transaction data must include the Who columns shown
in Table A–2:
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 A–3. You do not need to add extended Who columns if the table does not
already have them.
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.
3. The new connection will display in the Connections tree, shown in Figure A–4:
4. The Entity and View objects are located in Taxonomy-Model.jar > Business
Components, shown in Figure A–5:
Figure A–5 Locating the Entity and View Objects in the Connections Tree
Notes:
■ 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 unless the API accepts the
Taxonomy table primary key moduleId.
■ The package for the private view objects and the application
module conforms to Applications Packaging standards.
The application module is
oracle.apps.fnd.applcore.taxonomy.taxonomyService.applica
tionModule.
The view objects module is
oracle.apps.fnd.applcore.taxonomy.taxonomyService.view.
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.
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 User-
and Site-level in an application.
MBeans as viewed from Enterprise Manager are shown in Figure A–6.
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
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.
Table B–1 shows the commands you can use to administer search. The commands
appear in alphabetical order.