Академический Документы
Профессиональный Документы
Культура Документы
October 2013
Documentation for developers that describes how to design,
secure, test, and deploy Oracle Service-Oriented Architecture
(SOA) composite applications consisting of service and
reference binding components and Oracle BPEL process,
human task, business rule, Oracle Mediator, and spring
service components. Includes additional information on
designing transformations and business events, integrating
Oracle Business Activity Monitoring and Oracle User
Messaging Service into composites, and acting upon human
tasks during runtime in Oracle BPM Worklist.
Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite, 11g Release 1 (11.1.1.7)
E10224-20
Copyright 2005, 2013, Oracle and/or its affiliates. All rights reserved.
Primary Author:
Contributor:
Oracle Corporation
Oracle SOA Suite development, product management, and quality assurance teams
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 ................................................................................................................................................................ lix
Audience...................................................................................................................................................... lix
Documentation Accessibility .................................................................................................................... lix
Related Documents .................................................................................................................................... lix
Conventions ................................................................................................................................................. lx
2.2.2
2.2.3
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.3.6
2.3.7
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.5
2.5.1
2.5.2
2.5.3
2.6
2.7
2.7.1
2.8
2.8.1
2.8.2
What You May Need to Know About Adding and Deleting a Service Component .. 2-9
How to Edit a Service Component ............................................................................. 2-9
Adding Service Binding Components ............................................................................ 2-10
How to Add a Service Binding Component ............................................................ 2-10
How to Define the Interface (WSDL) for a Web Service .......................................... 2-12
How to View Schemas ............................................................................................. 2-16
How to Edit a Service Binding Component ............................................................. 2-17
What You May Need to Know About Adding and Deleting Services ..................... 2-17
What You May Need to Know About Using the Same Namespace in Different WSDL
Files in the Same Composite .................................................................................... 2-17
What You May Need to Know About WSDL Browsing in the Resource Palette When
the SOA Infrastructure Uses Both Internal and External Oracle HTTP Servers ....... 2-17
Adding Reference Binding Components ........................................................................ 2-18
How to Add a Reference Binding Component ........................................................ 2-18
What You May Need to Know About Adding and Deleting References ................. 2-20
What You May Need to Know About WSDL References ........................................ 2-20
What You May Need to Know About Mixed Message Types in a WSDL File ......... 2-21
What You May Need to Know About Invoking the Default Revision of a Composite ...
2-21
Adding Wires ................................................................................................................. 2-21
How to Wire a Service and a Service Component ................................................... 2-22
How to Wire a Service Component and a Reference ............................................... 2-23
What You May Need to Know About Adding and Deleting Wires ......................... 2-25
Adding Security ............................................................................................................. 2-26
Deploying a SOA Composite Application ...................................................................... 2-26
How to Invoke Deployed SOA Composite Applications ......................................... 2-26
Managing and Testing a SOA Composite Application .................................................. 2-27
How to Manage Deployed SOA Composite Applications in Oracle JDeveloper ..... 2-27
How to Test a Deployed SOA Composite Application ............................................ 2-30
iv
3.5.5
3.5.6
3.5.7
3.6
3.7
3.8
Part II
4
5.7
5.7.1
5.7.2
5.8
5.8.1
5.8.2
5.9
5.9.1
5.9.2
5.10
vi
6.15.1
How to Use bpelx:append ....................................................................................... 6-25
6.15.1.1
bpelx:append in BPEL 1.1 .................................................................................. 6-25
6.15.1.2
bpelx:append in BPEL 2.0 .................................................................................. 6-25
6.15.2
How to Use bpelx:insertBefore ................................................................................ 6-26
6.15.2.1
bpelx:insertBefore in BPEL 1.1 ........................................................................... 6-26
6.15.2.2
bpelx:insertBefore in BPEL 2.0 ........................................................................... 6-27
6.15.3
How to Use bpelx:insertAfter ................................................................................. 6-27
6.15.3.1
bpelx:insertAfter in BPEL 1.1 ............................................................................. 6-28
6.15.3.2
bpelx:insertAfter in BPEL 2.0 ............................................................................. 6-29
6.15.4
How to Use bpelx:remove ........................................................................................ 6-29
6.15.4.1
bpelx:remove in BPEL 1.1 .................................................................................. 6-30
6.15.4.2
bpelx:remove in BPEL 2.0 .................................................................................. 6-31
6.15.5
How to Use bpelx:rename and XSD Type Casting ................................................... 6-31
6.15.5.1
bpelx:rename in BPEL 1.1 .................................................................................. 6-31
6.15.5.2
bpelx:rename in BPEL 2.0 .................................................................................. 6-33
6.15.6
How to Use bpelx:copyList ...................................................................................... 6-33
6.15.6.1
bpelx:copyList in BPEL 1.1 ................................................................................ 6-34
6.15.6.2
bpelx:copyList in BPEL 2.0 ................................................................................ 6-35
6.15.7
How to Use Assign Extension Attributes ................................................................. 6-36
6.15.7.1
ignoreMissingFromData Attribute .................................................................... 6-36
6.15.7.2
insertMissingToData Attribute .......................................................................... 6-36
6.15.7.3
keepSrcElementName Attribute ........................................................................ 6-36
6.16
Validating XML Data ..................................................................................................... 6-37
6.16.1
How to Validate XML Data in BPEL 1.1 .................................................................. 6-37
6.16.2
How to Validate XML Data in BPEL 2.0 .................................................................. 6-37
6.17
Using Element Variables in Message Exchange Activities in BPEL 2.0 .......................... 6-38
6.18
Mapping WSDL Message Parts in BPEL 2.0 ................................................................... 6-39
6.18.1
How to Map WSDL Message Parts .......................................................................... 6-40
6.18.2
What Happens When You Map WSDL Message Parts ............................................ 6-41
6.19
Importing Process Definitions in BPEL 2.0 ..................................................................... 6-46
6.20
Manipulating XML Data Sequences That Resemble Arrays ........................................... 6-47
6.20.1
How to Statically Index into an XML Data Sequence That Uses Arrays .................. 6-47
6.20.2
How to Use SOAP-Encoded Arrays ......................................................................... 6-48
6.20.2.1
SOAP-Encoded Arrays in BPEL 2.0 ................................................................... 6-49
6.20.2.2
Declaring a SOAP Array Using a wsdl:arrayType Attribute Inside a Schema .. 6-49
6.20.3
How to Determine Sequence Size ............................................................................ 6-51
6.20.4
How to Dynamically Index by Applying a Trailing XPath to an Expression ........... 6-51
6.20.4.1
Applying a Trailing XPath to the Result of getVariableData ............................ 6-51
6.20.4.2
Using the bpelx:append Extension to Append New Items to a Sequence ......... 6-52
6.20.4.3
Merging Data Sequences ................................................................................... 6-52
6.20.4.4
Generating Functionality Equivalent to an Array of an Empty Element ........... 6-53
6.20.5
What You May Need to Know About Using the Array Identifier ........................... 6-54
6.21
Converting from a String to an XML Element ................................................................ 6-54
6.21.1
How To Convert from a String to an XML Element ................................................. 6-54
6.22
Understanding Document-Style and RPC-Style WSDL Differences ............................... 6-55
6.22.1
How To Use RPC-Style Files .................................................................................... 6-55
6.23
Manipulating SOAP Headers in BPEL ........................................................................... 6-56
vii
6.23.1
How to Receive SOAP Headers in BPEL ................................................................. 6-56
6.23.2
How to Send SOAP Headers in BPEL ...................................................................... 6-57
6.24
Declaring Extension Namespaces in BPEL 2.0 ............................................................... 6-58
6.24.1
How to Declare Extension Namespaces .................................................................. 6-58
6.24.2
What Happens When You Create an Extension ...................................................... 6-59
viii
Routing Callback Messages to the Correct Endpoint when Multiple Receive or Pick
Activities Use the Same Partner Link ............................................................................. 8-12
8.3.1
How to Route Callback Messages to the Correct Endpoint when Multiple Receive and
Pick Activities Use the Same Partner Link ............................................................... 8-12
8.4
Managing Idempotence at the Partner Link Operation Level ........................................ 8-13
8.4.1
How to Manage Idempotence at the Partner Link Operation Level ........................ 8-14
8.5
Creating a Dynamic Partner Link at Design Time for Use at Runtime ........................... 8-14
8.5.1
How To Create a Dynamic Partner Link at Design Time for Use at Runtime .......... 8-15
8.6
Overriding Security Certificates when Invoking Dynamic Partner Links ...................... 8-16
8.7
Overriding WSDL Files of Dynamic Partner Links ........................................................ 8-19
8.8
Using WS-Addressing in an Asynchronous Service ....................................................... 8-21
8.8.1
How to Use WS-Addressing in an Asynchronous Service ....................................... 8-22
8.8.1.1
Using TCP Tunneling to View Messages Exchanged Between Programs ......... 8-22
8.3
10
ix
10.3.1
10.3.1.1
10.3.1.2
10.3.2
10.3.2.1
10.3.2.2
11
Customizing the Number of Flow Activities with the flowN Activity in BPEL 1.1 10-12
How to Create a flowN Activity ...................................................................... 10-13
What Happens When You Create a FlowN Activity ....................................... 10-14
Processing Multiple Sets of Activities with the forEach Activity in BPEL 2.0 ........ 10-16
How to Create a forEach Activity .................................................................... 10-18
What Happens When You Create a forEach Activity ...................................... 10-20
12
xi
12.12.3
What Happens When You Create a compensate Activity ..................................... 12-49
12.12.4
Using a compensateScope Activity in BPEL 2.0 ..................................................... 12-50
12.12.5
How to Create a compensateScope Activity .......................................................... 12-50
12.12.6
What Happens When You Create a compensateScope Activity ............................ 12-50
12.13 Stopping a Business Process Instance with a Terminate or Exit Activity ..................... 12-51
12.13.1
Stopping a Business Process Instance with the Terminate Activity in BPEL 1.1 .... 12-51
12.13.1.1
How to Create a Terminate Activity ............................................................... 12-51
12.13.1.2
What Happens When You Create a Terminate Activity .................................. 12-52
12.13.2
Immediately Ending a Business Process Instance with the Exit Activity in BPEL 2.0 .....
12-52
12.13.2.1
How to Create an Exit Activity ....................................................................... 12-52
12.13.2.2
What Happens When You Create an Exit Activity .......................................... 12-53
12.14 Throwing Faults with Assertion Conditions ................................................................ 12-53
12.14.1
Introducing Assertion Conditions ......................................................................... 12-56
12.14.1.1
bpelx:postAssert and bpelx:preAssert Extensions ........................................... 12-56
12.14.1.2
Use of faultName and message Attributes ..................................................... 12-57
12.14.1.3
Multiple Assertions ......................................................................................... 12-57
12.14.1.4
Use of Built-in and Custom XPath Functions and $variable References ........ 12-58
12.14.1.5
Assertion Condition Evaluation Logging of Events to the Instance Audit Trail ......
12-59
12.14.1.6
Expressions Not Evaluating to an XML Schema Boolean Type Throw a Fault .......
12-59
12.14.1.7
Assertion Conditions in a Standalone Assert Activity .................................... 12-59
12.14.2
How to Create Assertion Conditions ..................................................................... 12-60
12.14.3
How to Disable Assertions .................................................................................... 12-63
12.14.4
What Happens When You Create Assertion Conditions ....................................... 12-63
14
xii
14.3.1
How to Add Custom Classes and JAR Files ............................................................ 14-6
14.4
Using Java Embedding in a BPEL Process in Oracle JDeveloper .................................... 14-7
14.4.1
How To Use Java Embedding in a BPEL Process in Oracle JDeveloper ................... 14-7
14.4.2
What You May Need to Know About Using thread.sleep() in a Java Embedding
Activity .................................................................................................................... 14-8
14.5
Embedding Service Data Objects with bpelx:exec .......................................................... 14-8
14.6
Sharing a Custom Implementation of a Class with Oracle BPEL Process Manager ....... 14-9
14.6.1
How to Configure the BPEL Connection Manager Class to Take Precedence ....... 14-10
15
16
xiii
17
18
Part III
xiv
19.3
Introduction to the Mediator Editor Environment ......................................................... 19-4
19.4
Creating a Mediator ....................................................................................................... 19-6
19.4.1
How to Create a Mediator ........................................................................................ 19-6
19.5
Configuring the Mediator Interface Definition ............................................................. 19-10
19.5.1
How to Configure the Mediator Interface Definition ............................................. 19-11
19.5.2
What Happens When You Create a Mediator ....................................................... 19-15
19.5.2.1
Without an Interface Definition ....................................................................... 19-16
19.5.2.2
With a WSDL-Based Interface ......................................................................... 19-16
19.5.2.3
With a One-Way Interface Definition .............................................................. 19-16
19.5.2.4
With a Synchronous Interface Definition ........................................................ 19-17
19.5.2.5
With an Asynchronous Interface Definition .................................................... 19-17
19.5.2.6
With an Event Subscription ............................................................................. 19-18
19.6
Defining an Interface for a Mediator ............................................................................ 19-19
19.6.1
How to Define an Interface for a Mediator ........................................................... 19-19
19.7
Generating a WSDL File ............................................................................................... 19-21
19.7.1
How to Generate a WSDL File ............................................................................... 19-21
19.8
Specifying Validation and Priority Properties .............................................................. 19-28
19.9
Modifying a Mediator Service Component .................................................................. 19-29
19.9.1
How To Modify Mediator Operations ................................................................... 19-29
19.9.2
How To Modify Mediator Event Subscriptions ..................................................... 19-29
xv
20.3.2.14
How to Work with Attachments ..................................................................... 20-34
20.3.2.15
How to Use Java Callouts ................................................................................ 20-34
20.3.3
How to Create Dynamic Routing Rules ................................................................. 20-43
20.3.4
What You May Need to Know About Using Dynamic Routing Rules .................. 20-46
20.3.5
How to Define Default Routing Rules ................................................................... 20-46
20.3.5.1
Default Rule Scenarios .................................................................................... 20-46
20.3.5.2
Default Rule Target ......................................................................................... 20-47
20.3.5.3
Default Rule: Validation, Transformation, and Assign Functionality ............. 20-48
20.3.5.4
Default Rule: Java Callouts .............................................................................. 20-48
20.3.5.5
Default Rule: Mediator .mplan File ................................................................. 20-48
20.4
Mediator Routing Use Cases ........................................................................................ 20-49
xvi
23.2.2
FIFO Resequencer .................................................................................................... 23-3
23.2.2.1
Overview of the FIFO Resequencer ................................................................... 23-4
23.2.2.2
Information Required for FIFO Resequencing .................................................. 23-4
23.2.2.3
Example of the FIFO Resequencer ..................................................................... 23-4
23.2.3
Best Effort Resequencer ........................................................................................... 23-4
23.2.3.1
Overview of the Best Effort Resequencer .......................................................... 23-5
23.2.3.2
Best Effort Resequencer Message Selection Strategies ....................................... 23-5
23.2.3.3
Best Effort Resequencer Message Delivery ........................................................ 23-6
23.2.3.4
Information Required for Best Effort Resequencing .......................................... 23-6
23.2.3.5
Example of Best Effort Resequencing Based on Maximum Rows ..................... 23-6
23.2.3.6
Example of Best Effort Resequencing Based on a Time Window ...................... 23-7
23.3
Configuring the Resequencer ......................................................................................... 23-7
23.3.1
How to Specify the Resequencing Level .................................................................. 23-8
23.3.2
How to Configure the Resequencing Strategy ......................................................... 23-8
Part IV
25
25.1
25.1.1
25.2
25.2.1
25.2.2
25.2.3
25.2.4
25.3
25.3.1
25.3.2
25.4
25.4.1
25.4.2
25.4.3
25.4.4
xvii
25.5.2
How to Select and Modify a Decision Function in a Business Rule Component ... 25-19
25.6
Running Business Rules in a Composite Application .................................................. 25-21
25.6.1
What You May Need to Know About Testing a Standalone Decision Service
Component ........................................................................................................... 25-21
25.7
Using Business Rules with Oracle ADF Business Components Fact Types ................. 25-23
Part V
xviii
27.2.1.5
Notifications ...................................................................................................... 27-8
27.2.1.6
Task Forms ........................................................................................................ 27-9
27.2.1.7
Advanced Concepts ......................................................................................... 27-10
27.2.1.8
Reports and Audit Trails ................................................................................. 27-10
27.2.2
Introduction to the Stages of Human Workflow Design ........................................ 27-11
27.3
Introduction to Human Workflow Features ................................................................. 27-11
27.3.1
Human Workflow Use Cases ................................................................................. 27-11
27.3.1.1
Task Assignment to a User or Role .................................................................. 27-12
27.3.1.2
Use of the Various Participant Types .............................................................. 27-12
27.3.1.3
Escalation, Expiration, and Delegation ............................................................ 27-12
27.3.1.4
Automatic Assignment and Delegation .......................................................... 27-13
27.3.1.5
Dynamic Assignment of Users Based on Task Content ................................... 27-13
27.4
Introduction to Human Workflow Architecture .......................................................... 27-13
27.4.1
Human Workflow Services .................................................................................... 27-14
27.4.2
Use of Human Task ............................................................................................... 27-16
27.4.3
Service Engines ...................................................................................................... 27-17
28
28.1
28.1.1
28.1.2
28.1.3
28.2
28.2.1
28.2.2
28.2.3
28.3
28.4
28.4.1
28.4.2
xix
28.4.7
28.4.8
28.4.8.1
28.4.8.2
28.4.9
29
What You May Need to Know About Deleting a Partner Link Generated by a Human
Task ....................................................................................................................... 28-18
How to Define Outcome-Based Modeling ............................................................. 28-18
Specifying Payload Updates ............................................................................ 28-18
Using Case Statements for Other Task Conclusions ........................................ 28-18
What You May Need to Know About Encoding an Attachment ........................... 28-19
xx
29.5.1
How to Route Tasks to All Participants in the Specified Order ............................. 29-43
29.5.1.1
Allowing All Participants to Invite Other Participants .................................... 29-44
29.5.1.2
Stopping Routing of a Task to Further Participants ........................................ 29-45
29.5.1.3
Enabling Early Completion in Parallel Subtasks ............................................. 29-46
29.5.1.4
Completing Parent Subtasks of Early Completing Subtasks ........................... 29-46
29.5.2
How to Specify Advanced Task Routing Using Business Rules ............................ 29-47
29.5.2.1
Introduction to Advanced Task Routing Using Business Rules ...................... 29-47
29.5.2.2
Facts ................................................................................................................. 29-47
29.5.2.3
Action Types ................................................................................................... 29-48
29.5.2.4
Sample Ruleset ................................................................................................ 29-49
29.5.2.5
Linked Dictionary Support .............................................................................. 29-51
29.5.2.6
Creating Advanced Routing Rules .................................................................. 29-51
29.5.3
How to Use External Routing ................................................................................ 29-52
29.5.4
How to Configure the Error Assignee .................................................................... 29-54
29.6
Specifying Multilingual Settings and Style Sheets ........................................................ 29-56
29.6.1
How to Specify WordML and Other Style Sheets for Attachments ....................... 29-56
29.6.2
How to Specify Multilingual Settings .................................................................... 29-57
29.7
Escalating, Renewing, or Ending the Task ................................................................... 29-58
29.7.1
Introduction to Escalation and Expiration Policy .................................................. 29-58
29.7.2
How to Specify a Policy to Never Expire ............................................................... 29-59
29.7.3
How to Specify a Policy to Expire .......................................................................... 29-59
29.7.4
How to Extend an Expiration Policy Period .......................................................... 29-60
29.7.5
How to Escalate a Task Policy ................................................................................ 29-60
29.7.6
How to Specify Escalation Rules ............................................................................ 29-61
29.7.7
How to Specify a Due Date .................................................................................... 29-62
29.8
Specifying Participant Notification Preferences ........................................................... 29-63
29.8.1
How to Notify Recipients of Changes to Task Status ............................................. 29-64
29.8.2
How to Edit the Notification Message ................................................................... 29-66
29.8.3
How to Set Up Reminders ..................................................................................... 29-67
29.8.4
How to Change the Character Set Encoding .......................................................... 29-67
29.8.5
How to Secure Notifications to Exclude Details .................................................... 29-67
29.8.6
How to Display the Oracle BPM Worklist URL in Notifications ........................... 29-67
29.8.7
How to Make Email Messages Actionable ............................................................. 29-68
29.8.8
How to Send Task Attachments with Email Notifications ..................................... 29-68
29.8.9
How to Send Email Notifications to Groups and Application Roles ..................... 29-68
29.8.10
How to Customize Notification Headers ............................................................... 29-69
29.9
Specifying Access Policies and Task Actions on Task Content ..................................... 29-69
29.9.1
How to Specify Access Policies on Task Content ................................................... 29-69
29.9.1.1
Introduction to Access Rules ........................................................................... 29-70
29.9.1.2
Specifying User Privileges for Acting on Task Content ................................... 29-71
29.9.1.3
Specifying Actions for Acting Upon Tasks ..................................................... 29-72
29.9.2
How to Specify a Workflow Digital Signature Policy ............................................ 29-73
29.9.2.1
Specifying a Certificate Authority ................................................................... 29-75
29.10 Specifying Restrictions on Task Assignments .............................................................. 29-75
29.10.1
How to Specify Restrictions on Task Assignments ................................................ 29-75
29.11 Specifying Java or Business Event Callbacks ................................................................ 29-76
29.11.1
How to Specify Callback Classes on Task Status ................................................... 29-76
xxi
29.11.1.1
Specifying Java Callbacks ................................................................................ 29-77
29.11.1.2
Specifying Business Event Callbacks ............................................................... 29-78
29.11.2
How to Specify Task and Routing Customizations in BPEL Callbacks ................. 29-80
29.11.3
How to Disable BPEL Callbacks ............................................................................ 29-81
29.12 Storing Documents in Oracle Enterprise Content Management .................................. 29-81
30
xxii
30.8.6
What You May Need to Know About Undeploying a Task Flow .......................... 30-46
30.9
Displaying a Task Form in the Worklist ....................................................................... 30-47
30.9.1
How To Display the Task Form in the Worklist .................................................... 30-47
30.10 Displaying a Task in an Email Notification .................................................................. 30-48
30.10.1
Changing the Text for the Worklist Application in Task Notifications .................. 30-49
30.10.2
Changing the URL of the Worklist Application in Task Notifications ................... 30-49
30.10.3
Showing or Hiding the URL of the Worklist Application in Task Notifications .... 30-49
30.11 Reusing the Task Flow Application with Multiple Human Tasks ................................ 30-50
30.11.1
How To Reuse the Task Flow Application with Multiple Human Tasks ............... 30-50
30.11.2
How to Reuse the Task Flow Application with Different Actions ......................... 30-50
32
xxiii
32.4.4
How To Act on Tasks That Require a Digital Signature ........................................ 32-35
32.5
Approving Tasks .......................................................................................................... 32-38
32.6
Setting a Vacation Period ............................................................................................. 32-39
32.7
Setting Rules ................................................................................................................. 32-41
32.7.1
How To Create User Rules .................................................................................... 32-41
32.7.2
How To Create Group Rules ................................................................................. 32-42
32.7.3
Assignment Rules for Tasks with Multiple Assignees ........................................... 32-44
32.8
Using the Worklist Administration Functions ............................................................. 32-44
32.8.1
How To Manage Other Users or Groups Rules (as an Administrator) ................ 32-45
32.8.2
How to Specify the Login Page Realm Label ......................................................... 32-46
32.8.3
How to Specify the Resource Bundle ..................................................................... 32-47
32.8.4
How to Specify the Language Locale Information ................................................. 32-47
32.8.5
How to Specify a Branding Logo ........................................................................... 32-48
32.8.6
How to Specify the Branding Title ......................................................................... 32-49
32.8.7
How to Choose a Skin ............................................................................................ 32-50
32.8.8
How to Enable Customized Applications and Links ............................................. 32-51
32.8.9
How to Specify an Image for a Task Action ........................................................... 32-52
32.9
Specifying Notification Settings ................................................................................... 32-52
32.9.1
Messaging Filter Rules ........................................................................................... 32-53
32.9.1.1
Data Types ...................................................................................................... 32-53
32.9.1.2
Attributes ........................................................................................................ 32-53
32.9.2
Rule Actions .......................................................................................................... 32-54
32.9.3
Managing Messaging Channels ............................................................................. 32-54
32.9.3.1
Viewing Your Messaging Channels ................................................................ 32-55
32.9.3.2
Creating, Editing, and Deleting a Messaging Channel .................................... 32-55
32.9.4
Managing Messaging Filters .................................................................................. 32-56
32.9.4.1
Viewing Messaging Filters .............................................................................. 32-56
32.9.4.2
Creating Messaging Filters .............................................................................. 32-56
32.9.4.3
Editing a Messaging Filter ............................................................................... 32-58
32.9.4.4
Deleting a Messaging Filter ............................................................................. 32-58
32.10 Using Mapped Attributes (Flex Fields) ........................................................................ 32-58
32.10.1
How To Map Attributes ......................................................................................... 32-59
32.10.2
Custom Mapped Attributes ................................................................................... 32-62
32.11 Creating Worklist Reports ............................................................................................ 32-63
32.11.1
How To Create Reports ......................................................................................... 32-64
32.11.2
What Happens When You Create Reports ............................................................. 32-65
32.11.2.1
Unattended Tasks Report ................................................................................ 32-65
32.11.2.2
Tasks Priority Report ....................................................................................... 32-66
32.11.2.3
Tasks Cycle Time Report ................................................................................. 32-67
32.11.2.4
Tasks Productivity Report ............................................................................... 32-67
32.12 Accessing Oracle BPM Worklist in Local Languages and Time Zones ........................ 32-68
32.12.1
Strings in Oracle BPM Worklist ............................................................................. 32-69
32.12.2
How to Change the Preferred Language, Display Names of Users, and Time Zone
Settings if the Identity Store is LDAP-Based .......................................................... 32-69
32.12.3
How to Change the Language in Which Tasks Are Displayed .............................. 32-70
32.12.4
How To Change the Language Preferences from a JAZN XML File ...................... 32-71
32.12.5
What You May Need to Know Setting Display Languages in Worklist ................ 32-72
32.12.6
How To Change the Time Zone Used in the Worklist ........................................... 32-72
xxiv
33
xxv
34.1.9.1
Internationalization of Attribute Labels .......................................................... 34-19
34.1.10
Evidence Store Service and Digital Signatures ...................................................... 34-20
34.1.10.1
Prerequisites .................................................................................................... 34-22
34.1.10.2
Interfaces and Methods ................................................................................... 34-22
34.1.11
Task Instance Attributes ........................................................................................ 34-24
34.2
Notifications from Human Workflow .......................................................................... 34-28
34.2.1
Contents of Notification ......................................................................................... 34-29
34.2.2
Error Message Support .......................................................................................... 34-30
34.2.3
Reliability Support ................................................................................................. 34-30
34.2.4
Management of Oracle Human Workflow Notification Service ............................ 34-31
34.2.5
How to Configure the Notification Channel Preferences ...................................... 34-31
34.2.6
How to Configure Notification Messages in Different Languages ........................ 34-32
34.2.7
How to Send Actionable Messages ........................................................................ 34-33
34.2.7.1
How to Send Actionable Emails for Human Tasks ......................................... 34-33
34.2.8
How to Send Inbound and Outbound Attachments .............................................. 34-35
34.2.9
How to Send Inbound Comments ......................................................................... 34-35
34.2.10
How to Send Secure Notifications ......................................................................... 34-35
34.2.11
How to Set Channels Used for Notifications ......................................................... 34-35
34.2.12
How to Send Reminders ........................................................................................ 34-35
34.2.13
How to Set Automatic Replies to Unprocessed Messages ..................................... 34-36
34.2.14
How to Create Custom Notification Headers ........................................................ 34-37
34.3
Assignment Service Configuration ............................................................................... 34-37
34.3.1
Dynamic Assignment and Task Escalation Patterns .............................................. 34-38
34.3.1.1
How to Implement a Dynamic Assignment Pattern ....................................... 34-39
34.3.1.2
How to Configure Dynamic Assignment Patterns .......................................... 34-40
34.3.1.3
How to Configure Display Names for Dynamic Assignment Patterns ........... 34-41
34.3.1.4
How to Implement a Task Escalation Pattern ................................................. 34-42
34.3.2
Dynamically Assigning Task Participants with the Assignment Service ............... 34-42
34.3.2.1
How to Implement an Assignment Service ..................................................... 34-43
34.3.2.2
Example of Assignment Service Implementation ............................................ 34-43
34.3.2.3
How to Deploy a Custom Assignment Service ............................................... 34-45
34.3.3
Custom Escalation Function .................................................................................. 34-46
34.4
Class Loading for Callbacks and Resource Bundles ..................................................... 34-46
34.5
Resource Bundles in Workflow Services ...................................................................... 34-46
34.5.1
Task Resource Bundles .......................................................................................... 34-47
34.5.2
Global Resource Bundle WorkflowLabels.properties ......................................... 34-47
34.5.3
Worklist Client Resource Bundles ......................................................................... 34-49
34.5.4
Task Detail ADF Task Flow Resource Bundles ...................................................... 34-49
34.5.5
Specifying Stage and Participant Names in Resource Bundles .............................. 34-50
34.5.6
Case Sensitivity in Group and Application Role Names ...................................... 34-50
34.6
Introduction to Human Workflow Client Integration with Oracle WebLogic Server
Services ........................................................................................................................ 34-50
34.6.1
Human Workflow Services Clients ........................................................................ 34-50
34.6.1.1
Task Query Service Client Code ...................................................................... 34-53
34.6.1.2
Configuration Option ...................................................................................... 34-55
34.6.1.3
Client Logging ................................................................................................. 34-58
34.6.1.4
Configuration Migration Utility ...................................................................... 34-58
34.6.2
Identity Propagation .............................................................................................. 34-58
xxvi
34.6.2.1
Enterprise JavaBeans Identity Propagation .................................................... 34-59
34.6.2.2
SAML Token Identity Propagation for SOAP Client ....................................... 34-59
34.6.2.3
Public Key Alias .............................................................................................. 34-61
34.6.3
Client JAR Files ...................................................................................................... 34-61
34.7
Task States in a Human Task ........................................................................................ 34-62
34.8
Database Views for Oracle Workflow .......................................................................... 34-62
34.8.1
Unattended Tasks Report View ............................................................................. 34-62
34.8.2
Task Cycle Time Report View ................................................................................ 34-63
34.8.3
Task Productivity Report View .............................................................................. 34-64
34.8.4
Task Priority Report View ..................................................................................... 34-65
35
xxvii
36.2.3.3
36.2.4
36.2.5
36.3
36.3.1
36.4
36.4.1
36.4.2
Part VI
xxviii
Part VII
40
xxix
40.1.2
Guidelines for Using the XSLT Mapper ................................................................... 40-6
40.2
Creating an XSL Map File .............................................................................................. 40-7
40.2.1
How to Create an XSL Map File in Oracle BPEL Process Manager .......................... 40-7
40.2.2
How to Create an XSL Map File from Imported Source and Target Schema Files in
Oracle BPEL Process Manager ................................................................................. 40-9
40.2.3
How to Create an XSL Map File in Oracle Mediator .............................................. 40-11
40.2.4
What You May Need to Know About Creating an XSL Map File .......................... 40-14
40.2.5
What You May Need to Know About Importing a Composite with an XSL File .. 40-15
40.2.6
What Happens at Runtime If You Pass a Payload Through Oracle Mediator Without
Creating an XSL Map File ...................................................................................... 40-15
40.2.7
What Happens If You Receive an Empty Namespace Tag in an Output Message 40-15
40.3
Designing Transformation Maps with the XSLT Mapper ............................................ 40-16
40.3.1
How to Add Additional Sources ........................................................................... 40-16
40.3.2
How to Perform a Simple Copy by Linking Nodes ............................................... 40-17
40.3.3
How to Set Constant Values .................................................................................. 40-18
40.3.4
How to Add Functions .......................................................................................... 40-19
40.3.4.1
Editing Function Parameters ........................................................................... 40-20
40.3.4.2
Chaining Functions ......................................................................................... 40-20
40.3.4.3
Using Named Templates ................................................................................. 40-21
40.3.4.4
Importing User-Defined Functions ................................................................. 40-21
40.3.5
How to Edit XPath Expressions ............................................................................. 40-24
40.3.6
How to Add XSLT Constructs ............................................................................... 40-25
40.3.6.1
Using Conditional Processing with xsl:if ........................................................ 40-26
40.3.6.2
Using Conditional Processing with xsl:choose ................................................ 40-27
40.3.6.3
Creating Loops with xsl:for-each ..................................................................... 40-28
40.3.6.4
Cloning xsl:for-each ........................................................................................ 40-29
40.3.6.5
Applying xsl:sort to xsl:for-each ...................................................................... 40-29
40.3.6.6
Copying Nodes with xsl:copy-of ..................................................................... 40-30
40.3.6.7
Including External Templates with xsl:include ............................................... 40-31
40.3.7
How to Automatically Map Nodes ........................................................................ 40-31
40.3.7.1
Using Auto Mapping with Confirmation ........................................................ 40-33
40.3.8
What You May Need to Know About Automatic Mapping .................................. 40-34
40.3.9
How to View Unmapped Target Nodes ................................................................ 40-35
40.3.10
How to Generate and Use Dictionaries .................................................................. 40-36
40.3.11
What You May Need to Know About Generating Dictionaries in Which Functions are
Used ....................................................................................................................... 40-37
40.3.12
How to Create Map Parameters and Variables ...................................................... 40-38
40.3.12.1
Creating a Map Parameter .............................................................................. 40-38
40.3.12.2
Creating a Map Variable ................................................................................. 40-39
40.3.13
How to Search Source and Target Nodes .............................................................. 40-40
40.3.14
How to Control the Generation of Unmapped Target Elements ........................... 40-41
40.3.15
How to Ignore Elements in the XSLT Document ................................................... 40-42
40.3.16
How to Import a Customization File to Specify Display Preferences in the XSLT
Mapper .................................................................................................................. 40-42
40.3.17
How to Replace a Schema in the XSLT Mapper ..................................................... 40-43
40.3.18
How to Substitute Elements and Types in the Source and Target Trees ................ 40-43
40.3.19
How to Resolve Low Memory Issues in the XSLT Mapper ................................... 40-46
40.4
Testing the Map ........................................................................................................... 40-47
xxx
40.4.1
How to Test the Transformation Mapping Logic ................................................... 40-47
40.4.2
How to Generate Reports ....................................................................................... 40-49
40.4.2.1
Correcting Memory Errors When Generating Reports .................................... 40-50
40.4.3
How to Customize Sample XML Generation ......................................................... 40-51
40.5
Demonstrating Features of the XSLT Mapper .............................................................. 40-51
40.5.1
How To Open the Application ............................................................................... 40-52
40.5.2
How To Create a New XSLT Map in the BPEL Process ......................................... 40-52
40.5.3
How To Use Type Substitution to Map the Purchase Order Items ........................ 40-53
40.5.4
How To Reference Additional Source Elements .................................................... 40-54
40.5.5
How To Use Element Substitution to Map the Shipping Address ......................... 40-56
40.5.6
How To Map the Remaining Fields ....................................................................... 40-57
40.5.7
How To Test the Map ............................................................................................ 40-58
41
Part VIII
xxxi
43
xxxii
How to Manage SOA Composite Applications with the WLST Utility ................. 43-42
How to Manage SOA Composite Applications with ant Scripts ............................ 43-43
How to Use ant to Automate the Testing of a SOA Composite Application ... 43-44
How to Use ant to Compile a SOA Composite Application ............................ 43-45
How to Use ant to Package a SOA Composite Application into a Composite SAR
File ................................................................................................................... 43-46
43.7.6.4
How to Use ant to Deploy a SOA Composite Application .............................. 43-47
43.7.6.5
How to Use ant to Undeploy a SOA Composite Application .......................... 43-48
43.7.6.6
How to Use ant to Export a Composite into a SAR File ................................... 43-49
43.7.6.7
How to Use ant to Export Postdeployment Changes of a Composite into a JAR
File ................................................................................................................... 43-50
43.7.6.8
How to Use ant to Import Postdeployment Changes of a Composite ............. 43-52
43.7.6.9
How to Use ant to Export Shared Data of a Given Pattern into a JAR File ...... 43-52
43.7.6.10
How to Use ant to Remove a Top-level Shared Data Folder ........................... 43-53
43.7.6.11
How to Use ant to Start a SOA Composite Application .................................. 43-54
43.7.6.12
How to Use ant to Stop a SOA Composite Application ................................... 43-54
43.7.6.13
How to Use ant to Activate a SOA Composite Application ............................ 43-55
43.7.6.14
How to Use ant to Retire a SOA Composite Application ................................ 43-56
43.7.6.15
How to Use ant to Assign the Default Version to a SOA Composite Application ....
43-56
43.7.6.16
How to Use ant to List the Deployed SOA Composite Applications ............... 43-57
43.7.6.17
How to Use ant to List All Available Partitions in the SOA Infrastructure ..... 43-57
43.7.6.18
How to Use ant to List All Composites in a Partition ...................................... 43-58
43.7.6.19
How to Use ant to Create a Partition in the SOA Infrastructure ...................... 43-58
43.7.6.20
How to Use ant to Delete a Partition in the SOA Infrastructure ...................... 43-59
43.7.6.21
How to Use ant to Start All Composites in the Partition ................................. 43-60
43.7.6.22
How to Use ant to Stop All Composites in the Partition ................................. 43-60
43.7.6.23
How to Use ant to Activate All Composites in the Partition ........................... 43-61
43.7.6.24
How to Use ant to Retire All Composites in the Partition ............................... 43-61
43.7.6.25
How to Use ant to Upgrade a SOA Composite Application ............................ 43-62
43.7.6.26
How to Use ant to Manage SOA Composite Applications .............................. 43-62
43.7.7
How to Deploy SOA Composite Applications from Oracle Enterprise Manager Fusion
Middleware Control .............................................................................................. 43-63
43.7.8
How to Deploy SOA Composite Applications to a Cluster ................................... 43-63
43.8
Postdeployment Configuration .................................................................................... 43-63
43.8.1
Security .................................................................................................................. 43-63
43.8.2
Updating Connections ........................................................................................... 43-63
43.8.3
Updating Data Sources and Queues ...................................................................... 43-63
43.8.4
Attaching Policies .................................................................................................. 43-64
43.9
Testing and Troubleshooting ........................................................................................ 43-64
43.9.1
Verifying Deployment ........................................................................................... 43-64
43.9.2
Initiating an Instance of a Deployed Composite .................................................... 43-64
43.9.3
Automating the Testing of Deployed Composites ................................................. 43-64
43.9.4
Recompiling a Project After Receiving a Deployment Error .................................. 43-64
43.9.5
Reducing Java Code Size to Resolve Java Compilation Errors ............................... 43-65
43.9.6
Troubleshooting Common Deployment Errors ..................................................... 43-66
43.9.6.1
Common Oracle JDeveloper Deployment Issues ............................................ 43-66
43.9.6.2
Common Configuration Plan Issues ................................................................ 43-68
43.7.5
43.7.6
43.7.6.1
43.7.6.2
43.7.6.3
xxxiii
43.9.6.3
43.9.6.4
43.9.6.5
43.9.6.6
43.9.6.7
43.9.6.8
44
xxxv
46.2.8
46.3
46.3.1
46.4
46.4.1
46.5
46.5.1
46.5.2
46.5.3
What You May Need to Know About Compiling and Deploying a Customized
Application .............................................................................................................. 46-7
Customizing the Vertical Application ............................................................................ 46-7
How to Customize the Vertical Application ............................................................ 46-7
Customizing the Customer Version ............................................................................. 46-10
How to Customize the Customer Version ............................................................. 46-10
Upgrading the Composite ............................................................................................ 46-11
How to Upgrade the Core Application Team Composite ...................................... 46-11
How to Upgrade the Vertical Application Team Composite ................................. 46-11
How to Upgrade the Customer Composite ........................................................... 46-12
xxxvi
47.6.1.3
47.6.1.4
47.6.1.5
47.6.1.6
47.6.1.7
47.6.1.8
47.6.2
48
xxxvii
49.8
Creating and Running the Cross Reference Use Case .................................................. 49-24
49.8.1
How to Create the Use Case .................................................................................. 49-25
49.8.1.1
Task 1: How to Configure the Oracle Database and Database Adapter .......... 49-25
49.8.1.2
Task 2: How to Create an Oracle JDeveloper Application and a Project ......... 49-26
49.8.1.3
Task 3: How to Create a Cross Reference ........................................................ 49-27
49.8.1.4
Task 4: How to Create a Database Adapter Service ........................................ 49-28
49.8.1.5
Task 5: How to Create EBS and SBL External References ................................ 49-30
49.8.1.6
Task 6: How to Create the Logger File Adapter External Reference ............... 49-32
49.8.1.7
Task 7: How to Create an Oracle Mediator Service Component ..................... 49-33
49.8.1.8
Task 8: How to Specify Routing Rules for an Oracle Mediator Service Component
49-34
49.8.1.9
Task 9: How to Specify Routing Rules for the Common Oracle Mediator ...... 49-44
49.8.1.10
Task 10: How to Configure an Application Server Connection ....................... 49-55
49.8.1.11
Task 11: How to Deploy the Composite Application ...................................... 49-55
49.8.2
How to Run and Monitor the XrefCustApp Application ....................................... 49-55
49.9
Creating and Running Cross Reference for 1M Functions ........................................... 49-56
49.9.1
How to Create the Use Case .................................................................................. 49-56
49.9.1.1
Task 1: How to Configure the Oracle Database and Database Adapter .......... 49-56
49.9.1.2
Task 2: How to Create an Oracle JDeveloper Application and a Project ......... 49-57
49.9.1.3
Task 3: How to Create a Cross Reference ........................................................ 49-58
49.9.1.4
Task 4: How to Create a Database Adapter Service ........................................ 49-59
49.9.1.5
Task 5: How to Create an EBS External Reference .......................................... 49-61
49.9.1.6
Task 6: How to Create a Logger File Adapter External Reference ................... 49-63
49.9.1.7
Task 7: How to Create an Oracle Mediator Service Component ..................... 49-64
49.9.1.8
Task 8: How to Specify Routing Rules for an Oracle Mediator Component ... 49-65
49.9.1.9
Task 9: How to Specify Routing Rules for the Common Oracle Mediator ...... 49-69
49.9.1.10
Task 10: How to Configure an Application Server Connection ....................... 49-74
49.9.1.11
Task 11: How to Deploy the Composite Application ...................................... 49-74
51.3
Creating the Dynamic Routing Decision Table .............................................................. 51-6
51.3.1
How to Create the Dynamic Routing Decision Table .............................................. 51-6
51.3.2
What Happens When You Create the Dynamic Routing Decision Table ................. 51-7
51.4
Use Case: Two-Layer BPM ............................................................................................. 51-7
51.4.1
Designing the SOA Composite ................................................................................ 51-8
51.4.2
Creating a Phase Activity ....................................................................................... 51-10
51.4.3
Creating and Editing the Dynamic Routing Decision Table .................................. 51-11
51.4.4
Adding Assign Activities to the BPEL Process Model ........................................... 51-12
51.4.5
Deploying and Testing the Sample ........................................................................ 51-14
Part X
53
xxxix
53.3.7
How to Add Existing Monitoring Objects to Activities ......................................... 53-13
53.3.8
How To Configure BPEL Process Monitors for Deployment ................................. 53-14
53.3.9
What You Need to Know About Using the Monitor Express Dashboard .............. 53-17
53.3.10
What You Need To Know About Monitor Express Data Objects .......................... 53-17
53.3.10.1
Understanding the COMPONENT Data Object .............................................. 53-18
53.3.10.2
Understanding the COUNTER Data Object .................................................... 53-19
53.3.10.3
Understanding the INTERVAL Data Object ................................................... 53-20
53.3.10.4
Understanding Business Indicator Data Objects ............................................. 53-22
53.3.10.5
Troubleshooting ............................................................................................. 53-23
53.4
Creating a Design Time Connection to an Oracle BAM Server .................................... 53-24
53.4.1
How to Create a Connection to an Oracle BAM Server ......................................... 53-24
53.5
Using Oracle BAM Adapter in a SOA Composite Application .................................... 53-25
53.5.1
How to Use Oracle BAM Adapter in a SOA Composite Application .................... 53-25
53.6
Using Oracle BAM Adapter in a BPEL Process ............................................................ 53-26
53.6.1
How to Use Oracle BAM Adapter in a BPEL Process ............................................ 53-26
53.7
Integrating BPEL Sensors Using Oracle BAM Sensor Action ....................................... 53-28
53.7.1
How to Create a Sensor ......................................................................................... 53-28
53.7.2
How to Create an Oracle BAM Sensor Action ....................................................... 53-29
53.8
Integrating SOA Applications and Oracle BAM Using Enterprise Message Resources 53-32
54
xl
54.6.1
How to Use an Oracle BAM Data Control in a JSF Page ........................................ 54-17
54.7
Deploying Applications With Oracle BAM Data Controls ........................................... 54-18
54.7.1
How to Deploy to Oracle WebLogic Server in Development Mode ...................... 54-18
54.7.2
How to Deploy to a Production Mode Oracle WebLogic Server ............................ 54-18
55
xli
xlii
What You May Need to Know About Integrating the Oracle Data Integrator (ODI) With
Oracle BAM .................................................................................................................... 57-1
Oracle BAM in an Application Server in 11g Release 1 (11.1.1.7.0) .......................... 57-2
Types of ODI Agents ............................................................................................... 57-2
Additional Installation Steps in Oracle BAM-ODI Integration in Release 11g ......... 57-2
Tips for Using Oracle Data Integrator with Oracle BAM ......................................... 57-2
Assumptions About Installing Oracle BAM-ODI integration .................................. 57-3
Installing the Oracle Data Integrator Integration Files ................................................... 57-3
How to Install Oracle BAM-ODI Integration Files Using the Script ........................ 57-4
What Happens When You Install Oracle BAM-ODI Integration Files Using the Script .
57-5
How to Manually Install Integration Files ............................................................... 57-6
Using the Logs ......................................................................................................... 57-9
Using Oracle BAM Knowledge Modules ....................................................................... 57-9
Creating the Oracle BAM Target .................................................................................. 57-15
How to Create the Oracle BAM Target .................................................................. 57-15
Reverse Engineering the Oracle BAM Schema ............................................................. 57-16
Updating the Oracle Data Integrator External Data Source Definition ........................ 57-17
How to Update the Oracle Data Integrator External Data Source Definitions ....... 57-17
Launching Oracle Data Integrator Scenarios From Oracle BAM Alerts ....................... 57-18
Running Oracle Data Integrator Agent as a Daemon or a Microsoft Windows Service With
Oracle BAM Embedded ............................................................................................... 57-19
Installation Files for Integrating Oracle BAM and Oracle Data Integrator ................... 57-19
58
xliii
61
Using ICommand
61.1
61.2
61.3
61.3.1
61.3.2
61.3.3
61.3.4
61.4
61.5
Part XI
62
63 Sending and Receiving Messages using the User Messaging Service EJB
API
63.1
Introduction to the UMS Java API .................................................................................. 63-1
63.1.1
Creating a Java EE Application Module .................................................................. 63-2
63.2
Creating a UMS Client Instance ..................................................................................... 63-2
63.2.1
Creating a MessagingEJBClient Instance Using a Programmatic or Declarative
Approach ................................................................................................................. 63-2
63.2.2
API Reference for Class MessagingClientFactory .................................................... 63-3
63.3
Sending a Message ......................................................................................................... 63-3
63.3.1
Creating a Message .................................................................................................. 63-3
63.3.1.1
Creating a Plaintext Message ............................................................................ 63-3
63.3.1.2
Creating a Multipart/Alternative Message (with Text/Plain and Text/HTML
Parts) ................................................................................................................. 63-3
63.3.1.3
Creating Delivery Channel-Specific Payloads in a Single Message for Recipients
with Different Delivery Types ........................................................................... 63-4
63.3.2
API Reference for Class MessageFactory ................................................................. 63-4
63.3.3
API Reference for Interface Message ....................................................................... 63-5
63.3.4
API Reference for Enum DeliveryType ................................................................... 63-5
63.3.5
Addressing a Message ............................................................................................. 63-5
63.3.5.1
Types of Addresses ........................................................................................... 63-5
63.3.5.2
Creating Address Objects .................................................................................. 63-5
63.3.5.3
Creating a Recipient with a Failover Address ................................................... 63-5
63.3.5.4
API Reference for Class AddressFactory ........................................................... 63-6
63.3.5.5
API Reference for Interface Address ................................................................. 63-6
63.3.6
Retrieving Message Status ....................................................................................... 63-6
63.3.6.1
Synchronous Retrieval of Message Status ......................................................... 63-6
63.3.6.2
Asynchronous Notification of Message Status .................................................. 63-6
63.4
Receiving a Message ...................................................................................................... 63-6
xliv
63.4.1
Registering an Access Point ..................................................................................... 63-6
63.4.2
Synchronous Receiving ............................................................................................ 63-7
63.4.3
Asynchronous Receiving ......................................................................................... 63-7
63.4.4
Message Filtering ..................................................................................................... 63-7
63.5
Using the UMS Enterprise JavaBeans Client API to Build a Client Application ............. 63-8
63.5.1
Overview of Development ....................................................................................... 63-9
63.5.2
Configuring the Email Driver .................................................................................. 63-9
63.5.3
Using JDeveloper 11g to Build the Application ....................................................... 63-9
63.5.3.1
Opening the Project ........................................................................................... 63-9
63.5.4
Deploying the Application ..................................................................................... 63-10
63.5.5
Testing the Application .......................................................................................... 63-11
63.6
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application .. 63-13
63.6.1
Overview of Development ..................................................................................... 63-14
63.6.2
Configuring the Email Driver ................................................................................ 63-14
63.6.3
Using JDeveloper 11g to Build the Application ..................................................... 63-14
63.6.3.1
Opening the Project ......................................................................................... 63-15
63.6.4
Deploying the Application ..................................................................................... 63-17
63.6.5
Testing the Application .......................................................................................... 63-18
63.7
Creating a New Application Server Connection .......................................................... 63-20
64 Sending and Receiving Messages using the User Messaging Service Java
API
64.1
Introduction to the UMS Java API .................................................................................. 64-2
64.2
Creating a UMS Client Instance and Specifying Runtime Parameters ........................... 64-2
64.2.1
API Reference for Class MessagingClientFactory .................................................... 64-3
64.3
Sending a Message ......................................................................................................... 64-3
64.3.1
Creating a Message .................................................................................................. 64-4
64.3.1.1
Creating a Plaintext Message ............................................................................. 64-4
64.3.1.2
Creating a Multipart/Alternative Message (with Text/Plain and Text/HTML
Parts) ................................................................................................................. 64-4
64.3.1.3
Creating Delivery Channel-Specific Payloads in a Single Message for Recipients
with Different Delivery Types ........................................................................... 64-4
64.3.2
API Reference for Class MessagingFactory .............................................................. 64-5
64.3.3
API Reference for Interface Message ........................................................................ 64-5
64.3.4
API Reference for Enum DeliveryType .................................................................... 64-5
64.3.5
Addressing a Message ............................................................................................. 64-6
64.3.5.1
Types of Addresses ........................................................................................... 64-6
64.3.5.2
Creating Address Objects .................................................................................. 64-6
64.3.5.3
Creating a Recipient with a Failover Address ................................................... 64-6
64.3.5.4
API Reference for Class MessagingFactory ....................................................... 64-6
64.3.5.5
API Reference for Interface Address ................................................................. 64-6
64.3.6
User Preference Based Messaging ........................................................................... 64-7
64.4
Retrieving Message Status .............................................................................................. 64-7
64.4.1
Synchronous Retrieval of Message Status ................................................................ 64-7
64.4.2
Asynchronous Receiving of Message Status ............................................................ 64-7
64.4.2.1
Creating a Listener Programmatically ............................................................... 64-7
64.4.2.2
Default Status Listener ...................................................................................... 64-8
xlv
64.4.2.3
Per Message Status Listener .............................................................................. 64-8
64.5
Receiving a Message ...................................................................................................... 64-8
64.5.1
Registering an Access Point ..................................................................................... 64-8
64.5.2
Synchronous Receiving ............................................................................................ 64-9
64.5.3
Asynchronous Receiving ......................................................................................... 64-9
64.5.3.1
Creating a Listener Programmatically ............................................................. 64-10
64.5.3.2
Default Message Listener ................................................................................ 64-10
64.5.3.3
Per Access Point Message Listener .................................................................. 64-10
64.5.4
Message Filtering ................................................................................................... 64-11
64.6
Configuring for a Cluster Environment ....................................................................... 64-11
64.7
Configuring Security .................................................................................................... 64-11
64.8
Threading Model .......................................................................................................... 64-12
64.8.1
Listener Threading ................................................................................................. 64-12
64.9
Using the UMS Client API to Build a Client Application ............................................. 64-13
64.9.1
Overview of Development ..................................................................................... 64-13
64.9.2
Configuring the Email Driver ................................................................................ 64-14
64.9.3
Using JDeveloper 11g to Build the Application ..................................................... 64-14
64.9.3.1
Opening the Project ......................................................................................... 64-14
64.9.4
Deploying the Application .................................................................................... 64-15
64.9.5
Testing the Application ......................................................................................... 64-16
64.10 Using the UMS Client API to Build a Client Echo Application .................................... 64-18
64.10.1
Overview of Development ..................................................................................... 64-19
64.10.2
Configuring the Email Driver ................................................................................ 64-19
64.10.3
Using JDeveloper 11g to Build the Application ..................................................... 64-20
64.10.3.1
Opening the Project ......................................................................................... 64-20
64.10.4
Deploying the Application .................................................................................... 64-22
64.10.5
Testing the Application ......................................................................................... 64-23
64.11 Creating a New Application Server Connection .......................................................... 64-24
65 Sending and Receiving Messages using the User Messaging Service Web
Service API
65.1
Introduction to the UMS Web Service API ..................................................................... 65-1
65.2
Creating a UMS Client Instance and Specifying Runtime Parameters ........................... 65-2
65.3
Sending a Message ......................................................................................................... 65-3
65.3.1
Creating a Message .................................................................................................. 65-4
65.3.1.1
Creating a Plaintext Message ............................................................................ 65-4
65.3.1.2
Creating a Multipart/Mixed Message (with Text and Binary Parts) ................. 65-4
65.3.1.3
Creating a Multipart/Alternative Message (with Text/Plain and Text/HTML
Parts) ................................................................................................................. 65-4
65.3.1.4
Creating Delivery Channel-Specific Payloads in a Single Message for Recipients
with Different Delivery Types ........................................................................... 65-5
65.3.2
API Reference for Interface Message ....................................................................... 65-6
65.3.3
API Reference for Enum DeliveryType ................................................................... 65-6
65.3.4
Addressing a Message ............................................................................................. 65-6
65.3.4.1
Types of Addresses ........................................................................................... 65-6
65.3.4.2
Creating Address Objects .................................................................................. 65-6
65.3.4.3
Creating a Recipient with a Failover Address ................................................... 65-7
xlvi
65.3.4.4
Recipient Types ................................................................................................. 65-7
65.3.4.5
API Reference for Class MessagingFactory ....................................................... 65-7
65.3.4.6
API Reference for Interface Address ................................................................. 65-7
65.3.5
User Preference Based Messaging ........................................................................... 65-7
65.4
Retrieving Message Status .............................................................................................. 65-8
65.4.1
Synchronous Retrieval of Message Status ................................................................ 65-8
65.4.2
Asynchronous Receiving of Message Status ............................................................ 65-8
65.4.2.1
Creating a Listener Programmatically ............................................................... 65-8
65.4.2.2
Publish the Callback Service .............................................................................. 65-9
65.4.2.3
Stop a Dynamically Published Endpoint ........................................................... 65-9
65.4.2.4
Registration ....................................................................................................... 65-9
65.5
Receiving a Message ....................................................................................................... 65-9
65.5.1
Registering an Access Point ................................................................................... 65-10
65.5.2
Synchronous Receiving .......................................................................................... 65-10
65.5.3
Asynchronous Receiving ....................................................................................... 65-11
65.5.3.1
Creating a Listener Programmatically ............................................................. 65-11
65.5.3.2
Default Message Listener ................................................................................ 65-11
65.5.3.3
Per Access Point Message Listener .................................................................. 65-12
65.5.4
Message Filtering ................................................................................................... 65-12
65.6
Configuring for a Cluster Environment ....................................................................... 65-12
65.7
Configuring Security .................................................................................................... 65-13
65.7.1
Client and Server Security ..................................................................................... 65-13
65.7.2
Listener/Callback Security .................................................................................... 65-13
65.8
Threading Model .......................................................................................................... 65-14
65.9
Sample Chat Application with Web Services APIs ...................................................... 65-14
65.9.1
Overview ............................................................................................................... 65-14
65.9.1.1
Provided Files .................................................................................................. 65-14
65.9.2
Running the Pre-Built Sample ................................................................................ 65-15
65.9.3
Testing the Sample ................................................................................................. 65-17
65.10 Creating a New Application Server Connection .......................................................... 65-20
66
xlvii
66.6.1.1
66.6.2
66.6.3
66.6.4
67
Part XII
A
Appendices
xlviii
A.2.8
Create Entity Activity ..............................................................................................A-14
A.2.9
Dehydrate Activity ..................................................................................................A-14
A.2.10
Email Activity ..........................................................................................................A-15
A.2.11
Empty Activity .........................................................................................................A-16
A.2.12
Exit Activity .............................................................................................................A-17
A.2.13
Flow Activity ...........................................................................................................A-17
A.2.14
FlowN Activity ........................................................................................................A-18
A.2.15
forEach Activity .......................................................................................................A-19
A.2.16
If Activity .................................................................................................................A-20
A.2.17
IM Activity ...............................................................................................................A-21
A.2.18
Invoke Activity ........................................................................................................A-21
A.2.19
Java Embedding Activity .........................................................................................A-22
A.2.20
Partner Link Activity ...............................................................................................A-23
A.2.21
Phase Activity ..........................................................................................................A-24
A.2.22
Pick Activity .............................................................................................................A-25
A.2.23
Receive Activity .......................................................................................................A-27
A.2.24
Receive Signal Activity ............................................................................................A-28
A.2.25
Remove Entity Activity ............................................................................................A-29
A.2.26
RepeatUntil Activity ................................................................................................A-29
A.2.27
Replay Activity ........................................................................................................A-30
A.2.28
Reply Activity ..........................................................................................................A-31
A.2.29
Rethrow Activity ......................................................................................................A-31
A.2.30
Scope Activity ..........................................................................................................A-32
A.2.31
Sequence Activity ....................................................................................................A-33
A.2.32
Signal Activity .........................................................................................................A-34
A.2.33
SMS Activity ............................................................................................................A-35
A.2.34
Switch Activity .........................................................................................................A-35
A.2.35
Terminate Activity ...................................................................................................A-36
A.2.36
Throw Activity .........................................................................................................A-37
A.2.37
Transform Activity ...................................................................................................A-37
A.2.38
User Notification Activity ........................................................................................A-38
A.2.39
Validate Activity ......................................................................................................A-39
A.2.40
Voice Activity ..........................................................................................................A-40
A.2.41
Wait Activity ............................................................................................................A-40
A.2.42
While Activity ..........................................................................................................A-41
A.3
Introduction to BPEL Services ........................................................................................A-42
A.4
Publishing and Browsing the Oracle Service Registry ....................................................A-43
A.4.1
How to Publish a Business Service ..........................................................................A-43
A.4.2
How to Create a Connection to the Registry ............................................................A-44
A.4.3
How to Configure a SOA Project to Invoke a Service from the Registry .................A-44
A.4.3.1
Dynamically Resolving the SOAP Endpoint Location ......................................A-46
A.4.3.2
Dynamically Resolving the WSDL Endpoint Location ......................................A-47
A.4.3.3
Resolving Endpoints .........................................................................................A-47
A.4.4
How To Configure the Inquiry URL, UDDI Service Key, and Endpoint Address for
Runtime ...................................................................................................................A-49
A.4.4.1
Changing Endpoint Locations in the Registry Control ......................................A-50
A.4.4.2
Publishing WSDLs from Multiple SOA Partitions .............................................A-52
xlix
A.4.5
A.5
A.6
B.2.4
B.2.5
B.2.6
B.2.7
B.2.8
B.2.9
B.2.10
B.2.11
B.2.12
B.2.13
B.2.14
B.2.15
B.2.16
B.2.17
B.2.18
B.2.19
B.2.20
B.2.21
B.2.22
B.2.23
B.2.24
B.2.25
B.2.26
B.2.27
B.2.28
B.2.29
B.2.30
B.2.31
B.2.32
B.2.33
B.2.34
B.2.35
B.2.36
B.2.37
B.2.38
B.2.39
B.2.40
B.2.41
B.2.42
B.2.43
B.2.44
B.2.45
B.2.46
B.2.47
B.2.48
B.2.49
B.2.50
copyList ...................................................................................................................B-18
countNodes ..............................................................................................................B-18
doc ...........................................................................................................................B-19
doStreamingTranslate ..............................................................................................B-19
doTranslateFromNative ...........................................................................................B-19
doTranslateToNative ...............................................................................................B-20
doXSLTransform ......................................................................................................B-21
doXSLTransformForDoc ..........................................................................................B-21
formatDate ...............................................................................................................B-22
generateGUID ..........................................................................................................B-22
getApplicationName ................................................................................................B-23
getAttachmentContent .............................................................................................B-23
getComponentName ................................................................................................B-23
getComponentInstanceID ........................................................................................B-24
getCompositeName .................................................................................................B-24
getCompositeInstanceID ..........................................................................................B-24
getCompositeURL ....................................................................................................B-24
getContentAsString ..................................................................................................B-25
getConversationId ...................................................................................................B-25
getCreator ................................................................................................................B-25
getCurrentDate ........................................................................................................B-25
getCurrentDateTime ................................................................................................B-26
getCurrentTime ........................................................................................................B-26
getECID ...................................................................................................................B-26
getElement ...............................................................................................................B-27
getFaultAsString ......................................................................................................B-27
getFaultName ..........................................................................................................B-27
getGroupIdsFromGroupAlias ..................................................................................B-28
getInstanceId ............................................................................................................B-28
getNodeValue ..........................................................................................................B-28
getNodes ..................................................................................................................B-28
getOwnerDocument ................................................................................................B-29
getParentComponentInstanceID ..............................................................................B-29
getPreference ...........................................................................................................B-29
getProcessId .............................................................................................................B-30
getProcessOwnerId ..................................................................................................B-30
getProcessURL .........................................................................................................B-30
getProcessVersion ....................................................................................................B-30
getUserAliasId .........................................................................................................B-31
getUserIdsFromGroupAlias .....................................................................................B-31
setCompositeInstanceTitle .......................................................................................B-31
instanceOf ................................................................................................................B-31
integer ......................................................................................................................B-32
listUsers ...................................................................................................................B-32
lookupUser ..............................................................................................................B-33
parseEscapedXML ...................................................................................................B-33
parseXML .................................................................................................................B-34
li
B.2.51
processXQuery ........................................................................................................B-34
B.2.52
processXSLT ............................................................................................................B-34
B.2.53
readBinaryFromFile .................................................................................................B-38
B.2.54
readFile ....................................................................................................................B-38
B.2.55
search .......................................................................................................................B-39
B.2.56
writeBinaryToFile ....................................................................................................B-40
B.2.57
BPEL Extension Functions in BPEL 1.1 and BPEL 2.0 ..............................................B-41
B.2.57.1
getLinkStatus ....................................................................................................B-41
B.2.57.2
getVariableData .................................................................................................B-41
B.2.57.3
getVariableProperty (For BPEL 1.1) ..................................................................B-42
B.2.57.4
getVariableProperty (For BPEL 2.0) ..................................................................B-42
B.2.58
Utility Functions ......................................................................................................B-43
B.2.58.1
batchProcessActive ............................................................................................B-43
B.2.58.2
batchProcessCompleted ....................................................................................B-43
B.2.58.3
format ................................................................................................................B-43
B.2.58.4
genEmptyElem ..................................................................................................B-44
B.2.58.5
getChildElement ...............................................................................................B-44
B.2.58.6
getMessage ........................................................................................................B-45
B.2.58.7
max-value-among-nodeset ................................................................................B-45
B.2.58.8
min-value-among-nodeset ................................................................................B-45
B.2.58.9
square-root ........................................................................................................B-46
B.3
Oracle Mediator XPath Extension Functions ..................................................................B-46
B.3.1
doStreamingTranslate ..............................................................................................B-46
B.3.2
doTranslateFromNative ...........................................................................................B-47
B.3.3
doTranslateToNative ...............................................................................................B-47
B.3.4
getAttachmentContent ............................................................................................B-48
B.3.5
getComponentInstanceID ........................................................................................B-49
B.3.6
getComponentName ...............................................................................................B-49
B.3.7
getCompositeInstanceID ..........................................................................................B-49
B.3.8
getCompositeName .................................................................................................B-49
B.3.9
getHeader ................................................................................................................B-50
B.3.10
getECID ...................................................................................................................B-50
B.3.11
getParentComponentInstanceID ..............................................................................B-51
B.3.12
readBinaryFromFile .................................................................................................B-51
B.3.13
setCompositeInstanceTitle .......................................................................................B-51
B.4
Advanced Functions ......................................................................................................B-51
B.4.1
create-nodeset-from-delimited-string ......................................................................B-51
B.4.2
generate-guid ...........................................................................................................B-52
B.4.3
lookupPopulatedColumns .......................................................................................B-52
B.4.4
lookupValue ............................................................................................................B-53
B.4.5
lookupValue1M .......................................................................................................B-53
B.4.6
lookupXRef ..............................................................................................................B-54
B.4.7
lookupXRef1M .........................................................................................................B-54
B.4.8
lookup-xml ..............................................................................................................B-55
B.4.9
markForDelete .........................................................................................................B-55
B.4.10
populateXRefRow ....................................................................................................B-56
B.4.11
populateXRefRow1M ..............................................................................................B-56
lii
B.5
Workflow Service Functions ...........................................................................................B-57
B.5.1
clearTaskAssignees ..................................................................................................B-57
B.5.2
createWordMLDocument ........................................................................................B-57
B.5.3
getNotificationProperty ...........................................................................................B-57
B.5.4
getNumberOfTaskApprovals ..................................................................................B-58
B.5.5
getPreviousTaskApprover .......................................................................................B-58
B.5.6
getTaskAttachmentByIndex .....................................................................................B-58
B.5.7
getTaskAttachmentByName ....................................................................................B-59
B.5.8
getTaskAttachmentContents ....................................................................................B-59
B.5.9
getTaskAttachmentsCount ......................................................................................B-59
B.5.10
getTaskResourceBundleString .................................................................................B-60
B.5.11
wfDynamicGroupAssign .........................................................................................B-60
B.5.12
wfDynamicUserAssign ............................................................................................B-61
B.5.13
Identity Service Functions ........................................................................................B-61
B.5.13.1
getDefaultRealmName ......................................................................................B-62
B.5.13.2
getGroupProperty .............................................................................................B-62
B.5.13.3
getManager ........................................................................................................B-62
B.5.13.4
getReportees ......................................................................................................B-63
B.5.13.5
getSupportedRealmNames ................................................................................B-63
B.5.13.6
getUserProperty ................................................................................................B-63
B.5.13.7
getUserRoles ......................................................................................................B-64
B.5.13.8
getusersinapprole ..............................................................................................B-64
B.5.13.9
getUsersInGroup ...............................................................................................B-64
B.5.13.10
isUserInRole ......................................................................................................B-65
B.5.13.11
lookupGroup .....................................................................................................B-65
B.5.13.12
lookupUser ........................................................................................................B-65
B.6
Building XPath Expressions in the Expression Builder in Oracle JDeveloper ................B-66
B.6.1
How to Use the Expression Builder .........................................................................B-66
B.6.2
Introduction to the XPath Building Assistant ..........................................................B-67
B.6.3
How to Use the XPath Building Assistant ................................................................B-68
B.6.4
Using the XPath Building Assistant in the XSLT Mapper ........................................B-69
B.6.5
Function Parameter Tool Tips ..................................................................................B-70
B.6.6
Syntactic and Semantic Validation ...........................................................................B-71
B.6.7
Creating Expressions with Free Form Text and XPath Expressions .........................B-71
B.6.8
Using Double Slashes for Directory Paths in XPath Functions on Windows Can Cause
Errors .......................................................................................................................B-72
B.7
Creating User-Defined XPath Extension Functions ........................................................B-73
B.7.1
How to Implement User-Defined XPath Extension Functions .................................B-75
B.7.1.1
How to Implement Functions for the XSLT Mapper .........................................B-75
B.7.1.2
How to Implement Functions for All Other Components .................................B-76
B.7.2
How to Configure User-Defined XPath Extension Functions ..................................B-76
B.7.3
How to Deploy User-Defined Functions to Runtime ...............................................B-79
liii
C.2
liv
DataObjectOperations10131 .............................................................................................E-1
Batch ..........................................................................................................................E-1
Request Message .................................................................................................E-1
Delete .........................................................................................................................E-2
Request Message .................................................................................................E-2
Insert ..........................................................................................................................E-2
Request Message .................................................................................................E-2
Update .......................................................................................................................E-3
Request Message .................................................................................................E-3
Upsert ........................................................................................................................E-3
Request Message .................................................................................................E-3
DataObjectOperationsByName ........................................................................................E-4
Delete .........................................................................................................................E-4
Request Message .................................................................................................E-4
Get .............................................................................................................................E-4
Request Message .................................................................................................E-4
Insert ..........................................................................................................................E-5
Request Message .................................................................................................E-5
Update .......................................................................................................................E-5
Request Message .................................................................................................E-5
Upsert ........................................................................................................................E-5
Request Message .................................................................................................E-6
DataObjectOperationsByID ..............................................................................................E-6
Batch ..........................................................................................................................E-6
Request Message .................................................................................................E-6
Delete .........................................................................................................................E-7
Request Message .................................................................................................E-7
Insert ..........................................................................................................................E-7
Request Message .................................................................................................E-7
Update .......................................................................................................................E-8
Request Message .................................................................................................E-8
Upsert ........................................................................................................................E-8
Request Message .................................................................................................E-8
DataObjectDefinition Operations .....................................................................................E-9
E.4.1
Create .........................................................................................................................E-9
E.4.1.1
Request Message .................................................................................................E-9
E.4.1.2
Response Message .............................................................................................E-11
E.4.2
Delete .......................................................................................................................E-11
E.4.2.1
Request Message ...............................................................................................E-11
E.4.2.2
Response Message .............................................................................................E-11
E.4.3
Get ...........................................................................................................................E-11
E.4.3.1
Request Message ...............................................................................................E-11
E.4.3.2
Response Message .............................................................................................E-11
E.4.4
Update .....................................................................................................................E-12
E.4.4.1
Request Message ...............................................................................................E-12
E.4.4.2
Response Message .............................................................................................E-12
E.5
ManualRuleFire Operations ...........................................................................................E-12
E.5.1
FireRuleByName ......................................................................................................E-13
E.5.1.1
Request Message ...............................................................................................E-13
E.5.1.2
Response Message .............................................................................................E-13
Events ...............................................................................................................................F-1
In a specific amount of time .......................................................................................F-1
At a specific time today ..............................................................................................F-2
On a certain day at a specific time .............................................................................F-2
Every interval between two times ..............................................................................F-2
Every date interval starting on certain date at a specific time ....................................F-2
When a report changes ..............................................................................................F-2
When a data field changes in data object ...................................................................F-3
When a data field in a report meets specified conditions ...........................................F-3
When a data field in a data object meets specified conditions ...................................F-4
When this rule is launched .........................................................................................F-5
Conditions ........................................................................................................................F-5
If it is between two times ...........................................................................................F-5
If It is between two days ............................................................................................F-5
If it is a particular day of the week .............................................................................F-5
Actions .............................................................................................................................F-5
Send a report via email ..............................................................................................F-6
Send a message via email ...........................................................................................F-6
Send a report via email and escalate to another user after a specific amount of time F-6
Send a parameterized message ..................................................................................F-6
Send a parameterized message for every matching row in a data object .................F-10
Launch a rule ...........................................................................................................F-11
Launch rule if an action fails ....................................................................................F-11
Delete rows from a Data Object ...............................................................................F-11
Call a Web Service ...................................................................................................F-11
How to Use Call a Web Service: An Example ....................................................F-13
Run an Oracle Data Integrator Scenario ...................................................................F-14
Call an External Action ............................................................................................F-14
Frequency Constraint .....................................................................................................F-14
lv
J.3
Send Email with Attachments ....................................................................................... J-14
J.3.1
Overview of SendEmailWithAttachment Application ............................................. J-15
J.3.1.1
Provided Files .................................................................................................... J-15
J.3.2
Running the Pre-Built Sample .................................................................................. J-15
J.3.3
Testing the Sample ................................................................................................... J-16
J.3.3.1
Verifying the Execution ..................................................................................... J-17
J.3.4
Building the Sample ................................................................................................. J-17
J.3.4.1
Sending Text Content with base64 Encoding .................................................... J-26
Index
lvii
lviii
Preface
This manual describes how to use Oracle SOA Suite.
This preface contains the following topics:
Audience
Documentation Accessibility
Related Documents
Conventions
Audience
This manual is intended for anyone who is interested in developing applications with
Oracle SOA Suite.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For
information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are
hearing impaired.
Related Documents
For more information, see the following Oracle resources:
Oracle Fusion Middleware Healthcare Integration User's Guide for Oracle SOA Suite
Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring
Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules
lix
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite
Oracle Fusion Middleware Enterprise Deployment Guide for Oracle SOA Suite
Conventions
The following text conventions are used in this document:
lx
Convention
Meaning
boldface
italic
monospace
lxi
lxii
Sections
Changes Made
Section added to
describe how to move
and copy variables in the
Structure window.
Chapter 8 Invoking an
Asynchronous Web Service
from a BPEL Process
lxiii
Sections
Changes Made
Section added to
describe how a BPEL
process can consume
midprocess receive
activity messages even
after the expiration of a
configured timeout on
the receive activity, if the
exception resulting from
the timeout goes
unhandled.
Section added to
describe how to resolve
the routing of callback
messages to the correct
end point address when
multiple receive or pick
activities are associated
with the same partner
link.
Section added to
describe how you can
define idempotency at
the operation level of a
partner link.
X
Section added to
describe how to specify a
keystore recipient alias
value to override the
security certificate in the
WSDL file of the web
service.
X
Section added to
describe how to override
the default WSDL file
used by dynamic partner
links.
Section added to
describe how to add a
system fault to a
synchronous BPEL
process.
X
Section added to
describe what happens
when the idempotent
deployment descriptor
property is set to false
in the composite.xml
file and the invocation of
a partner link fails.
lxiv
Sections
Changes Made
Section added to
describe how to roll back
activities by specifying
the bpelx:rollback
extension in a throw
activity.
Table updated to
describe the behavior
when
onewayDeliveryPoli
cy is set to
async.cache in
environments in which
the main process
asynchronously calls the
subprocess.
Multiple sections
Various graphics
corrected.
Section added to
describe how to create
tokens in Oracle
JDeveloper for values in
the binding URLs of
external references. The
token values that you
assign are substituted in
place of the hardcoded
HTTP values.
Chapter 38 Integrating
Enterprise JavaBeans with
SOA Composite
Applications
Section 38.6.1, "How to
Configure Enterprise
JavaBeans Binding Support
in the Credential Store
Framework"
Section updated to
describe how all
Enterprise JavaBeans
bindings now support
using the Credential
Store Framework (CSF)
to store JNDI user access
credentials, and not just
service data object (SDO)
Enterprise JavaBeans
bindings.
lxv
Sections
Changes Made
Chapter 40 Creating
Transformations with the
XSLT Mapper
Section 40.3.16, "How to
Import a Customization File
to Specify Display
Preferences in the XSLT
Mapper"
X
Section added to
describe how to import a
customization file that
specifies display
preferences in the XSLT
Mapper.
Chapter updated to
describe how to define
composite sensors on
service components that
have subscribed to
business events.
Description of
X
-dependencies option
changed to describe how
to export dependent
reports.
Appendix H Normalized
Message Properties
lxvi
Sections
Changes Made
Section updated to
indicate that
WS-Addressing headers
from incoming SOAP
requests are propagated
within Oracle SOA Suite
through the normalized
message properties.
However, overriding of
WS-Addressing headers
in the outbound SOAP
message through use of
these normalized
message properties is not
supported.
lxvii
lxviii
Part I
Introduction to Oracle SOA Suite
This part provides an introduction to Oracle SOA Suite and developing SOA
composite applications.
This part contains the following chapters:
1
Introduction to Building Applications with
Oracle SOA Suite
This chapter describes service-oriented architecture (SOA) and Oracle SOA Suite,
standards used by Oracle SOA Suite to enable SOA, SOA composite application
architecture and runtime behavior, approaches to designing SOA composite
applications, and where to go to learn more about Oracle SOA Suite.
This chapter includes the following sections:
1-1
A standard interface and message structure define services. The most widely used
mechanism are web services standards. These standards include the Web Service
Description Language (WSDL) file for service interface definition and XML Schema
Documents (XSD) for message structure definition. These XML standards are easily
exchanged using standard protocols. Because standards for web services use a
standard document structure, they enable existing systems to interoperate regardless
of the choice of operating system and computer language used for service
implementation.
When designing a SOA approach, you create a service portfolio plan to identify
common functionality to use as a service within the business process. By creating and
maintaining a plan, you ensure that existing services and applications are reused or
repurposed whenever possible. This plan also reduces the time spent in creating
needed functionality for the application.
Messaging
Service discovery
Orchestration
Business rules
Events framework
1-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Specifies a standard data method and can modify business data regardless of how
it is physically accessed. Knowledge is not required about how to access a
particular back-end data source to use SDO in a SOA composite application.
Consequently, you can use static or dynamic programming styles and obtain
connected and disconnected access.
WSDL file
Provides the entry points into a SOA composite application. The WSDL file
provides a standard contract language and is central for understanding the
capabilities of a service.
SCA provides a model for assembling distributed groups of service components into
an application, enabling you to describe the details of a service and how services and
service components interact. Composites are used to group service components and
wires are used to connect service components. SCA helps to remove middleware
concerns from the programming code by applying infrastructure declaratively to
composites, including security and transactions.
The key benefits of SCA include the following:
Loose coupling
1-3
Flexibility
Service components can easily be replaced by other service components.
Services invocation
Services can be invoked either synchronously or asynchronously.
Productivity
Service components are easily integrated to create a SOA composite application.
Wire
Wire
Composite BigBank
Service Component
Account
binding.ws
WebApp
binding.rmi
binding.ws
BPEL
Service Component
AccountRule
Service Component
Business Rules
1-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Spring enables you to integrate Java interfaces into SOA composite applications.
For more information about service components, see Section 2.2, "Adding Service
Components."
Services provide the outside world with an entry point to the SOA composite
application. The WSDL file of the service advertises its capabilities to external
applications. These capabilities are used for contacting the SOA composite
application components. The binding connectivity of the service describes the
protocols that can communicate with the service, for example, SOAP/HTTP or a
JCA adapter.
References enable messages to be sent from the SOA composite application to
external services in the outside world.
Table 11 lists and describes the binding components provided by Oracle SOA Suite.
Table 11
Binding Components
Description
Web service (SOAP over HTTP) Use for connecting to standards-based services using SOAP
over HTTP.
JCA adapters
Oracle B2B
Oracle Healthcare
ADF-BC service
Oracle Applications
1-5
Description
BAM adapter
EJB service
HTTP binding
For more information about binding components, see Section 2.3, "Adding Service
Binding Components" and Section 2.4, "Adding Reference Binding Components."
1.5.3 Wires
Wires enable you to graphically connect the following components in a single SOA
composite application for message communication:
For more information about wires, see Section 2.5, "Adding Wires."
1-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
APR
Rule
Manager
Review
Task
BPEL
Process
Manager
Business
Rules
Oracle
Mediator
EBS
Customer
View
Human
Task
Service Engines
(Containers that host the
component business logic)
UDDI
Service Infrastructure
(Picks up SOAP message
from binding component
and determines the
intended component
target)
MDS
BAM
B2B
HTTP
SOAP
.NET
Payment
Calculator
SDO
ADF/BC
JCA
Adapter
Binding Components
(Connect SOA applications
to the outside world)
The .NET payment calculator is an external application that sends a SOAP message to
the SOA application to initiate contact. The Service Infrastructure picks up the SOAP
message from the binding component and determines the intended component target.
The BPEL process service engine receives the message from the Service Infrastructure
for processing by the BPEL Loan Process application and posts the message back to the
Service Infrastructure after completing the processing.
Table 12 describes the operability of the SOA composite application shown in
Figure 11.
1-7
Table 12
Part
Description
Binding
components
Service binding
.NET application.
components provide an
entry point to the SOA
See Section
Section 1.5.1,
"Service
Components"
Service engines
(containers
hosting service
components)
Section 1.6.2,
"Service Engines"
Universal
Description,
Discovery, and
Integration
(UDDI) and
MDS
SOA archive
composite
(deployment
unit)
Section 1.6.1,
"Service
Infrastructure"
Oracle Fusion
Middleware
Getting Started
with Oracle SOA
Suite
Section 1.6.3,
"Deployed
Service
Archives"
Receives messages from the service providers or external partners through SOAP
services or adapters
Sends the message to the appropriate service engine
Receives the message back from the service engine and sends it to any additional
service engines in the composite or to a reference binding component based on the
wiring
1-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Top-Down: You analyze your business processes and identify activities in support
of your process. When creating a composite, you define all the SOA components
through the SOA Composite Editor. You create all the services first, and then build
the BPEL process, referencing the created services.
Bottom-Up: You analyze existing applications and assets to identify those that can
be used as services. As you create a BPEL process, you build the services on an
as-needed basis. This approach works well when IT must react to a change.
Getting Started: Oracle Fusion Middleware Getting Started with Oracle SOA Suite
introduces you to Oracle SOA Suite and its components, and provides you with a
high-level understanding of what you can accomplish with the suite. Also, you
can refer to the Oracle SOA Suite section of the Oracle Fusion Middleware 11g
Release 1 documentation library for additional documentation.
Oracle SOA Suite samples provide access to various use case samples for Oracle
SOA Suite and its components.
Cue Cards in Oracle JDeveloper: Oracle JDeveloper cue cards provide step-by-step
support for the application development process using Oracle SOA Suite. They are
designed to be used either with the included examples and a sample schema, or
with your own data. Cue cards also include topics that provide more detailed
background information, and viewlets that demonstrate how to complete the steps
1-9
Accessibility Options
in the card. Cue cards provide a fast, easy way to become familiar with the basic
features of Oracle SOA Suite, and to work through a simple end-to-end task. In
Oracle JDeveloper, click Help > Cue Cards to access the cue cards.
While this guide primarily describes how to use Oracle SOA
Suite with Oracle WebLogic Server, most of the information is also
applicable to using Oracle SOA Suite with other third-party
application servers. However, there may be some differences with
using third-party application servers.
Note:
2.
For more information about Oracle SOA Composer, see Chapter 48, "Using Oracle
SOA Composer with Domain Value Maps."
On the Accessibility tab, shown in Figure 14, select the desired option.
1-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Accessibility Options
3.
Click OK.
For more information about Oracle BPM Worklist, see Section 32, "Using Oracle BPM
Worklist."
1-11
Accessibility Options
1-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2
Developing SOA Composite Applications
with Oracle SOA Suite
This chapter describes how to use Oracle JDeveloper to create a SOA composite
application. It guides you through the basic steps of composite, service and reference
binding component, and service component creation, security, deployment, and
testing, along with describing key issues to be aware of when designing a SOA
composite application.
This chapter includes the following sections:
Note:
2-1
2.
If Oracle JDeveloper is running for the first time, specify the location for the Java
JDK.
3.
Table 21
If Oracle JDeveloper...
Then...
Has no applications
2.
3.
In the Name your application page, you can optionally change the name and
location for your web project. If this is your first application, from Application
Template, select SOA Application. Accept the defaults for the package prefix, and
click Next.
Notes:
5.
In the Name your project page, you can optionally change the name and location
for your SOA project. By default, Oracle JDeveloper adds the SOA project
technology, the composite.xml file that describes the SOA composite application,
and the necessary libraries to your model project.
6.
Click Next.
2-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
A project deployed to the same infrastructure must have a unique name across
SOA composite applications. The uniqueness of a composite is determined by its
project name. For example, do not perform the actions described in Table 22.
During deployment, the second deployed project (composite) overwrites the first
deployed project (composite).
Table 22
Application1
Project1
Application2
Project1
The Project SOA Settings page of the Create SOA Application wizard appears.
7.
In the Configure SOA Settings page, click Empty Composite, and click Finish.
8.
2.1.2 What Happens When You Create a SOA Application and Project
When you create a SOA application, Oracle JDeveloper creates a project that contains
all the source files related to your application. Oracle JDeveloper automatically adds
the following libraries needed for your SOA project:
SOA runtime
BPEL runtime
You can then use Oracle JDeveloper to create additional projects needed for your
application.
Figure 21 shows the SOA Composite Editor for the OrderBookingComposite project
contained within the WebLogicFusionOrderDemo application of the Fusion Order
Demo.
2-3
Element
Description
Application Navigator
Displays the key files for the specific service components included
in the SOA project:
Structure Window
2-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Designer
Project Name
Component Palette
The component palette provides the various resources that you can
use in a SOA composite. It contains the following service
components and adapters:
Service components
Displays the BPEL process, business rule, human task, Oracle
Mediator, and spring components that can be dragged and
dropped into the designer.
Service adapters
Displays the JCA adapter (AQ, file, FTP, database, JMS, MQ,
Oracle Applications, Oracle User Messaging Service, socket,
and third party), Oracle BAM binding component, Oracle
Healthcare binding component, Oracle B2B binding
component, EJB binding component, ADF-BC binding
component, direct binding component, HTTP binding
component, and web service binding component that can be
dragged into the left or right swimlane.
2-5
Description
Resource Palette
The Resource Palette provides a single dialog from which you can
browse both local and remote resources. For example, you can
access the following resources:
Property Inspector
Application View
The Application View shows the artifacts for the SOA composite
application.
The composite_name (composite.xml) file displays as a tab in the designer and as a file
in the Application Navigator. This file is automatically created when you create a new
SOA project. This file describes the entire composite assembly of services, service
components, and references. There is one composite.xml file for each SOA project.
When you work with the composite.xml file, you mostly use the designer, the
Structure window, and the Property Inspector, as shown in Figure 21. The designer
enables you to view many of your files in a WYSIWYG environment, or you can view
a file in an overview editor where you can declaratively make changes, or you can
view the source code for the file. The Structure window shows the structure of the
currently selected file. You can select objects in this window, and then edit the
properties for the selection in the Property Inspector.
2-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
From the Service Components list, drag a component into the designer.
Figure 22 shows a BPEL process being added to the designer.
Invokes The...
BPEL Process
Business Rule
Human Task
Mediator
Spring Context
3.
Configure the settings for a service component. For help with a service component
dialog, click Help or press F1. Click Finish.
Figure 23 shows the BPEL Process dialog with data entered to create the
OrderProcessor BPEL process for the WebLogicFusionOrderDemo application of
the Fusion Order Demo. The process is selected to be asynchronous. The Expose
as a SOAP Service checkbox directs Oracle JDeveloper to automatically create this
service component connected to an inbound web service.
2-7
4.
Click OK.
The service component displays in the designer. Figure 24 shows the
OrderProcessor BPEL process. A SOAP service binding component called
orderprocessor_client_ep in the left swimlane provides the outside world with an
entry point into the SOA composite application. If the Expose as a SOAP Service
option was not selected in the Create BPEL Process dialog, the orderprocessor_
client_ep service would not display. Section 2.3.1, "How to Add a Service Binding
Component," describes how you can later add a service.
You can more fully define the content of the service component now or at a later
time. For this top-down example, the content is defined now.
5.
2-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.2.2 What You May Need to Know About Adding and Deleting a Service Component
Note the following details about adding service components:
Create a service component from either the SOA Composite Editor or the designer
of another component. For example, you can create a human task component from
the SOA Composite Editor or the Oracle BPEL Designer.
Use the Resource Palette to browse for service components defined in the SOA
Composite Editor, and those deployed.
You can delete a service component by right-clicking it and selecting Delete from
the context menu.
When a service component is deleted, all references pointing to it are invalidated
and all wires are removed. The service component is also removed from the
Application Navigator.
A service component created from within another service component can be
deleted. For example, a human task created within the BPEL process service
component of Oracle JDeveloper can be deleted from the SOA Composite Editor.
In addition, the partner link to the task can be deleted. Deleting the partner link
removes the reference interface from its .componentType file and removes the
wire to the task.
Double-Clicking This
Service Component...
Displays The...
BPEL Process
Business Rule
Human Task
Mediator
Spring Context
To return to the SOA Composite Editor from within any service component,
double-click composite_name (composite.xml) in the Application Navigator or
single-click composite_name (composite.xml) above the designer.
For help with a service component editor, click Help or press F1.
2.
Click Finish.
3.
Modify the settings for a service component. For help with a service component
editor or designer, click Help or press F1.
4.
Click Finish.
2-9
5.
6.
You can use the Component Palette from the SOA Composite Editor to drag and drop
service binding components to the composite.
To add a service binding component:
1. From the Component Palette, select SOA.
2.
From the Service Adapters list, drag a service to the left swimlane to define the
service interface.
Figure 25 shows a web service being added to the designer.
2-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A specific dialog for the selected service displays. Table 26 describes the available
editors.
Table 26
Service Editors
Adapters
ADF-BC Service
B2B
Healthcare
EJB Service
HTTP Binding
Direct Binding
3.
Configure the settings for the service. For help with a service editor, click Help or
press F1. When you add a web service, you must select the WSDL file to use. For
information, see Section 2.3.2, "How to Define the Interface (WSDL) for a Web
Service."
Developing SOA Composite Applications with Oracle SOA Suite 2-11
4.
Click Finish.
Figure 26 shows the Web Service dialog with data entered to create the
orderprocessor_client_ep service for the OrderProcessor BPEL process.
5.
Click OK.
The service binding component displays in the left swimlane. Figure 27 shows
the orderprocessor_client_ep service binding component added to the
composite.xml file.
6.
1.
2-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
From the Service Adapters list, drag a Web Service to the left swimlane.
This invokes the Create Web Service dialog shown in Figure 26.
3.
Table 27
Field
Value
Name
Type
Select the type (message direction) for the web service. Since you
dragged the web service to the left swimlane, the Service type is
the correct selection, and displays by default:
Service (default)
Creates a web service to provide an entry point to the SOA
composite application
Reference
Creates a web service to provide access to an external
service in the outside world
Select the WSDL file for the service. There are three methods for selection:
To the right of the WSDL URL field, click the Find existing WSDLs (first) icon
and select an existing WSDL file from the local file system (for this example,
OrderProcessor.wsdl is selected). File System in the list at the top of the
dialog is automatically selected. Figure 28 provides details.
Select a WSDL created when defining a component interface. The WSDL can be
selected from the project/application browser.
a.
To the right of the WSDL URL field, click the Find existing WSDLs (first) icon
and select Resource Palette from the list at the top of the dialog, as shown in
Figure 29. This action enables you to use existing WSDL files from other
applications.
To the right of the WSDL URL field, click the Generate WSDL from schemas
(second) icon to automatically generate a WSDL file from a schema.
Figure 210 shows the Create WSDL dialog. Default values for the WSDL file
name, directory location, namespace, port type, operation name, and interface
type are displayed. If the specified directory is not the subdirectory of the
current project, a warning message is displayed. If the specified directory does
not exist, it is automatically created.
You can modify the default values.
2-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
Click the Add icon above the Input table to display the Add Message Part dialog
to add a new WSDL message part. If the WSDL file contains multiple messages,
you can add a message part for each one. You can select XML schema simple
types, project schema files, and project WSDL files for a message part.
For more information, click Help.
6.
7.
Table 28
Field
Value
Port Type
8.
Click OK.
9.
Notes:
The Update Interface dialog shown in Figure 212 displays all schemas currently
used by the WSDL file.
Figure 212 Update Interface Dialog
2.
If you want to select a new message schema, click Help or press F1 for
instructions.
2-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
To...
Web service
Adapters
ADF-BC Service
B2B
Healthcare
EJB Service
HTTP Binding
Direct Binding
2.3.5 What You May Need to Know About Adding and Deleting Services
Note the following detail about adding services:
When a new service is added for a service component, the service component is
notified so that it can make appropriate metadata changes. For example, when a
new service is added to a BPEL service component, the BPEL service component is
notified to create a partner link that can be connected to a receive or an
on-message activity.
2.3.6 What You May Need to Know About Using the Same Namespace in Different
WSDL Files in the Same Composite
Having two different WSDL files with the same fully-qualified namespace in the same
SOA composite application is ambiguous and not supported. This causes the
application to fail during compilation with duplicate definition errors. Ensure that you
use unique namespaces for every WSDL file.
2.3.7 What You May Need to Know About WSDL Browsing in the Resource Palette
When the SOA Infrastructure Uses Both Internal and External Oracle HTTP Servers
When the SOA Infrastructure is configured in the Server URL field of the SOA
Infrastructure Common Properties page in Oracle Enterprise Manager Fusion
Middleware Control to use both internal and external Oracle HTTP servers, you
cannot browse for WSDL URLs using the Resource Palette. However, you can paste
the correct WSDL URL in the WSDL URL field of the Update Service dialog for the
web service binding component. Figure 213 provides details.
From the Service Adapters list, drag a service to the right swimlane.
Figure 214 shows a web service being added to the designer.
A specific dialog or wizard for the selected reference displays. Table 210 describes
the available editors.
2-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 210
Reference Editors
Invokes The...
Web Service
Adapters
ADF-BC Service
B2B
Healthcare
EJB Service
HTTP Binding
Direct Binding
3.
Configure the settings for the reference binding component. For help with a
reference editor, click Help or press F1.
4.
Click Finish.
Figure 215 shows the Create Web Service dialog with data entered to create a
reference.
5.
Click OK.
The reference binding component displays in the right swimlane. Figure 216
shows the StoreFrontService reference added to the SOA composite application.
6.
2.4.2 What You May Need to Know About Adding and Deleting References
Note the following detail about adding references:
The only way to add a new reference in the SOA Composite Editor is by wiring
the service component to the necessary target service component. When a new
reference is added, the service component is notified so it can make appropriate
changes to its metadata. For example, when a reference is added to a BPEL service
component, the BPEL service component is notified to add a partner link that can
then be used in an invoke activity.
When a reference for a service component is deleted, the associated wire is also
deleted and the service component is notified so that it can update its metadata.
For example, when a reference is deleted from a BPEL service component, the
service component is notified to delete the partner link in its BPEL metadata.
Deleting a reference connected to a wire clears the reference and the wire.
Adding Wires
services and references). There can also be other WSDL references required by runtime
(for example, a WSDL that imports another WSDL, such as the BPEL process WSDL).
Ensure that you change the following places in this file where a WSDL URL is
referenced:
Always modify the WSDL location though the dialogs of the SOA Composite Editor in
which a WSDL location is specified (for example, a web service, BPEL partner link,
and so on). Changing the URLs host address is the exact case in which the SOA
Composite Editor automatically updates all WSDL references.
2.4.4 What You May Need to Know About Mixed Message Types in a WSDL File
If a BPEL process has multiple WSDL messages declared in its WSDL file and one or
more messages have their parts defined to be of some type, whereas other messages
have their parts defined to be of some element, runtime behavior can become
unpredictable. This is because these WSDLs are considered to have mixed type
messages. For example, assume there are multiple copy actions within an assign
activity. These copy actions attempt to populate an output variable that has multiple
parts:
2.4.5 What You May Need to Know About Invoking the Default Revision of a Composite
A WSDL URL that does not contain a revision number is processed by the default
composite application. This action enables you to always call the default revision of
the called service without having to make other changes in the calling composite.
Select the default WSDL to use in the Resource Palette in Oracle JDeveloper.
To invoke the default revision of a composite:
1. In the Create Web Service dialog, click the icon to the right of the WSDL URL field
to invoke the SOA Resource Browser dialog.
2.
3.
Expand the nodes under the Application Server connection or WSIL connection
to list all deployed composites and revisions. The default revision is identified by
the word Default in the title (for example, OrderBookingComposite [Default]).
4.
Adding Wires
Since a web service is an inbound service, a reference handle displays on the right
side. Web services that are outbound references do not have a reference handle on
the right side.
You can drag a defined interface to an undefined interface in either direction
(reference to service or service to reference). The undefined interface then inherits
the defined interface. There are several exceptions to this rule:
A component has the right to reject a new interface. For example, an Oracle
Mediator can only have one inbound service. Therefore, it rejects attempts to
create a second service.
The port type and the namespace are used to uniquely identify an interface.
You cannot wire services and composites that have different interfaces. For
example, you cannot connect a web service configured with a synchronous WSDL
file to an asynchronous BPEL process. Figure 217 provides details.
Figure 217 Limitations on Wiring Services and Composites with Different Interfaces
The service and reference must match, meaning the interface and the callback
must be the same. If you have two services that have different interfaces, you can
place an Oracle Mediator between the two services and perform a transformation
between the interfaces.
2-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Adding Wires
2.
If the service component is a BPEL process, double-click the BPEL process and
note that the service displays as a partner link in the left swimlane, as shown in
Figure 219.
Figure 219 Display of the Service as a Partner Link in the BPEL Process
3.
From the service component, drag a wire to the reference, as shown in Figure 220.
3.
If the service component is a BPEL process, double-click the BPEL process and
note that the reference displays as a partner link in the right swimlane, as shown
in Figure 221.
Adding Wires
Figure 221 Display of the Reference as a Partner Link in the BPEL Process
4.
5.
6.
Adding Wires
erv
iceSoapHttpPort)"
location="oramds:/apps/FusionOrderDemoShared/services/oracle/fodemo/storefront/
sto
re/service/common/serviceinterface/StoreFrontService.wsdl"/>
</reference>
2.5.3 What You May Need to Know About Adding and Deleting Wires
Note the following details about adding wires:
Wire the first Oracle Mediator to the second Oracle Mediator component
service.
If you remove the wire between the two Oracle Mediators, then for every message,
the second Oracle Mediator can publish the event and the first Oracle Mediator
can subscribe to it.
Note the following details about deleting wires:
Adding Security
If you want to change the service WSDL interface, there are several workarounds:
In most cases, you just want to change the schema instead of the inbound
service definition. In the SOA Composite Editor, click any interface icon that
uses the WSDL. For example, you can click the web service interface icon or
the Oracle Mediator service icon. This invokes the Update Interface dialog,
which enables you to change the schema for any WSDL message.
If you are using a BPEL process service component, select a new WSDL
through the Edit Partner Link dialog.
See Section 2.3.3, "How to View Schemas" for details about the Update Interface
dialog.
2.
a.
In the SOA Composite Editor, drag a Web Service from the Component
Palette to the External References swimlane.
b.
In Oracle BPEL Designer, drag a Partner Link from the Component Palette to
the right swimlane.
Access the SOA Resource Browser dialog based on the type of service you created.
a.
From the Create Web Service dialog, click the Find existing WSDLs icon.
b.
From the Edit Partner Link dialog, click the SOA Resource Browser icon.
2-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Expand the tree to display the application server connection to the Oracle
WebLogic Administration Server on which the SOA composite application is
deployed.
5.
6.
Expand the SOA folder and partition. Figure 222 provides details.
7.
8.
Click OK.
For information about creating an application server connection, see Section 43.7.1.1,
"Creating an Application Server Connection."
Note:
1.
2.
3.
4.
5.
6.
Select an option to perform. The options that display for selection are based upon
the current state of the application. Table 211 provides details.
Table 211
Option
Description
Stop
Start
Restarts a composite application revision that was shut down. This action enables
new requests to be processed (and not be rejected). No recovery of messages
occurs.
This option displays when the composite application has been stopped.
2-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Retire
Retires the selected composite revision. If the process life cycle is retired, you
cannot create a new instance. Existing instances are allowed to complete
normally.
An initiating request to the composite application is rejected back to the client.
The behavior of different binding components during rejection is the same as
with the shut down option.
A callback to an initiated composite application instance is delivered properly.
This option displays when the composite application is active.
Activates the retired composite application revision. Note the following behavior
with this option:
Activate
You can no longer configure and monitor this revision of the composite
application.
You can no longer process instances of this revision of the composite
application.
You cannot view previously completed processes.
The state of currently running instances is changed to stale and no new
messages sent to this composite are processed.
If you undeploy the default revision of the composite application (for
example, 2.0), the next available revision of the composite application
becomes the default (for example, 1.0).
Set Default Sets the selected composite application revision to be the default.
Revision
7.
If you want to deploy a prebuilt SOA composite application archive that includes a
deployment profile, right-click the SOA folder and select Deploy SOA Archive.
The archive consists of a JAR file of a single application or a SOA bundle ZIP file
containing multiple applications.
You are prompted to select the following:
The target SOA servers to which you want to deploy the SOA composite
application archive.
The archive to deploy.
The configuration plan to attach to the application. As you move projects from
one environment to another (for example, from testing to production), you
typically must modify several environment-specific values, such as JDBC
connection strings, hostnames of various servers, and so on. Configuration
plans enable you to modify these values using a single text (XML) file called a
configuration plan. The configuration plan is created in either Oracle
JDeveloper or from the command line. During process deployment, the
configuration plan is used to search the SOA project for values that must be
replaced to adapt the project to the next target environment. This is an
optional selection.
Whether you want to overwrite an existing composite of the same revision ID.
This action enables you to redeploy an application revision.
Chapter 43, "Deploying SOA Composite Applications" for details about creating a
deployment profile and a configuration plan and deploying an existing SOA
archive
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite for details about managing deployed SOA
composite applications from Oracle Enterprise Manager Fusion Middleware
Control.
2-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3
Introduction to the SOA Sample Application
This chapter describes how to set up, deploy, and run the SOA sample application that
can be used with this guide. The WebLogic Fusion Order Demo application of the
Fusion Order Demo demonstrates various capabilities of Oracle SOA Suite and is used
as an example throughout this guide.
This chapter includes the following sections:
Section 3.3, "Taking a Look at the WebLogic Fusion Order Demo Application"
Section 3.8, "Undeploying the Composites for the WebLogic Fusion Order Demo
Application"
3-1
StoreFrontService: This project provides access to the store front data and provides
transaction support to update data for customers, orders, and products.
StoreFrontUI: This project provides web pages that the customer uses to browse
the storefront, place orders, register on the site, view order information, and
update the user profile.
Figure 31 shows the Home page of the Store Front module user interface. It shows the
featured products that the site wants to promote and provides access to the full catalog
of items. Products are presented as images along with the name of the product. Page
regions divide the product catalog area from other features that the site offers.
Figure 31 StoreFrontUI Home Page
From the home page, you can browse the web site as an anonymous user, then log in
as a registered customer to place an order.
The Fusion Order Demo application ships with predefined customer data. Because the
Fusion Order Demo application implements Oracle ADF security to manage access to
Oracle ADF resources, only the authenticated user can view orders in their cart.
For more information about the Store Front module, see Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.
Oracle Mediator
3-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Spring
Once an order has been placed by using the Store Front module, the WebLogic Fusion
Order Demo application processes the order. When processing an order, it uses various
internal and external applications, including a customer service application, a credit
validation system, and both an internal vendor and external vendor. For example, the
internal vendor (InternalWarehouseService) and external vendor
(ExternalPartnerSupplier), are sent information for every order. As part of the order
process, they each return a price for which they would supply the items in the order. A
condition in the process determines which supplier is assigned the order.
For information about SOA composite applications, see Chapter 1, "Introduction to
Building Applications with Oracle SOA Suite."
Ensure that you download and install 11g and that it is the Studio Edition, not the Java
Edition. You can verify these details in Oracle JDeveloper from the Help > About
menu option.
To create and deploy SOA composite applications and projects, you must install the
Oracle SOA Suite extension. For instructions on installing this extension for Oracle
JDeveloper, see the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.
2.
3-3
For instructions on installing and configuring Oracle SOA Suite, see the Oracle Fusion
Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
After successfully completing the installation process, perform the following
additional configuration steps:
1. Enable the credentials that are included in the Store Front module by adding a
setting to the configuration file for the domain:
a.
Locate the configuration file set for the Oracle SOA Suite domain in the
following directory:
(UNIX) MW_HOME/user_projects/domains/domain_name/bin/setDomainEnv.sh
(Windows) MW_HOME\user_projects\domains\domain_name\bin\setDomainEnv.cmd
b.
For more information about setting this property, see Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.
c.
On Windows, from the Windows Start menu, select All Programs > Oracle
WebLogic > User Projects > domain_name > Stop Admin Server.
d.
On Windows, from the Windows Start menu, select All Programs > Oracle
WebLogic > User Projects > domain_name > Start Admin Server.
3-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When prompted on UNIX, enter your Oracle WebLogic Server user name and
password. The password is not visible as you type.
The Administration Server is started when the command window displays the
following messages:
<Server state changed to RUNNING>
<Server started in RUNNING mode>
Leave the command window open, although you may minimize it. The
Administration Server is now running and ready for use.
e.
startManagedWebLogic Values
Value
Description
managed_server
admin_url
username
password
2.
If you are deploying remotely from one host that has Oracle JDeveloper to another
host that has the Oracle SOA Suite installation with Oracle WebLogic Server,
modify the JAVA_HOME and PATH environment variables on the host with the
Oracle SOA Suite installation.
Oracle JDeveloper requires changes to these variables for running the scripts that
deploy the composite services. You set the JAVA_HOME variable to include the
path to the Oracle WebLogic Server JDK, and set the PATH variable to include the
path to the Oracle WebLogic Server bin directory for ant.
On UNIX, use the export command. For example:
3-5
export JAVA_HOME=$MW_HOME/jdk160_11
export PATH=$PATH:MW_HOME/modules/org.apache.ant_1.7.0/bin
Open the Control Panel from the Windows Start menu and double-click the
System icon.
b.
In the System Properties dialog, select the Advanced tab and click
Environment Variables.
c.
d.
Double-click the Path system variable and ensure that it includes the path to
the Oracle WebLogic Server ant\bin directory. If it does not, add the path to
the end of the variable value. For example:
;C:\weblogic\modules\org.apache.ant_1.7.0\bin
e.
f.
Click OK twice more to dismiss the Environment Variables and the System
Properties dialogs.
3.
Click Open.
4.
When prompted to migrate files to the 11.1.1.6.0 format, click Yes. When the
migration is complete, click OK.
Figure 32 shows the Application Navigator after you open the file for the
application workspace. It displays the project applications of the WebLogic Fusion
Order Demo.
3-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Application
Description
B2BX12OrderGateway
bin
CreditCardAuthorization
OrderBookingComposite
OrderSDOComposite
PartnerSupplierComposite
3-7
The composite then appears in the SOA Composite Editor in Oracle JDeveloper, as
shown in Figure 33.
Figure 33 SOA Composite Editor
3-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When a new customer registers in Global Companys store front user interface, the
web client sends the customers information to the internal customer service
application called StoreFrontService. StoreFrontService then stores the customer
information in a database. The customer can then browse products, add them to their
online shopping cart, and place the order. User ngreenbe is the only user not required
to register before placing an order.
3-9
When a registered customer uses Global Companys store front user interface, the user
interface invokes the StoreFrontService and provides authentication. A registered user
fills their shopping cart, and places an order. When the order is submitted, the
following events take place:
After an order is placed, the following sequence occurs to complete the order:
1.
Oracle ADF Business Component writes the order to a database with schema for
Fusion Order Demo, and raises a NewOrderSubmitted event using the Event
Delivery Network (EDN). The data associated with this event is the order ID.
2.
3.
The OrderPendingEvent Oracle Mediator receives the order and routes the input
order ID to the OrderProcessor BPEL process.
4.
The OrderProcessor BPEL process receives the order ID from the database, using a
bind entity activity to bind to the exposed Oracle ADF Business Component
StoreFrontService service.
Some of the information about the order used later in the process is:
Customer ID
5.
The BPEL process initiates StoreFrontService, passing it the order ID, to retrieve
information about the customer.
6.
The BPEL process then sends the purchase amount, credit card type, and credit
card number to CreditCardAuthorizationService, which verifies if the customer's
credit card is valid.
If the credit card is not valid, the BPEL process cancels the order.
If the credit card is valid, the BPEL process sends the order to the
RequiresApprovalRule business rule to determine if the order requires approval
by management.
7.
8.
For those orders requiring manual approval, the BPEL process invokes the
ApprovalHumanTask human task, which in turn performs the following:
9.
If the order is approved, the BPEL process sends the order information to the
following suppliers in parallel to obtain a bid:
3-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
10. The two suppliers respond with their bids, and the BPEL process sends the bids to
Stores the order in a temporary queue and uploads it to the fulfillment system
in batch mode overnight.
Routes the order to USPS.
If an Oracle BAM Server is configured, it uses an Oracle BAM adapter to send
data about the order (based on order ID) to the Oracle BAM Server.
If an Oracle BAM Server is configured, it uses an Oracle BAM adapter to send
data about the time for the order to process (based on the instance ID) to the
Oracle BAM Server.
13. Once the order is fulfilled, the BPEL process sets the order to complete.
14. The BPEL process invokes the NotificationService service, which sends the
2.
In the remaining sections of this chapter, deploy and run the Fusion Order Demo. As a
part of it running it, use Oracle Enterprise Manager Fusion Middleware Control to
monitor orders processed by the OrderBookingComposite composite. When you
monitor an order, you can also view the composite sensors and activity sensors.
3.
In the New Gallery dialog, in the Categories tree, select General, and then
Connections.
4.
5.
Enter a unique name for the connection in the Connection Name field and select
WebLogic 10.3 from the Connection Type list. Figure 36 provides details.
3-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Click Next.
The Authentication page is displayed.
7.
Enter weblogic in the User Name field and the password for that administrator
in the Password field.
8.
Table 33
Application
Description
Weblogic Hostname
(Administration Server)
Port
Weblogic Domain
9.
Click Next.
The Test page displays.
JSR-88
JSR-88-LOCAL
JNDI
JSR-160 DomainRuntime
JSR-160 Runtime
JSR-160 Edit
HTTP
Server MBeans Model
...
...
...
...
...
...
...
...
success.
success.
success.
success.
success.
success.
success.
success.
8 of 8 tests successful.
If the test is unsuccessful, ensure that Oracle WebLogic Server is running, and
retry the test.
11. Click Finish.
Introduction to the SOA Sample Application 3-13
12. In the Resource Palette, under IDE Connections, expand Application Server to
see the application server connection that you created. Figure 37 provides details.
Figure 37 Resource Palette
In the New Gallery dialog, in the Categories tree, select General > Connections.
3.
4.
5.
6.
Click Next.
7.
Enter weblogic in the User Name field and the password for that administrator
in the Password field.
8.
Enter the connection information about the Oracle BAM Server host described in
Table 34.
Table 34
Field
Description
Enter the name of the host on which the Oracle BAM Report
Server and web applications are installed. In most cases, the
Oracle BAM web applications host, Oracle BAM Server host,
and the Oracle WebLogic Server are the same.
Enter the name of the host on which the Oracle BAM Server is
installed.
User Name
Password
HTTP Port
Enter the port number or accept the default value of 9001. This
is the HTTP port for the Oracle BAM web applications host.
JNDI Port
Enter the port number or accept the default value of 9001. The
JNDI port is for the Oracle BAM report cache, which is part of
the Oracle BAM Server.
Use HTTPS
3-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
Click Next.
The Test page displays.
3.5.3 Task 3: Install the Schema for the Fusion Order Demo Application
To install the schema for the Fusion Order Demo application:
1. Start Oracle JDeveloper 11g, and from the main menu choose File > Open.
2.
3.
Click Open.
4.
When prompted to migrate files to the 11.1.1.7.0 format, click Yes. When the
migration is complete, click OK.
5.
6.
In the editor, modify the following properties shown in Table 35 for your
environment.
Table 35
Field
Description
jdeveloper.home
jdbc.urlBase
jdbc.port
jdbc.sid
db.adminUser
db.demoUser.tablespace
The tablespace name for the Fusion Order Demo users. For
example:
USERS
7.
From the JDeveloper main menu, choose File > Save All.
8.
In the Application Navigator, under the Resources node, right-click build.xml and
choose Run Ant Target > buildAll.
9.
For more information on the demo schema and scripts, see the README.txt file in
the MasterBuildScript project.
3.5.4 Task 4: Set the Configuration Property for the Store Front Module
You can deploy the Store Front module as a simple web application or as part of a SOA
environment. There is a property defined in the service portion of the Store Front
module that is used within one of its pages to determine whether the Submit Order
button fires an event that launches a BPEL process. When using the Store Front
module within a SOA environment, you must change the default value for this
property.
To set the configuration property for the Store Front module:
1. Choose File > Open.
2.
3.
Click Open.
4.
When prompted to migrate files to the 11.1.1.7.0 format, click Yes. When the
migration is complete, click OK.
Figure 38 shows the Application Navigator after you open the file for the
application workspace.
5.
6.
7.
3-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 39 StoreServiceAMLocalWeb
8.
In the Edit Business Components Configuration dialog, select the Properties tab
and the fod.application.issoaenabled property. This property specifies whether
the application is being deployed to a SOA environment.
9.
Double-click StoreFrontService.jpx.
3.
To the right of the Connection field, click the Edit icon, as shown in Figure 311.
4.
Edit the connect string for the FOD database connection by replacing the values in
the Host Name and SID fields with the correct host and SID. Figure 312 provides
details.
3-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
b.
c.
d.
Deselect option Deploy to all server instances in the domain, and then click
Next.
e.
In the Server Instances page, select the Managed Server for the Oracle
WebLogic Server, such as soa_server, and click OK.
f.
g.
View the messages that display in the Deployment log window at the bottom
of Oracle JDeveloper to ensure deployment was successful.
Deploy the Store Front module. From the Application menu, select Deploy >
StoreFrontModule > to > MyAppServerConnection.
a.
b.
c.
d.
Deselect option Deploy to all server instances in the domain, and then click
Next.
e.
In the Server Instances page, select the Managed Server for the Oracle
WebLogic Server, such as soa_server, and click Next.
f.
g.
View the messages that display in the Deployment log window at the bottom
of Oracle JDeveloper to ensure that deployment was successful.
3-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If you configured an Oracle BAM server during installation, perform the following
steps:
a.
b.
c.
In the editor, modify the following properties shown in Table 36 for the
Oracle BAM environment.
Table 36
Field
Description
enable.bam.sensors
true
Set to true to enable sensors for Oracle BAM.
seed.bam.do
true
Set to true to seed data objects, alerts, and reports for Oracle
BAM.
After deployment is done, set this value back to false. If this
parameter is set to true after initial deployment and you
redeploy at a later time, then the data objects, alerts, and
reports reseed. Therefore, after initial deployment, set this
parameter to false.
bam.server.host
bam.server.port
The port of the Managed Server for Oracle BAM. For example:
9001
Description
bam.server.username
bam.server.password
d.
3.
From the Oracle JDeveloper main menu, choose File > Save All. Keep the
sca-build.properties tab open, so you can modify the seed.bam.do
parameter to false after deployment.
b.
c.
In the editor, modify the following properties shown in Table 37 for the
WebLogicFusionOrderDemo application.
Table 37
Field
Description
oracle.home
soa.only.deployment
false
You set this property to true if you are using the
OrderSDOComposite composite to place orders. This guide
assumes you are using the Store Front module to place orders.
Therefore, you must modify this property to false.
admin.server.host
3-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 37 (Cont.) Properties Required for the WebLogic Fusion Order Demo Application
Field
Description
admin.server.port
managed.server
managed.server.port
The port of the Managed Server for Oracle SOA Suite for
hosting applications. For example:
8001
server.user
server.password
server.targets
soa.server.oracle.home
foreign.mds.type
soa.partition.name
4.
5.
In the Application Navigator, under the Resources node, right-click build.xml and
choose Run Ant Target and select the following ant targets in the specified
sequential order shown in Table 38.
Table 38
Target
Description
1. validateFodConfigSettings
Table 38 (Cont.) ant Targets to Deploy the WebLogic Fusion Order Demo Application
Target
Description
2. server-setup-seed-deploy-test
In the Apache Ant - Log, you see the following message when the target
successfully completes:
BUILD SUCCESSFUL
Total time: nn minutes nn seconds
6.
7.
3-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Undeploying the Composites for the WebLogic Fusion Order Demo Application
using Oracle BAM applications, including Oracle BAM Architect, see Oracle Fusion
Middleware User's Guide for Oracle Business Activity Monitoring.
3.8 Undeploying the Composites for the WebLogic Fusion Order Demo
Application
To undeploy the WebLogic Fusion Order Demo composite application:
1. Access the Undeploy SOA Composite wizard in Fusion Middleware Control
through the options described in Table 39.
Table 39
From the SOA
Infrastructure Menu...
1.
Select SOA
Deployment >
Undeploy.
1.
Right-click soa-infra.
1.
2.
Select SOA
Deployment >
Undeploy.
2.
In the Composite
table, select both
OrderBookingCompo
site and
PartnerSupplierComp
osite.
The Select
Composite page
appears.
2.
In the SOA
3.
Composite
Deployments
section, select
OrderBookingCo
mposite and
PartnerSupplierCo
mposite to
undeploy them,
and click Next.
In the SOA
Composite
3.
Deployments section,
select
OrderBookingCompo
site and
PartnerSupplierComp
osite to undeploy, and
click Next.
Click Undeploy. You are warned if you are about to undeploy the last remaining
revision of a deployed composite application.
Processing messages display.
3.
Undeploying the Composites for the WebLogic Fusion Order Demo Application
3-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part II
Part II
4
4
To Start...
On Windows...
Oracle JDeveloper
Click JDev_Oracle_
$ORACLE_HOME/jdev/bin/jdev
Home\jdeveloper\JDev\bin\jdev.
exe or create a shortcut
2.
On UNIX...
Add a BPEL process service component through one of the following methods:
As a service component in an existing SOA composite application:
a.
From the Component Palette, drag a BPEL Process service component into the
SOA Composite Editor.
4-1
In a new application:
a.
From the Application Navigator, select File > New > Applications > SOA
Application.
This starts the Create SOA Application wizard.
b.
c.
In the Directory field, enter a directory path in which to create the SOA
composite application and project.
d.
Click Next.
e.
In the Project Name dialog, enter a name in the Project Name field.
f.
Click Next.
g.
In the Project SOA Settings dialog, select Composite With BPEL Process.
h.
Click Finish.
Each method causes the Create BPEL Process dialog shown in Figure 41 to
appear.
Figure 41 Create BPEL Process Dialog
3.
Note:
4-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 42
Field
Name
Enter a name for the BPEL process or accept the default name. The name
you enter becomes the file name for the BPEL process, Web Services
Description Language (WSDL), and componentType files in the
Application Navigator.
Always use completely unique names when creating BPEL processes. Do
not create the following:
Namespace
4-3
Description
Template
Service Name
Accept the default value or enter the name of the service this process is
exposing. When you open an invoke, receive, OnMessage, or reply
activity, the service name appears by default in the Partner Link field.
This name is the same name as the partner link.
Expose as a SOAP
Service
4-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Delivery
Set the persistence policy of the process in the delivery layer. This list
enables you to specify a value for the oneWayDeliveryPolicy
deployment descriptor property. This field is displayed if you select an
asynchronous or one-way BPEL process in the Template list. The
possible values are:
4-5
Description
Transaction
Set the transaction behavior of the BPEL instance for initiating calls. This
list enables you to specify a value for the transaction deployment
descriptor property. This field is displayed if you select a synchronous
BPEL process in the Template list. The possible values are:
Note: This property does not apply for midprocess receive activities. In
those cases, another thread in another transaction is used to process the
message. This is because a correlation is needed and it is always done
asynchronously.
For information about transaction and fault propagation semantics for
this property, see Chapter 13, "Transaction and Fault Propagation
Semantics in BPEL Processes."
For information about changing the value of this property in the
Property Inspector, see Section C.1.1, "How to Define Deployment
Descriptor Properties in the Property Inspector."
Input
Accept the default input XSD schema or click the Search icon to select a
different XSD. If you click the Search icon, the Type Chooser dialog
appears. Browse the imported schemas and select the input element (for
example, a purchase order). You can also import an existing schema or
WSDL in the Type Chooser dialog
Output
Accept the default output XSD schema or click the Search icon to select a
different XSD. If you click the Search icon, the Type Chooser dialog
appears. Browse the imported schemas and select the output element (for
example, a purchase order).
4.
Click OK.
Oracle BPEL Designer displays the sections shown in Figure 42.
4-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 42
Each section of this view enables you to perform specific design and deployment
tasks. Table 43 identifies the sections listed in Figure 42.
4-7
Table 43
Element
Description
Application Navigator
Displays the process files of a SOA project. Key files include the
following:
composite_name (composite.xml)
Describes the entire SOA composite application. For more
information about this file, see Section 2.1.2, "What Happens
When You Create a SOA Application and Project."
.bpel
Depending upon the process type you selected, initially
contains a minimal set of activities. (If you selected to create an
asynchronous process, then receive and invoke activities
appear.) You add syntax to this file when you drag activities,
create variables, create partner links, and so on.
.componentType
Describes the services and references for the BPEL process
service component.
.wsdl
The WSDL client interface, which defines the input and output
messages for this BPEL process flow, the supported client
interface and operations, and other features. This functionality
enables the BPEL process flow to be called as a service.
monitor.config
Defines runtime and deployment properties needed to connect
with Oracle BAM Server to create the Oracle BAM data objects
and dashboards.
Designer
4-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Structure window
Importing schemas.
Log window
The input variable type must match the partner link operation
type.
View the syntax inside the BPEL process service component files.
As you drag activities and partner links, and perform other tasks,
the syntax in these source files is immediately updated to reflect
these changes.
History window
Property Inspector
To learn more about these sections, you can also place the
cursor in the appropriate section and press F1 to display online Help.
Note:
5.
Click the icon above the Oracle BPEL Designer to view the BPEL project version
(either 1.1 or 2.0). Figure 43 provides details.
4-9
Introduction to Activities
An assign activity enables you to manipulate data, such as copying the contents of
one variable to another. Figure 44 shows an assign activity.
An invoke activity enables you to invoke a service (identified by its partner link)
and specify an operation for this service to perform. Figure 45 shows an invoke
activity.
4-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The invoke activity enables you to specify an operation you want to invoke for the
service (identified by its partner link). The operation can be one-way or
request-response on a port provided by the service. You can also automatically create
variables in an invoke activity. An invoke activity invokes a synchronous service or
initiates an asynchronous web service.
The invoke activity opens a port in the process to send and receive data. It uses this
port to submit required data and receive a response. For synchronous callbacks, only
one port is needed for both the send and the receive functions.
For more information about activities, see Appendix A, "BPEL Process Activities and
Services."
For information about copying and pasting activities in the same project or between
projects, see Section A.2.2, "Copying and Pasting Activities in BPEL Projects."
A partner link type characterizes the conversational relationship between two services
by defining the roles played by each service in the conversation and specifying the
port type provided by each service to receive messages within the conversation.
Figure 49 shows an example of the attributes of a partner link for a service.
Figure 49 Partner Link Dialog
Field
Description
Name
A unique and recognizable name you provide for the partner link.
Process
WSDL URL
The name and location of the WSDL file or Java interface that you
select for the partner link. Click the SOA Service Explorer icon
(second icon from the left above the WSDL URL field) to access a
window for selecting the WSDL file or Java interface to use.
Java interfaces display for selection under the References folder with a
name of javaEJB. If the component with which you are wiring this
partner link uses WSDL files and you select a Java interface and click
OK, a message displays indicating that this component requires a
WSDL interface. If you click Yes, a compatible WSDL file is created
based on the Java interface.
For more information about integrating components that use Java
interfaces into SOA composite applications, see Chapter 52,
"Integrating the Spring Framework in SOA Composite Applications."
Partner Role
My Role
Note:
4-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Best Practice:
3.
Drag a Partner Link into the appropriate Partner Links swimlane, as shown in
Figure 410.
The following sections describe the impact of partner link creation on the SOA
Composite Editor.
Figure 411 shows how this method of creation appears in the SOA Composite Editor.
Figure 411 SOA Composite Editor Impact
4-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 412 shows how this method of creation appears in the SOA Composite Editor.
Figure 412 SOA Composite Editor Impact
Figure 413 shows how this method of creation appears in the SOA Composite Editor.
Figure 414 shows how this method of creation appears in the SOA Composite Editor.
Figure 414 SOA Composite Editor Impact
4.4.1.6 Partner Links from an Existing Human Task, Business Rule, or Oracle
Mediator
Table 410 describes the impact on the SOA Composite Editor.
Table 410
Figure 415 shows how this method of creation appears in the SOA Composite Editor.
Figure 415 SOA Composite Editor Impact
4-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Adapters
Adapters enable you to integrate the BPEL process service component (and, therefore,
the SOA composite application as a whole) with access to file systems, FTP servers,
database tables, database queues, sockets, Java Message Services (JMS), Oracle User
Messaging Service, and MQ. You can also integrate with services such as HTTP
binding, direct binding, EJB, and others. This wizard enables you to configure the
types of services and adapters shown in Figure 417 for use with the BPEL process
service component:
Figure 417 Service and Adapter Types
For information about the service and adapter types, see Chapter 37, "Getting Started
with Binding Components."
When you select an adapter type, the Service Name dialog shown in Figure 418
prompts you to enter a name. For this example, File Adapter was selected in
Figure 417. When the wizard completes, a WSDL file by this service name appears in
the Application Navigator for the BPEL process service component (for this example,
named USPSShipment.wsdl). The service name must be unique within the project.
This file includes the adapter configuration settings you specify with this wizard.
Other configuration files (such as header files and files specific to the adapter) are also
created and display in the Application Navigator.
The Adapter Configuration wizard dialogs that appear after the Service Name dialog
are based on the adapter type you selected.
You can also add adapters to your SOA composite application as services or references
in the SOA Composite Editor.
For more information about technology adapters, see Oracle Fusion Middleware User's
Guide for Technology Adapters.
For more information, see Section 53.3, "Using Oracle BAM Monitor Express With
BPEL Processes."
4-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5
5
<invoke>
WSDL
PartnerLink
d1
<receive>
5-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
WSDL Client
PartnerLink
BPEL Process
Call
service
<invoke>
d1
BPEL Process
<receive>
d2
<reply>
OR
f1
</wsdl:portType>
Call
service
<invoke>
Get
response
<receive>
WSDL
PartnerLink
d1
<receive>
d2
<invoke>
5-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Call
service
<invoke>
d1
<receive>
<pick>
d2
Wait for
callback
<onMessage>
Time out
in 1M
<onAlarm>
Logic Post
Callback
Logic Post
Timeout
<invoke>
BPEL Process
<scope>
Call
service
<invoke>
Wait for
Callback
<receive>
d1
d2
Service
BPEL
Process
<receive>
<invoke>
<onAlarm>
Notify
Someone
5-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Call
service
<invoke>
Service BPEL
Process
<receive>
d1
<sequence>
<sequence>
<receive>
d2
<invoke>
<receive>
d3
<invoke>
<receive>
d4
<invoke>
</sequence>
</sequence>
WSDL
PartnerLink
Call
service
<invoke>
d1
<receive>
<pick>
<switch>
<onMessage A>
<onMessage B>
Logic B
Logic A
Msg A
or
Msg B
Item in Stock?
<otherwise>
<invoke> Msg A
<invoke> Msg B
As with all partner activities, the WSDL file defines the interaction.
For more information about interactions using one request and one of two possible
responses, see Section 15.2, "Creating a Pick Activity to Select Between Continuing a
Process or Waiting."
5-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
WSDL
PartnerLink
<scope>
Call service
<invoke>
d1
<receive>
Msg A
(maybe)
<switch>
<onMessage A>
<otherwise>
Delay?
Notify User of
Delay
<invoke> Msg A
When
product
ships....
<invokes>
Msg B
Msg B
Call
service
<invoke>
Service BPEL
Process
<receive>
d1
<receive>
d2
<receive>
<invoke>
d3
<invoke>
<receive>
d4
<receive>
<receive>
<receive>
<receive>
eceive>
i
<receive>
<
rece
recei
eceiive
ve
v
e>
<receive>
<
<rece
re
ec
ec
ce
ei
eive
iv
ve>
ve
e>
5-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
BPEL
Process A
Buyer
<invoke>
B
<receive>
C
BPEL
Process B
Seller
<receive>
A
d1
d3
d2
WSDL
PartnerLink
<invoke>
C
WSDL
PartnerLink
BPEL
Process C
Shipper
<receive>
BC
<invoke>
A
5-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6
6
6-1
Note:
For Oracle BPEL Process Manager samples, see the Oracle SOA Suite samples.
Therefore, most variables in BPEL are XML data, and any BPEL process service
component uses much of its code to manipulate these XML variables. This typically
includes performing data transformation between representations required for
different services, and local manipulation of data (for example, to combine the results
from several service invocations).
BPEL also supports service data object (SDO) variables, which are not in an XML
format, but rather in a memory structure format.
6-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 61 shows the formal syntax for BPEL version 1.1, as described in the
Business Process Execution Language for Web Services Specification Version 1.1:
Example 61 Assign Activity for BPEL 1.1
<assign standard-attributes>
standard-elements
<copy>
from-spec
to-spec
</copy>
</assign>
Example 62 shows the formal syntax for BPEL version 2.0, as described in the Web
Services Business Process Execution Language Specification Version 2.0. The
keepSrcElementName attribute specifies whether the element name of the
destination (as selected by the to-spec) is replaced by the element name of the source
(as selected by the from-spec) during the copy operation. When
keepSrcElementName is set to no (the default value), the name (that is, the
namespace name and local name properties) of the original destination element is
used as the name of the resulting element. When keepSrcElementName is set to yes,
the source element name is used as the name of the resulting destination element.
Example 62 Assign Activity for BPEL 2.0
<assign validate="yes|no"? standard-attributes>
standard-elements
(
<copy keepSrcElementName="yes|no"? ignoreMissingFromData="yes|no"?>
from-spec
to-spec
</copy>
. . .
. . .
</assign>
This syntax is described in detail in both specifications. The from-spec and to-spec
typically specify a variable or variable part, as shown in Example 63:
Example 63 from-spec and to-spec Attributes
<assign>
<copy>
<from variable="c1" part="address"/>
<to variable="c3"/>
</copy>
</assign>
When you use Oracle JDeveloper, you supply assign activity details in a Copy Rules
dialog that includes a From section and a To section. This reflects the preceding BPEL
source code syntax.
XPath standards play a key role in the assign activity. Brief examples are shown here
as an introduction; examples with more context and explanation are provided in the
sections that follow.
XPath queries
6-3
An XPath query selects a field within a source or target variable part. The from or
to clause can include a query attribute whose value is an XPath query string.
Example 64 provides an example:
Example 64 query Attribute
<from variable="input" part="payload"
query="/p:CreditFlowRequest/p:ssn"/>
The value of the query attribute must be a location path that selects exactly one
node. You can find further details about the query attribute and XPath standards
syntax in the Business Process Execution Language for Web Services Specification
Version 1.1 (section 14.3) or Web Services Business Process Execution Language
Specification Version 2.0 (section 8.4), and the XML Path Language (XPath)
Specification, respectively.
XPath expressions
You use an XPath expression (specified in an expression attribute in the from
clause) to indicate a value to be stored in a variable. For example:
<from expression="100"/>
The expression can be any general expression (that is, an XPath expression that
evaluates to any XPath value type). Similarly, the value of an expression attribute
must return exactly one node or one object only when it is used in the from clause
within a copy operation. For more information about XPath expressions, see
section 9.1.4 of the XML Path Language (XPath) Specification.
Within XPath expressions, you can call the following types of functions:
For a complete list of the functions built into XPath standards, see section 4 of the
XML Path Language (XPath) Specification.
For BPEL 1.1, the extensions are defined in the standard BPEL namespace
http://schemas.xmlsoap.org/ws/2003/03/business-process/
and indicated by the prefix bpws:
<from expression= "bpws:getVariableData('input', 'payload', '/p:value') +
1"/>
For more information, see sections 9.1 and 14.1 of the Business Process Execution
Language for Web Services Specification Version 1.1. For more information about
getVariableData, see Section B.2.57.2, "getVariableData."
For BPEL 2.0, the extensions are also defined in the standard BPEL namespace
http://schemas.xmlsoap.org/ws/2003/03/business-process/.
However, the prefix is bpel:
<from>bpel:getVariableProperty('input', 'propertyName')</from>
6-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information, see section 8.3 of the Web Services Business Process
Execution Language Specification Version 2.0. For more information about
getVariableProperty, see Section B.2.57.4, "getVariableProperty (For
BPEL 2.0)."
Custom functions
Oracle BPEL Process Manager functions are defined in the
bpel-xpath-functions-config.xml and placed inside the orabpel.jar
file. For more information, see Section B.7, "Creating User-Defined XPath
Extension Functions."
Sophisticated data manipulation can be difficult to perform with the BPEL assign
activity and the core XPath functions. However, you can perform complex data
manipulation and transformation by using XSLT, Java, or a bpelx operation under an
assign activity (See Section 6.15, "Manipulating XML Data with bpelx Extensions") or
as a web service. For XSLT, Oracle BPEL Process Manager includes XPath functions
that execute these transformations.
For more information about XPath and XQuery transformation code examples, see
Chapter 40, "Creating Transformations with the XSLT Mapper."
For more information about the assign activity, see Section A.2.3, "Assign Activity."
Passing large schemas through an assign activity can cause
Oracle JDeveloper to freeze up and run low on memory if you
right-click the target or source payload node in the Edit Assign dialog
and select Expand All Child Nodes. As a workaround, manually
expand the payload elements.
Note:
The entity variable can be used with an Oracle Application Development Framework
(ADF) Business Component data provider service using SDO-based data.
Before Release 11g, variables and messages exchanged within a BPEL business process
were a disconnected payload (a snapshot of data returned by a web service) placed
into an XML structure. In some cases, the user required this type of fit. In other cases,
this fit presented challenges.
6-5
To address these challenges with Release 11g, you create an entity variable during
variable declaration. An entity variable acts as a data handle to access and plug in
different data provider service technologies behind the scenes. During compilation
and runtime, Oracle BPEL Process Manager delegates data operations to the
underlying data provider service.
Table 61 provides an example of how data conversion was performed in previous
releases (using the database adapter as an example) and in release 11g with the entity
variable.
Table 61
10.1.x Releases
6-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
The WebLogic Fusion Order Demo application describes use of the entity variable. For
more information, see Chapter 3, "Introduction to the SOA Sample Application."
SDO Binding
Component
Service
Wire
You use the SOA Composite Editor and Oracle BPEL Designer to perform the
following tasks:
6-7
Define an SDO binding component service and a BPEL process service component
in the composite application.
Connect (wire) the SDO service and BPEL process service component.
For more information about using the SOA Composite Editor, see Chapter 2,
"Developing SOA Composite Applications with Oracle SOA Suite."
SDO Binding
Component
Reference
ADF BC
Application Using
SDO-Formed Data
When the Oracle ADF Business Component application is the external partner link to
the outside world, there is no SDO binding component reference in the SOA
Composite Editor that you drag into the composite application to create outbound
communication. Instead, communication between the composite application and the
Oracle ADF Business Component application occurs as follows:
6-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Right-click the Variables folder and select Expand All Child Nodes.
3.
4.
5.
Click the Entity Variable checkbox and select the Search icon to the right of the
Partner Link field.
The Partner Link Chooser dialog appears with a list of available services,
including the SDO service called ADF-BC Service.
6.
Browse for and select the service for the Oracle ADF Business Component
application.
7.
Click OK to close the Partner Link Chooser and Create Variable dialogs.
The dialog looks as shown in Figure 63.
Drag a Bind Entity activity into your BPEL process service component.
The Bind Entity dialog appears.
3.
4.
To the right of the Entity Variable field, click the Search icon.
The Variable Chooser dialog appears.
5.
Select the entity variable created in Section 6.2.1.3, "Creating an Entity Variable
and Choosing a Partner Link" and click OK.
6.
7.
6-9
Table 62
Field
Value
Key Value
Enter the key value expression. This expression must match the
type of a key. The following examples show expression value
keys for a POID key:
$inputMsg.payload/tns:poid
bpws:getVariableData(inputmsg,payload,tns:
poid)
8.
6-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
For more information about using SDOs, see Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework. This guide describes
how to expose application modules as web services and publish rows of view data
objects as SDOs. The application module is the ADF framework component that
encapsulates business logic as a set of related business functions.
6-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 610
<assign>
<!-- copy from literal xml to the variable -->
<copy>
<from>
<result xmlns="http://samples.otn.com">
<name/>
<symbol/>
<price>12.3</price>
<quantity>0</quantity>
<approved/>
<message/>
</result>
</from>
<to variable="output" part="payload"/>
</copy>
</assign>
<assign>
<copy>
<from variable="c1"/>
<to variable="c2"/>
</copy>
<copy>
<from variable="c1" part = "address"/>
<to variable="c3"/>
</copy>
</assign>
Variable Definition
The WSDL file defines the person message type shown in Example 613:
Example 613
6-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about this code example, see Section 9.3.2 of the Business Process
Execution Language for Web Services Specification Version 1.1. For BPEL 2.0, see Section
8.4.4 of Web Services Business Process Execution Language Specification Version 2.0 for a
similar example.
For more information, see Section A.2.3, "Assign Activity."
<variables>
<variable name="tmp" element="tns:output">
<from>
<literal>
<output xmlns="http://samples.otn.com/bpel2.0/ch8.1">
<value>1000</value>
</output>
</literal>
</from>
</variable>
</variables>
For more information, see section 8.1 of Web Services Business Process Execution
Language Specification Version 2.0.
6.6.1 How to Access Fields Within Element-Based and Message Type-Based Variables
In Example 615, the ssn field is copied from the CreditFlow processs input
message into the ssn field of the credit rating services input message.
Example 615
<assign>
<copy>
<from variable="input" part="payload"
query="/tns:CreditFlowRequest/tns:ssn"/>
<to variable="crInput" part="payload" query="/tns:ssn"/>
</copy>
</assign>
Example 616 shows how the BPEL file defines message type-based variables involved
in this assignment:
Example 616
The crInput variable is used as an input message to a credit rating service. Its
message type, CreditFlowRequestMessage, is defined in the
CreditFlowService.wsdl file, as shown in Example 617:
Example 617
CreditFlowRequestMessage Definition
<message name="CreditFlowRequestMessage">
<part name="payload" element="tns:CreditFlowRequest"/>
</message>
CreditRatingServiceRequestMessage Definition
<message name="CreditRatingServiceRequestMessage">
<part name="payload" element="tns:ssn"/>
</message>
Example 619 shows the BPEL 2.0 syntax for how the BPEL file defines message
type-based variables involved in the assignment in Example 615. Note that
/tns:CreditFlowRequest is not required.
Example 619
<copy>
<from>$input.payload/tns:ssn</from>
<to>$crInput.payload</to>
</copy>
A BPEL process can also use element-based variables. Example 620 shows how to use
element-based variables in BPEL 1.1. The autoloan field is copied from the loan
application processs input message into the customer field of a web services input
message.
Example 620
<assign>
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:
application/autoloan:customer"/>
<to variable="customer"/>
</copy>
</assign>
6-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 621
<assign>
<copy>
<from>$input.payload/autoloan:application/autoloan:customer</from>
<to>$customer</to>
</copy>
</assign>
Example 622 shows how the BPEL file defines element-based variables involved in an
assignment:
Example 622
2.
3.
In the BPEL process, click the Variables icon of the scope activity.
The variable you moved is displayed, as shown in Figure 68.
3.
<assign>
<!-- copy from integer expression to the variable -->
<copy>
<from expression="100"/>
<to variable="output" part="payload" query="/p:result/p:quantity"/>
</copy>
</assign>
6-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<assign>
<copy>
<from expression="bpws:getVariableData('input', 'payload',
'/p:value') + 1"/>
<to variable="output" part="payload" query="/p:result"/>
</copy>
</assign>
You can also use $variable syntax in BPEL 1.1, as shown in Example 625:
Example 625
<assign>
<copy>
<from expression="$input.payload + 1"/>
<to variable="output" part="payload" query="/p:result"/>
</copy>
</assign>
<assign>
<copy>
<from>$input.payload + 1</from>
<to>$output.payload</to>
</copy>
</assign>
<assign>
<!-- copy from string expression to the variable -->
Concatenating Strings
<copy>
<from expression="'GE'"/>
<to variable="output" part="payload" query="/p:result/p:symbol"/>
</copy>
</assign>
<assign>
<copy>
<from>'GE'</from>
<to>$output.payload/p:symbol</from>
</copy>
</assign>
<assign>
<!-- copy from XPath expression to the variable -->
<copy>
<from expression="concat('Hello ',
bpws:getVariableData('input', 'payload', '/p:name'))"/>
<to variable="output" part="payload" query="/p:result/p:message"/>
</copy>
</assign>
Other string manipulation functions available in XPath are listed in section 4.2 of the
XML Path Language (XPath) Specification.
<assign>
6-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<assign>
<copy>
<from>true()</from>
<to>$output.payload/approved</to>
</copy>
</assign>
The XPath specification recommends that you use the "true()" and "false()"
functions as a method for returning boolean constant values.
If you instead use "boolean(true)" or "boolean(false)", the true or false
inside the boolean function is interpreted as a relative element step, and not as any
true or false constant. It attempts to select a child node named true under the
current XPath context node. In most cases, the true node does not exist. Therefore, an
empty result node set is returned and the boolean() function in XPath 1.0 converts
an empty node set into a false result. This result can be potentially confusing.
Example 633 shows an example that uses the function getCurrentDate in BPEL
2.0.
Manipulating Attributes
Example 633
<assign>
<copy>
<from>xpath20:getCurrentDate()</from>
<to>$output.payload/invoiceDate</to>
</copy>
</assign>
In Example 634, the formatDate function converts the date-time value provided in
XSD format to the string 'Jun 10, 2005' (and assigns it to the string field
formattedDate).
Example 634
Example 635 shows how the formatDate function works in BPEL 2.0.
Example 635
<assign>
<copy>
<from>ora:formatDate('2005-06-10T15:56:00','MMM dd, yyyy')</from>
<to>$output.payload/formattedDate</to>
</copy>
</assign>
<invalidLoanApplication xmlns="http://samples.otn.com">
<application xmlns = "http://samples.otn.com/XPath/autoloan">
<customer custId = "111" >
<name>
Mike Olive
</name>
...
</customer>
...
</application>
</invalidLoanApplication>
6-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The BPEL 1.1 code in Example 637 selects the custId attribute of the customer field
and assigns it to the variable custId:
Example 637
<assign>
<!-- get the custId attribute and assign to variable custId -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/@custId"/>
<to variable="custId"/>
</copy>
</assign>
Example 638 shows the equivalent syntax in BPEL 2.0 for selecting the custId
attribute of the customer field and assigning it to the variable custId:
Example 638
<assign>
<copy>
<from>$input.payload/autoloan:application/autoloan:customer/@custId</from>
<to>$custId</to>
</copy>
</assign>
The namespace prefixes in this example are not integral to the example.
The WSDL file defines a customer to have a type in which custId is defined as an
attribute, as shown in Example 639:
Example 639
<complexType name="CustomerProfileType">
<sequence>
<element name="name" type="string"/>
...
</sequence>
<attribute name="custId" type="string"/>
</complexType>
In BPEL 2.0, you select an extension type by right-clicking the copy rule, selecting
Change rule type, and then selecting the extension type, as shown in Figure 611.
Figure 611 Copy Rule Converted to bpelx Extension in BPEL 2.0
For more information, see the online Help for this dialog and Section A.2.3, "Assign
Activity."
6-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For BPEL 1.1, select a copy rule, then select Append from the dropdown list, as
shown in Figure 610.
For BPEL 2.0, right-click a copy rule, select Change rule type, and then select
Append, as shown in Figure 611.
Note: The bpelx:append extension is not supported with SDO
variables and causes an error.
<bpel:assign>
<bpelx:append>
<bpelx:from ... />
<bpelx:to ... />
</bpelx:append>
</bpel:assign>
The from-spec query within bpelx:append yields zero or more nodes. The node
list is appended as child nodes to the target node specified by the to-spec query.
The to-spec query must yield one single L-Value element node. Otherwise, a
bpel:selectionFailure fault is generated. The to-spec query cannot refer to a
partner link.
Example 641 consolidates multiple bills of material into one single bill of material
(BOM) by appending multiple b:parts for one BOM to b:parts of the consolidated
BOM.
Example 641
<bpel:assign>
<bpelx:append>
<bpelx:from variable="billOfMaterialVar"
query="/b:bom/b:parts/b:part" />
<bpelx:to variable="consolidatedBillOfMaterialVar"
query="/b:bom/b:parts" />
</bpelx:append>
</bpel:assign>
Example 642
<bpel:assign>
<bpelx:append>
<bpelx:from>$billOfMaterialVar/b:parts/b:part</bpelx:from>
<bpelx:to>$consolidatedBillOfMaterialVar/b:parts</bpelx:from>
</bpelx:append>
</bpel:assign>
Note:
For BPEL 1.1, select a copy rule, then select InsertBefore from the dropdown list,
as shown in Figure 610.
For BPEL 2.0, right-click a copy rule, select Change rule type, and then select
InsertBefore, as shown in Figure 611.
<bpel:assign>
<bpelx:insertBefore>
<bpelx:from ... />
<bpelx:to ... />
</bpelx:insertBefore>
</bpel:assign>
The from-spec query within bpelx:insertBefore yields zero or more nodes. The
node list is appended as child nodes to the target node specified by the to-spec
query.
The to-spec query of the insertBefore operation points to one or more single
L-Value nodes. If multiple nodes are returned, the first node is used as the reference
node. The reference node must be an element node. The parent of the reference node
must also be an element node. Otherwise, a bpel:selectionFailure fault is
generated. The node list generated by the from-spec query selection is inserted
before the reference node. The to-spec query cannot refer to a partner link.
Example 644 shows the syntax before the execution of <insertBefore>. The value
of addrVar is:
Example 644
Presyntax Execution
<a:usAddress>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
6-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</a:usAddress>
Postsyntax Execution
<bpel:assign>
<bpelx:insertBefore>
<bpelx:from>
<a:city>Redwood Shore></a:city>
</bpelx:from>
<bpelx:to "addrVar" query="/a:usAddress/a:state" />
</bpelx:insertBefore>
</bpel:assign>
addrVar Value
<a:usAddress>
<a:city>Redwood Shore</a:city>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
</a:usAddress>
<assign>
<extensionAssignOperation>
<bpelx:insertBefore>
<bpelx:from>
<bpelx:literal>
<a:city>Redwood Shore></a:city>
</bpelx:literal>
</bpelx:from>
<bpelx:to>$addrVar/a:state</bpelx:to>
</bpelx:insertBefore>
</extensionAssignOperation>
</assign>
after another variables contents. To use this extension, perform one of the following
steps at the bottom of the Copy Rules tab:
For BPEL 1.1, select a copy rule, then select InsertAfter from the dropdown list, as
shown in Figure 610.
For BPEL 2.0, right-click a copy rule, select Change rule type, and then select
InsertAfter, as shown in Figure 611.
<bpel:assign>
<bpelx:insertAfter>
<bpelx:from ... />
<bpelx:to ... />
</bpelx:insertAfter>
</bpel:assign>
This operation is similar to the functionality described for Section 6.15.2, "How to Use
bpelx:insertBefore," except for the following:
If multiple L-Value nodes are returned by the to-spec query, the last node is
used as the reference node.
Instead of inserting nodes before the reference node, the source nodes are inserted
after the reference node.
Presyntax Execution
<a:usAddress>
<a:addressLine>500 Oracle Parkway</a:addressLine>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
</a:usAddress>
Postsyntax Execution
<bpel:assign>
<bpelx:insertAfter>
<bpelx:from>
<a:addressLine>Mailstop 1op6</a:addressLine>
</bpelx:from>
<bpelx:to "addrVar" query="/a:usAddress/a:addressLine[1]" />
</bpelx:insertAfter>
</bpel:assign>
6-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 651
addrVar Value
<a:usAddress>
<a:addressLine>500 Oracle Parkway</a:addressLine>
<a:addressLine>Mailstop 1op6</a:addressLine>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
</a:usAddress>
The from-spec query within bpelx:insertAfter yields zero or more nodes. The
node list is appended as child nodes to the target node specified by the to-spec
query.
<assign>
<extensionAssignOperation>
<bpelx:insertAfter>
<bpelx:from>
<bpelx:literal>
<a:addressLine>Mailstop 1op6</a:addressLine>
</bpelx:literal>
</bpelx:from>
<bpelx:to>$addrVar/a:addressLine[1]</bpelx:to>
</bpelx:insertAfter>
</extensionAssignOperation>
</assign>
After releasing the cursor, the bpelx:remove extension is applied to the target
variable. Figure 613 provides details.
<bpel:assign>
<bpelx:remove>
<bpelx:target variable="ncname" part="ncname"? query="xpath_str" />
</bpelx:remove>
</bpel:assign>
Node removal specified by the XPath expression is supported. Nodes specified by the
XPath expression can be multiple, but must be L-Values. Nodes being removed from
this parent can be text nodes, attribute nodes, and element nodes.
The XPath expression can return one or more nodes. If the XPath expression returns
zero nodes, then a bpel:selectionFailure fault is generated.
The syntax of bpelx:target is similar to and a subset of to-spec for the copy
operation.
Example 654 shows addrVar with the following value:
Example 654
addrVar
<a:usAddress>
<a:addressLine>500 Oracle Parkway</a:addressLine>
<a:addressLine>Mailstop 1op6</a:addressLine>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
</a:usAddress>
After executing the syntax shown in Example 655 in the BPEL process service
component file, the second address line of Mailstop is removed:
Example 655
<bpel:assign>
<bpelx:remove>
<target variable="addrVar"
query="/a:usAddress/a:addressLine[2]" />
</bpelx:remove>
</bpel:assign>
After executing the syntax shown in Example 656 in the BPEL process service
component file, both address lines are removed:
6-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 656
<bpel:assign>
<bpelx:remove>
<target variable="addrVar"
query="/a:usAddress/a:addressLine" />
</bpelx:remove>
</bpel:assign>
<assign>
<extensionAssignOperation>
<bpelx:remove>
<bpelx:target>$ncname.ncname/xpath_str</bpelx:target>
</bpelx:remove>
</extensionAssignOperation>
</assign>
<bpel:assign>
<bpelx:rename elementTo="QName1"? typeCastTo="QName2"?>
<bpelx:target variable="ncname" part="ncname"? query="xpath_str" />
</bpelx:rename>
</bpel:assign>
The syntax of bpelx:target is similar to and a subset of to-spec for the copy
operation. The target must return a list of one more element nodes. Otherwise, a
bpel:selectionFailure fault is generated. The element nodes specified in the
from-spec are renamed to the QName specified by the elementTo attribute. The
xsi:type attribute is added to those element nodes to cast those elements to the
QName type specified by the typeCastTo attribute.
Assume you have the employee list shown in Example 659:
Example 659
xsi:type Attribute
<e:empList>
<e:emp>
<e:firstName>John</e:firstName><e:lastName>Dole</e:lastName>
<e:emp>
<e:emp xsi:type="e:ManagerType">
<e:firstName>Jane</e:firstName><e:lastName>Dole</e:lastName>
<e:approvalLimit>3000</e:approvalLimit>
<e:managing />
<e:emp>
<e:emp>
<e:firstName>Peter</e:firstName><e:lastName>Smith</e:lastName>
<e:emp>
<e:emp>
<e:firstName>Mary</e:firstName><e:lastName>Smith</e:lastName>
<e:emp>
</e:empList>
Promotion changes are now applied to Peter Smith in the employee list in
Example 660:
Example 660
<bpel:assign>
<bpelx:rename typeCastTo="e:ManagerType">
<bpelx:target variable="empListVar"
query="/e:empList/e:emp[./e:firstName='Peter' and
./e:lastName='Smith'" />
</bpelx:rename>
</bpel:assign>
After executing the above casting (renaming), the data looks as shown in
Example 661 with xsi:type info added to Peter Smith:
Example 661
Data Output
<e:empList>
<e:emp>
<e:firstName>John</e:firstName><e:lastName>Dole</e:lastName>
<e:emp>
<e:emp xsi:type="e:ManagerType">
<e:firstName>Jane</e:firstName><e:lastName>Dole</e:lastName>
<e:approvalLimit>3000</e:approvalLimit>
<e:managing />
<e:emp>
<e:emp xsi:type="e:ManagerType">
<e:firstName>Peter</e:firstName><e:lastName>Smith</e:lastName>
<e:emp>
<e:emp>
<e:firstName>Mary</e:firstName><e:lastName>Smith</e:lastName>
<e:emp>
</e:empList>
The employee data of Peter Smith is now invalid, because <approvalLimit> and
<managing> are missing. Therefore, <append> is used to add that information.
Example 662 provides an example.
Example 662
<bpel:assign>
6-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<bpelx:rename typeCastTo="e:ManagerType">
<bpelx:target variable="empListVar"
query="/e:empList/e:emp[./e:firstName='Peter' and
./e:lastName='Smith'" />
</bpelx:rename>
<bpelx:append>
<bpelx:from>
<e:approvalLimit>2500</e:approvalLimit>
<e:managing />
</bpelx:from>
<bpelx:to variable="empListVar"
query="/e:empList/e:emp[./e:firstName='Peter' and
./e:lastName='Smith'" />
</bpelx:append>
</bpel:assign>
With the execution of both rename and append, the corresponding data looks as
shown in Example 663:
Example 663
<e:emp xsi:type="e:ManagerType">
<e:firstName>Peter</e:firstName><e:lastName>Smith</e:lastName>
<e:approvalLimit>2500</e:approvalLimit>
<e:managing />
<e:emp>
<bpel:assign>
<extensionAssignOperation>
<bpelx:rename elementTo="QName1"? typeCastTo="QName2"?>
<bpelx:target>$ncname[.ncname][/xpath_str]</bpelx:target>
</bpelx:rename>
</extensionAssignOperation>
</bpel:assign>
For BPEL 1.1, select a copy rule, then select CopyList from the dropdown list, as
shown in Figure 610.
For BPEL 2.0, right-click a copy rule, select Change rule type, and then select
CopyList, as shown in Figure 611.
<bpel:assign>
<bpelx:copyList>
<bpelx:from ... />
<bpelx:to ... />
</bpelx:copyList>
</bpel:assign>
The from-spec query can yield a list of either all attribute nodes or all element nodes.
The to-spec query can yield a list of L-value nodes: either all attribute nodes or all
element nodes.
All the element nodes returned by the to-spec query must have the same parent
element. If the to-spec query returns a list of element nodes, all element nodes must
be contiguous.
If the from-spec query returns attribute nodes, then the to-spec query must return
attribute nodes. Likewise, if the from-spec query returns element nodes, then the
to-spec query must return element nodes. Otherwise, a
bpws:mismatchedAssignmentFailure fault is thrown.
The from-spec query can return zero nodes, while the to-spec query must return
at least one node. If the from-spec query returns zero nodes, the effect of the
copyList operation is similar to the remove operation.
The copyList operation provides the following features:
Schema
<schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/Event_jws/Event/EventTest"
xmlns="http://www.w3.org/2001/XMLSchema">
<element name="process">
<complexType>
<sequence>
<element name="payload" type="string"
maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="processResponse">
<complexType>
<sequence>
6-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Variable Content
<ns1:process xmlns:ns1="http://xmlns.oracle.com/Event_jws/Event/EventTest">
<ns1: payload >a</ns1: payload >
<ns1: payload >b</ns1: payload >
</ns1:process>
Variable Content
<ns1:processResponse xmlns:ns1="http://xmlns.oracle.com/Event_
jws/Event/EventTest">
<ns1: payload >c</ns1: payload >
</ns1:process>
bpelx:copyList
<assign>
<bpelx:copyList>
<bpelx:from variable="inputVariable" part="payload"
query="/client:process/client:payload"/>
<bpelx:to variable="outputVariable" part="payload"
query="/client:processResponse/client:payload"/>
</bpelx:copyList>
</assign>
Variable Content
<ns1:processResponse xmlns:ns1="http://xmlns.oracle.com/Event_
jws/Event/EventTest">
<ns1: payload >a</ns1: payload >
<ns1: payload >b</ns1: payload >
</ns1:process>
<assign>
<extensionAssignOperation>
<bpelx:copyList>
<bpelx:from>$inputVariable.payload/client:payload</bpelx:from>
Manipulating XML Data in a BPEL Process 6-35
<bpelx:to>$outputVariable.payload/client:payload</bpelx:to>
</bpelx:copyList>
</extensionAssignOperation>
</assign>
ignoreMissingFromData
insertMissingToData
keepSrcElementName
At the bottom of the Copy Rules tab of an assign activity, you right-click a selected
copy rule to display a menu for choosing the appropriate attribute. Figure 614
provides details.
Figure 614 Assign Extension Attributes
BPEL 1.1
BPEL 2.0
<copy
bpelx:ignoreMissingFromData="yes|no"/>
<copy ignoreMissingFromData="yes|no"/>
BPEL 1.1
BPEL 2.0
<copy
bpelx:insertMissingToData="yes|no"/>
<copy bpelx:insertMissingToData="yes|no"/>
6-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
attribute was not implemented in BPEL 1.1. Table 65 describes the syntax supported
in BPEL version 2.0.
Table 65
BPEL 1.1
BPEL 2.0
Not implemented
<copy keepSrcElementName="yes|no"/>
From the BPEL Constructs section of the Component Palette, drag an Assign
activity into the designer.
2.
3.
In the General tab, enter a name for the activity and select the Validate
checkbox.
4.
5.
From the Oracle Extensions section of the Component Palette, drag a Validate
activity into the designer.
2.
3.
4.
5.
6.
7.
From the BPEL Constructs section of the Component Palette, drag an Assign
activity into the designer.
2.
3.
In the General tab, enter a name for the activity and select the Validate
checkbox.
4.
5.
Click the Source tab to view the syntax. The syntax for validating XML data
with the assign activity is slightly different between BPEL versions 1.1 and 2.0.
<assign name="Assign1" validate="yes">
. . .
</assign>
From the BPEL Constructs section of the Component Palette, drag a Validate
activity into the designer.
2.
3.
4.
5.
6.
7.
Click the Source tab to view the syntax. The syntax for validating XML data
with the validate activity is slightly different between BPEL versions 1.1 and
2.0.
<validate name="Validate1" variables="inputVariable"/>
The Input field (for an inputVariable attribute) and Output field (for an
outputVariable attribute) of an invoke dialog
The variables referenced by these fields typically must be message type variables in
which the QName matches the QName of the input and output message types used in
the operation, respectively.
The one exception is if the WSDL operation in the activity uses a message containing
exactly one part that is defined using an element. In this case, a variable of the same
element type used to define the part can be referenced by the inputVariable and
outputVariable attributes, respectively, in the invoke activity or the variable
attribute of the receive or reply activity.
Using a variable in this situation must be the same as declaring an anonymous,
temporary WSDL message variable based on the associated WSDL message type.
Copying element data between the anonymous, temporary WSDL message variable
and the element variable acts as a single virtual assign activity with one copy
operation whose keepSrcElementName attribute is set to yes. The virtual assign
must follow the same rules and use the same faults as a real assign activity. Table 66
provides details.
6-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 66
For The...
The...
inputVariable attribute
outputVariable attribute Value of the received part in the temporary WSDL message
variable sets the value of the variable referenced by the attribute.
Receive activity
Reply activity
For more information about the keepSrcElementName attribute, see Section 6.15.7.3,
"keepSrcElementName Attribute."
toParts Element
<toParts>
<toPart part="payload" fromVariable="request"/>
</toParts>
The toParts element acts as a single, virtual assign activity. Each toPart acts as a
copy operation. One toPart at most exists for each part in the WSDL message
definition. Each copy operation copies data from the variable specified in the
fromVariable attribute into the part of the anonymous, temporary WSDL variable
referenced in the part attribute of the toParts element.
The fromParts element in receive activities, invoke activities, the onEvent branch of
scope activities, and the onMessage branch of pick activities is similar to the toParts
element. The fromParts element, as shown in Example 673, retrieves data from an
incoming multipart WSDL message and places the data into individual variables.
Example 673
fromParts Element
<fromParts>
<fromPart part="payload" toVariable="request"/>
</fromParts>
For both the toParts and fromParts elements, the virtual assign activity must
follow the same semantics and generate the same faults as a real assign activity.
The presence of a fromParts element in an invoke activity does not require it to have
a fromPart for every part in the WSDL message definition. Parts not explicitly
represented by fromParts elements are not copied from the anonymous WSDL
variable to the variable.
For more information about mapping WSDL message parts with the toParts and
fromParts elements, see the Web Services Business Process Execution Language Version
2.0 Specification located at the following URL:
http://www.oasis-open.org
2.
Note that the assign activity in Figure 616 copies the test-type-variable contents
to Var1.
6-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Note that the To Parts button at the bottom of the reply activity is enabled in
Figure 617, instead of the Variable button. You create information for this section
by clicking the Add icon. The copy operation copies data from the variable
indicated in the From Variable attribute, Var1, into the part of the anonymous,
temporary WSDL variable referenced in the Part attribute.
<sequence name="main">
<!-- Receive input from requester. This maps to operation defined in WSDL -->
<receive name="receiveInput" partnerLink="test_client"
portType="client:Test" operation="process" variable="inputVariable"
createInstance="yes"/>
<!-- Generate reply to synchronous request -->
<assign name="Assign_1">
<copy>
<from>"test-type-variable"</from>
<to>$Var1</to>
</copy>
</assign>
<reply name="replyOutput" partnerLink="test_client" portType="client:Test"
operation="process">
<toParts>
<toPart part="payload" fromVariable="Var1"/>
</toParts>
</reply>
</sequence>
Example 675
<wsdl:types>
<schema attributeFormDefault="unqualified" elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/RT_Validate_P_02_jws/ch10_
3toParts_1/Test"
xmlns="http://www.w3.org/2001/XMLSchema">
<element name="process">
<complexType>
<sequence>
<element name="input" type="string"/>
</sequence>
</complexType>
</element>
<element name="processResponse">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
</schema>
</wsdl:types>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MESSAGE TYPE DEFINITION - Definition of the message types used as
part of the port type defintions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<wsdl:message name="TestRequestMessage">
<wsdl:part name="payload" element="client:process"/>
</wsdl:message>
<wsdl:message name="TestResponseMessage">
<wsdl:part name="payload" type="xsd:string"/>
</wsdl:message>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PORT TYPE DEFINITION - A port type groups a set of operations into
a logical service unit.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<!-- portType implemented by the Test BPEL process -->
<wsdl:portType name="Test">
<wsdl:operation name="process">
<wsdl:input message="client:TestRequestMessage"/>
<wsdl:output message="client:TestResponseMessage"/>
</wsdl:operation>
</wsdl:portType>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PARTNER LINK TYPE DEFINITION
6-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<plnk:partnerLinkType name="Test">
<plnk:role name="TestProvider">
<plnk:portType name="client:Test"/>
</plnk:role>
</plnk:partnerLinkType>
</wsdl:definitions>
Example 676 shows a .bpel file with toPart elements defined in invoke and reply
activities. This maps to the operation defined in the WSDL file shown in
Example 677. The copy operation in the invoke activity copies data from the variable
indicated in the fromVariable attribute into the part of the anonymous, temporary
WSDL variable, request. The copy operation in the reply activity copies data from
the variable indicated in the fromVariable attribute into the part of the anonymous,
temporary WSDL variable, output.
Example 676
<sequence>
<!-- receive input from requester -->
<receive name="receiveInput" partnerLink="client" portType="tns:Test"
operation="process" variable="input" createInstance="yes"/>
<assign>
<copy>
<from>$input.payload</from>
<to>$request</to>
</copy>
</assign>
<invoke name="invokeDummyService" partnerLink="DummyService"
portType="tns:DummyPortType"
operation="process" outputVariable="response">
<toParts>
<toPart part="payload" fromVariable="request"/>
</toParts>
</invoke>
<assign>
<copy>
<from>$response</from>
<to>$output</to>
</copy>
</assign>
<!-- respond output to requester -->
<reply name="replyOutput" partnerLink="client"
portType="tns:Test" operation="process">
<toParts>
<toPart part="payload" fromVariable="output"/>
</toParts>
</reply>
</sequence>
Example 677
<?xml version="1.0"?>
<definitions name="ch10.3toParts"
targetNamespace="http://samples.otn.com/bpel2.0/ch10.3"
xmlns:tns="http://samples.otn.com/bpel2.0/ch10.3"
xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
xmlns="http://schemas.xmlsoap.org/wsdl/"
>
<types>
<schema attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://samples.otn.com/bpel2.0/ch10.3"
xmlns="http://www.w3.org/2001/XMLSchema">
<element name="input" type="string"/>
<element name="output" type="string"/>
</schema>
</types>
<message name="TestRequestMessage">
<part name="payload" element="tns:input"/>
</message>
<message name="TestResultMessage">
<part name="payload" element="tns:output"/>
</message>
<portType name="Test">
<operation name="process">
<input message="tns:TestRequestMessage"/>
<output message="tns:TestResultMessage"/>
</operation>
</portType>
<plnk:partnerLinkType name="Test">
<plnk:role name="TestProvider" portType="tns:Test"/>
</plnk:partnerLinkType>
</definitions>
Example 678 shows a .bpel file with fromParts elements defined in pick and
invoke activities. This maps to the operation defined in the WSDL file shown in
Example 679. The copy operation in the pick activity retrieves data from the variable
indicated in the toVariable attribute into the part of the anonymous, temporary
WSDL variable, request. The copy operation in the invoke activities retrieves data
from the variable indicated in the toVariable attribute into the part of the
anonymous, temporary WSDL variable, response.
Example 678
<sequence>
<!-- receive input from requester -->
<pick createInstance="yes">
<onMessage partnerLink="client" portType="tns:Test"
operation="process">
<fromParts>
<fromPart part="payload" toVariable="request"/>
</fromParts>
<empty/>
</onMessage>
</pick>
<invoke name="invokeDummyService" partnerLink="DummyService"
portType="tns:DummyPortType"
operation="process" inputVariable="request">
<fromParts>
<fromPart part="payload" toVariable="response"/>
</fromParts>
</invoke>
<assign>
<copy>
<from>concat($response, " ", $response)</from>
<to>$request</to>
6-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</copy>
</assign>
<invoke name="invokeDummyService" partnerLink="DummyService"
portType="tns:DummyPortType"
operation="process2" inputVariable="request">
<fromParts>
<fromPart part="payload" toVariable="response"/>
</fromParts>
</invoke>
<assign>
<copy>
<from>$response</from>
<to>$output.payload</to>
</copy>
</assign>
<!-- respond output to requester -->
<reply name="replyOutput" partnerLink="client"
portType="tns:Test" operation="process" variable="output"/>
</sequence>
Example 679
<?xml version="1.0"?>
<definitions name="BPEL20TestCh10.4"
targetNamespace="http://samples.otn.com/bpel2.0/ch10.4"
xmlns:tns="http://samples.otn.com/bpel2.0/ch10.4"
xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
xmlns="http://schemas.xmlsoap.org/wsdl/"
>
<types>
<schema attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://samples.otn.com/bpel2.0/ch10.4"
xmlns="http://www.w3.org/2001/XMLSchema">
<element name="input" type="string"/>
<element name="output" type="string"/>
</schema>
</types>
<message name="TestRequestMessage">
<part name="payload" element="tns:input"/>
</message>
<message name="TestResultMessage">
<part name="payload" element="tns:output"/>
</message>
<portType name="Test">
<operation name="process">
<input message="tns:TestRequestMessage"/>
<output message="tns:TestResultMessage"/>
</operation>
</portType>
<plnk:partnerLinkType name="Test">
<plnk:role name="TestProvider" portType="tns:Test"/>
</plnk:partnerLinkType>
</definitions>
Import Element
You can also use the import element to import a schema without a namespace, as
shown in Example 681.
Example 681
You can also use the import element to import a schema with a namespace, as shown
in Example 682.
Example 682
If importing XML schema 1.0 documents, this attributes value must be set to
"http://www.w3.org/2001/XMLSchema".
6-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information, see section 5.4 of the Web Services Business Process Execution
Language Specification Version 2.0.
6.20.1 How to Statically Index into an XML Data Sequence That Uses Arrays
The following two examples illustrate how to use XPath functionality to select a data
sequence element when the index of the element you want is known at design time. In
these cases, it is the first element.
In Example 683, addresses[1] selects the first element of the addresses data
sequence:
Example 683
<assign>
<!-- get the first address and assign to variable address -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/autoloan:addresses[1]"/>
<to variable="address"/>
</copy>
</assign>
<assign>
<!-- get the first address's street and assign to street1 -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/autoloan:addresses[position()=1]
/autoloan:street"/>
<to variable="street1"/>
</copy>
</assign>
If you review the definition of the input variable and its payload part in the WSDL file,
you go several levels down before coming to the definition of the addresses field.
There you see the maxOccurs="unbounded" attribute. The two XPath indexing
methods are functionally identical; you can use whichever method you prefer.
<myFavoriteNumbers SOAP-ENC:arrayType="xsd:int2">
<number>3</number>
<number>4</number>
</myFavoriteNumbers>
attributeFormDefault="unqualified" elementFormDefault="unqualified"
targetNamespace="java:services" xmlns:s0="http://schemas.xmlsoap.org/wsdl/"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
Partially-transmitted arrays
Sparse arrays
Multidimensional arrays
2.
Prepare the payload for the invocation. Note that bpelx:append in Example 687
is used to add items into the SOAP array.
Example 687
SOAP Array
<bpws:assign>
<bpws:copy>
<bpws:from variable="input" part="payload" query="/tns:value"/>
<bpws:to variable="request" part="strArray"
query="/strArray/JavaLangstring"/>
</bpws:copy>
</bpws:assign>
<bpws:assign>
<bpelx:append>
6-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Import the following namespace in your WSDL file. Oracle JDeveloper does not
understand the SOAP-ENC tag if the import statement is missing in the WSDL
schema element.
<xs:import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
<assign name="Assign_1">
<copy>
<from>$inputVariable.payload</from>
<to>$Invoke_1_echoArray_InputVariable.strArray/JavaLangstring[1]</to>
</copy>
<extensionAssignOperation>
<bpelx:append>
<bpelx:from variable="Invoke_1_echoArray_InputVariable"
part="strArray">
<bpelx:query>
JavaLangstring[1]
</bpelx:query>
</bpelx:from>
<bpelx:to variable="Invoke_1_echoArray_InputVariable"
part="strArray">
</bpelx:to>
</bpelx:append>
</extensionAssignOperation>
</assign>
Example 689 shows a sample invoke activity with a SOAP-encoded array in a BPEL
2.0 project.
Example 689
<xsd:complexType name="UserObject">
<xsd:sequence>
<xsd:element name="userInformation" nillable="true"
type="n5:ArrayOfKeyValuePair"/>
<xsd:element name="username" nillable="true" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ArrayOfKeyValuePair">
<xsd:complexContent>
<xsd:restriction base="soapenc:Array">
<xsd:attribute ref="soapenc:arrayType"
wsdl:arrayType="n5:KeyValuePair[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="KeyValuePair">
<xsd:sequence>
<xsd:element name="key" nillable="true" type="xsd:string"/>
<xsd:element name="value" nillable="true" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
Example 691 shows how to create and access a SOAP-encoded array in BPEL 1.1.
Example 691
<bpws:copy>
<bpws:from>
<ns1:userInformation soapenc:arrayType="com1:KeyValuePair[1]"
xmlns:ns1="http://www.schematargetnamespace.com/wsdl/Impl/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
<ns1:KeyValuePair
xmlns:ns1="http://www.schematargetnamespace.com/wsdl/Impl/">
<key>testkey</key>
<value>testval1</value>
</ns1:KeyValuePair>
</ns1:userInformation>
</bpws:from>
<bpws:to variable="Inputvar" part="userObject"
query="/userObject/userInformation"/>
</bpws:copy>
<!--Update elements with SOAPENC Array-->
<bpws:copy>
<bpws:from variable="KeyValueVar" part="KeyValuePair"
query="/KeyValuePair/ns2:key"/>
<bpws:to variable="Inputvar" part="userObject
query="//*[local-name()='KeyValuePair'][1]/*[local-name()='key']"/>
</bpws:copy>
<bpws:copy>
<bpws:from variable="KeyValueVar" part="KeyValuePair"
query="/KeyValuePair/client:value"/>
<bpws:to variable="Inputvar" part="userObject"
query="//*[local-name()='KeyValuePair'][1]/*[local-name()='value']"/>
</bpws:copy>
<!-- Append elements within SOAPENC Array -->
<bpelx:append>
6-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<assign>
<copy>
<from expression="count(bpws:getVariableData(outpoint, payload,
'/p:invoice/p:lineItems/p:item')"/>
<to variable="lineItemSize"/>
</copy>
</assign>
Dynamic Indexing
Assume at runtime that the idx integer variable holds 2 as its value. The expression in
Example 693 within the from is equivalent to that shown in Example 694.
Example 694
Equivalent Format
<from expression="bpws:getVariableData('input','payload'
)/p:line-item[2]/p:line-total" />
There are some subtle XPath usage differences, when an XPath used trailing behind
the bwps:getVariableData() function is compared with the one used inside the
function.
Using the same example (where payload is the message part of element
"p:invoice"), if the XPath is used within the getVariableData() function, the
root element name ("/p:invoice") must be specified at the beginning of the XPath.
Example 695 provides details.
Example 695
bpws:getVariableData('input', 'payload',
'/p:invoice/p:line-item[2]/p:line-total')
This is because the node returned by the getVariableData() function is the root
element. Specifying the root element name again in the XPath is redundant and is
incorrect according to standard XPath semantics.
<assign name="assign-3">
<copy>
<from expression="bpws:getVariableData('idx')+1" />
<to variable="idx"/>
</copy>
<bpelx:append>
<bpelx:from variable="partInfoResultVar" part="payload" />
<bpelx:to variable="output" part="payload" />
</bpelx:append>
...
</assign>
The bpelx:append logic in this example appends the payload element of the
partInfoResultVar variable as a child to the payload element of the output
variable. In other words, the payload element of the output variable is used as the
parent element.
6-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 697
<assign>
<!-- initialize "mergedLineItems" variable
to an empty element -->
<copy>
<from> <p:lineItems /> </from>
<to variable="mergedLineItems" />
</copy>
<bpelx:append>
<bpelx:from variable="input" part="payload"
query="/p:invoice/p:lineItems/p:lineitem" />
<bpelx:to variable="mergedLineItems" />
</bpelx:append>
<bpelx:append>
<bpelx:from variable="literalLineItems"
query="/p:lineItems/p:lineitem" />
<bpelx:to variable="mergedLineItems" />
</bpelx:append>
</assign>
append Statement
<bpelx:assign>
<bpelx:append>
<bpelx:from expression="ora:genEmptyElem('p:lineItem',10)" />
<bpelx:to variable="poVar" query="/p:po" />
</bpelx:append>
</bpelx:assign>
ora:genEmptyElem('p:lineItem',10)
== for $i in (1 to 10) return <p:lineItem />
The empty elements generated by this function are typically invalid XML data. You
perform further data initialization after the empty elements are created. Using the
same example above, you can perform the following:
6.20.5 What You May Need to Know About Using the Array Identifier
For processing in Native Format Builder array identifier environments, information is
required about the parent node of a node. Because the reportSAXEvents API is
used, this information is typically not available for outbound message scenarios.
Setting nxsd:useArrayIdentifiers to true in the native schema enables
DOM-parsing to be used for outbound message scenarios. Use this setting cautiously,
as it can lead to slower performance for very large payloads. Example 6100 provides
details.
Example 6100 Array Identifier
<?xml version="1.0" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
elementFormDefault="qualified"
attributeFormDefault="unqualified" nxsd:encoding="US-ASCII"
nxsd:stream="chars" nxsd:version="NXSD" nxsd:useArrayIdentifiers="true">
<xsd:element name="Root-Element">
....
</xsd:element>
</xsd:schema>
6-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<copy>
<from expression="oratext:parseEscapedXML(
'<item xmlns="http://samples.otn.com"
sku="006">
<description>sun ultra sparc VI server
</description>
<price>1000
</price>
<quantity>2
</quantity>
<lineTotal>2000
</lineTotal>
</item>')"/>
<to variable="escapedLineItem"/>
</copy>
</assign>
This is in contrast to RPC-style WSDL files, in which the message is defined with an
XML schema type, as shown in Example 6103:
Example 6103 RPC-Style type Definition
<message name="LoanFlowRequestMessage">
<part name="payload" type="s1:LoanApplicationType"/>
</message>
6-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Create a BPEL source file that declares the header message variables and uses
bpelx:headerVariable to receive the headers, as shown in Example 6108.
<variable name="input"
messageType="tns:HeaderServiceRequestMessage"/>
<variable name="event"
messageType="tns:HeaderServiceEventMessage"/>
<variable name="output"
messageType="tns:HeaderServiceResultMessage"/>
<variable name="customHeader"
messageType="tns:CustomHeaderMessage"/>
</variables>
<sequence>
<!-- receive input from requester -->
<receive name="receiveInput" partnerLink="client"
portType="tns:HeaderService" operation="initiate"
variable="input"
bpelx:headerVariable="customHeader"
createInstance="yes"/>
Define the custom header variable, manipulate it, and send it using
bpelx:inputHeaderVariable, as shown in Example 6109.
...
<!-- initiate the remote process -->
<invoke name="invokeAsyncService"
partnerLink="HeaderService"
portType="services:HeaderService"
bpelx:inputHeaderVariable="customHeader"
operation="initiate"
inputVariable="request"/>
3.
In the Namespace field, enter the extension namespace to declare. This namespace
must be different from the standard BPEL namespace.
4.
If you want the extensions to be recognized by the BPEL process, select the Must
Understand checkbox.
5.
Click OK.
6.
Click Close.
6-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7
7
Partner link
Defines the location and the role of the web services with which the BPEL process
service component connects to perform tasks, and the variables used to carry
information between the web service and the BPEL process service component. A
partner link is required for each web service that the BPEL process service
component calls. You can create partner links in several ways, including the
following:
In the SOA Composite Editor, when you drag a Web Service from the Service
Adapters section of the Component Palette into the Exposed Services or
External References swimlane. For more information, see Section 2.3, "Adding
Service Binding Components" or Section 2.4, "Adding Reference Binding
Components."
7-1
In Oracle BPEL Designer, when you drag a Partner Link icon from the BPEL
Constructs section of the Component Palette into the Partner Links swimlane.
This method is described in this chapter.
Invoke activity
Opens a port in the BPEL process service component to send and receive data. For
example, this port is used to retrieve information verifying that a customer has
acceptable credit using a credit card authorization service. For synchronous
callbacks, only one port is needed for both the send and receive functions.
Drag the necessary partner link, invoke activity, scope activity, and assign activity
into the designer.
3.
7-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
7-3
Note:
The WSDL file defines the interface to your BPEL process service component:
Other parameters
7.2.2.2 Partner Link Type and Port Type in the BPEL Code
The web services CreditCardAuthorizationService.wsdl file contains two
sections that enable the web service to work with BPEL process service components:
partnerLinkType:
Defines the following characteristics of the conversion between a BPEL process
service component and the credit card authorization web service:
portType:
A collection of related operations implemented by a participant in a conversation.
A port type defines which information is passed back and forth, the form of that
information, and so on. A synchronous invocation requires only one port type that
7-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
both initiates the synchronous process and calls back the client with the response.
An asynchronous callback (one in which the reply is not immediate) requires two
port types:
7-5
query="/ns8:AuthInformation/ns8:CCNumber"/>
</copy>
</assign>
<invoke name="InvokeCheckCreditCard"
inputVariable="lCreditCardInput"
outputVariable="lCreditCardOutput"
partnerLink="CreditCardAuthorizationService"
portType="ns2:CreditAuthorizationPort"
operation="AuthorizeCredit"/>
For more information, see Chapter 3, "Introduction to the SOA Sample Application."
From the SOA Infrastructure menu, select SOA Administration > BPEL
Properties.
3.
At the bottom of the BPEL Service Engine Properties page, click More BPEL
Configuration Properties.
4.
Click SyncMaxWaitTime.
5.
6.
Click Apply.
7.
Click Return.
7.3.2 What You May Need to Know About SyncMaxWaitTime and Durable Synchronous
Requests Not Timing Out
The SyncMaxWaitTime property applies to durable synchronous processes that are
called in an asynchronous manner.
Assume you have a BPEL process with the definition shown in Example 76. The
process is not durable because there are no breakpoint activities.
Example 76 Process with No Breakpoint Activities
<receive name="receiveInput" partnerLink="client" variable="input"
createInstance="yes" />
<assign>
...
</assign>
7-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If a Java client or another BPEL process calls this process, the assign activity is
performed and the reply activity sets the output message into a HashMap for the client
(actually the delivery service) to retrieve. Since the reply is the last activity, the thread
returns to the client side and tries to pick up the reply message. Since the reply
message was previously inserted, the client does not wait and returns with the reply.
Assume you have a BPEL process with a breakpoint activity, as shown in Example 77.
Example 77 Process with Breakpoint Activities
<receive name="receiveInput" partnerLink="client" variable="input"
createInstance="yes" />
<assign>
...
</assign>
<wait for="'PT10S'" />
<reply name="replyOutput" partnerLink="client" variable="output" />
7-7
7-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8
Invoking an Asynchronous Web Service
from a BPEL Process
This chapter describes how to configure and invoke an asynchronous web service
from a BPEL process. It also describes how to route callback messages to the correct
endpoint when multiple receive or pick activities use the same partner link, manage
idempotence at the partner link operation level, create a dynamic partner link at
runtime, override security certificates and WSDL files in dynamic partner link
environments, and use WS-Addressing.
This chapter includes the following sections:
Section 8.3, "Routing Callback Messages to the Correct Endpoint when Multiple
Receive or Pick Activities Use the Same Partner Link"
Section 8.5, "Creating a Dynamic Partner Link at Design Time for Use at Runtime"
8-1
web service WSDL file contains the information necessary to request and receive the
necessary information.
For the asynchronous web service, the following actions take place (in order of
priority):
1.
2.
An invoke activity initiates the loan request. The contents of this request are put
into a request variable. This request variable is sent to the asynchronous loan
processor web service.
When the loan request is initiated, a correlation ID unique to the client and partner
link initiating the request is also sent to the loan processor web service. The
correlation ID ensures that the correct loan offer response is returned to the
corresponding loan application requester.
3.
The loan processor web service then sends the correct response to the receive
activity, which has been tracked by the correlation ID.
4.
Subsequent sections in this chapter provide specific details about the asynchronous
functionality.
3.
4.
In the SOA composite application in the SOA Composite Editor, double-click the
BPEL process service component (for this example, the component is named
LoanBroker).
Oracle BPEL Designer appears.
8-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
6.
Drag a Partner Link icon into the right Partner Links swimlane.
The Create Partner Link dialog appears.
7.
Enter the following details to create a partner link and select the loan application
approver web service:
Name
Enter a name for the partner link (for this example, LoanService is entered).
Process
Displays the BPEL process service component name (for this example,
LoanBroker appears).
WSDL URL
Enter the name of the Web Services Description Language (WSDL) file to use.
Click the SOA Resource Lookup icon above this field to locate the correct
WSDL.
Partner Role
Refers to the role of the external source, for example, provider. Select from the
list (for this example, LoanServiceProvider is selected).
My Role
Refers to the role of the BPEL process service component in this interaction.
Select from the list (for this example, LoanServiceRequester is selected).
8.
Click OK.
A new partner link for the loan application approver web service (United Loan)
appears in the swimlane of the designer.
3.
Go to the Structure window. While this example describes variable creation from
the Structure window, you can also create variables by clicking the Add icons to
the right of the Input and Output fields of the Invoke dialog.
4.
5.
In the second Variables folder in the tree, right-click and select Create Variable.
The Create Variable dialog appears.
8-3
6.
Enter the variable name and select Message Type from the options provided:
Type
This option lets you select an XML schema simple type (for example, string,
boolean, and so on).
Message Type
This option enables you to select a WSDL message file definition of a partner
link or of the project WSDL file of the current BPEL process service component
(for example, a response message or a request message). You can specify
variables associated with message types as input or output variables for
invoke, receive, or reply activities.
To display the message type, select the Message Type option, and then select
its Browse icon to display the Type Chooser dialog. From here, expand the
Message Types tree to make your selection. For this example, Message Types
> Partner Links > Loan Service > LoanService.wsdl > Message Types >
LoanServiceRequestMessage is selected.
Element
This option lets you select an XML schema element of the project schema file
or project WSDL file of the current BPEL process service component, or of a
partner link.
7.
Click OK.
8.
9.
In the Invoke dialog, select the partner link from the Partner Link list (for this
example, LoanService is selected) and initiate from the Operation list.
10. To the right of the Input field, click the second icon and select the input variable
8-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Create a variable to hold the receive information by invoking the Create Variable
dialog, as you did in Step 3 through Step 7 of Section 8.2.1.2, "Adding an Invoke
Activity."
Figure 82 shows the Create Variable dialog in BPEL 1.1.
4.
From the Partner Link list, select the partner link (for this example, LoanService is
selected).
5.
From the Operation list, select onResult. Do not select the Create Instance
checkbox.
6.
Select the variable you created in Step 3 through Step 7 of Section 8.2.1.2, "Adding
an Invoke Activity."
7.
Click OK.
The receive activity and the output variable are created. Because the initial receive
activity in the BPEL file (for this example, LoanBroker.bpel) created the initial
8-5
BPEL process service component instance, a second instance does not need to be
created.
Create an initial assign activity for data manipulation in front of the invoke
activity that copies the clients input variable loan application request document
payload into the loan application approver web services request variable
payload.
Create a second assign activity for data manipulation after the receive activity that
copies the loan application approver web services response variable loan
application results payload into the output variable for the client to receive.
The other calls back the client with the asynchronous response
8-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Partner link types in asynchronous services have two roles: one for the web service
provider and one for the client requester.
In the conversation shown in Example 82, the LoanServiceProvider role and
LoanService portType are used for client request messages and the
LoanServiceRequester role and LoanServiceCallback portType are used for
asynchronously returning (calling back) response messages to the client.
Example 82 partnerLinkType Definition
<plnk:partnerLinkType name="LoanService">
<plnk:role name="LoanServiceProvider">
<plnk:portType name="client:LoanService"/>
</plnk:role>
<plnk:role name="LoanServiceRequester">
<plnk:portType name="client:LoanServiceCallback"/>
</plnk:role>
</plnk:partnerLinkType>
Two port types are combined into this single asynchronous BPEL process service
component: portType="services:LoanService" of the invoke activity and
portType="services:LoanServiceCallback" of the receive activity. Port
types are essentially a collection of operations to be performed. For this BPEL process
service component, there are two operations to perform: initiate in the invoke
activity and onResult in the receive activity.
The attribute myRole indicates the role of the client. The attribute partnerRole role
indicates the role of the partner in this conversation. Each partnerLinkType has
myRole and partnerRole attributes in asynchronous processes.
8-7
For more information, see Section 8.2.1.1, "Adding a Partner Link for an Asynchronous
Service" for instructions on creating a partner link.
A receive activity that waits for the asynchronous callback from the loan
application approver web service. The receive activity includes the response
global output variable defined in the variables section. This variable contains
the loan offer response. The receive activity asynchronously waits for a callback
message from a service. While the BPEL process service component is waiting, it is
dehydrated, or compressed and stored, until the callback message arrives.
8-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.2.3 What You May Need to Know About Midprocess Receive Activities Consuming
Messages After Timing Out
A BPEL process can consume midprocess receive activity messages even after the
expiration of a configured timeout on the receive activity, if the exception resulting
from the timeout goes unhandled. In these scenarios, the callback message is
consumed when it is delivered. This is the expected behavior.
Invoking an Asynchronous Web Service from a BPEL Process
8-9
Create a SOA composite application with a client BPEL process and service BPEL
process to exchange a message using asynchronous invoke and receive activities.
Configure a timeout of 30 seconds in the Timeout tab of the receive activity of the
client BPEL process.
Configure a wait activity to wait for five minutes in the service BPEL process.
You may expect that after the timeout occurs, the client BPEL process is marked as
completed in the faulted state instead of remaining in the running state, and the
callback message from the service BPEL process is ignored. However, when the
timeout fault is thrown on the client BPEL process, the client BPEL process remains in
the running state. When the service BPEL process responds five minutes after the
completion of the wait activity, the response is sent back to the client BPEL process
and the response is consumed by the client BPEL process and reconciled with the
running process instance.
8.2.4 What You May Need to Know About Multiple Client Components Invoking a
Composite
If multiple client components invoke a SOA composite application by using its remote
WSDL file, the callback response can only be retrieved by the original client calling the
remote composite if it has a receive activity. When the original client does not have a
receive activity and any of the subsequent clients calling the composite has a receive
activity, the response message is lost. It goes into the recovery state of the original
client process.
This is the expected behavior. This is because the composite being invoked cannot tell
which client has a receive activity or if the client is indeed a BPEL process service
component.
8.2.5 What You May Need to Know About Limitations on BPEL 2.0 IMA Support
Receive activities are a type of inbound message activity (IMA). Other examples of
IMAs are as follows:
The BPEL 2.0 specification allows multiple IMAs to work with each other or with other
IMAs derived from extension activities. To provide for consistent runtime behavior,
the BPEL 2.0 specification allows for correlation sets with the initiate attribute set
to join.
However, Oracle BPEL Process Managers implementation of the BPEL 2.0
specification does not support this behavior. The only way to support multiple IMAs is
by coding them as onMessage branches for a pick activity (that is, setting
createInstance to yes).
Oracle BPEL Process Manager also does not support other forms of multiple IMAs,
such as a flow activity with two branches, each with a receive activity and with
createInstance set to yes and correlation sets with initiate set to join.
As a workaround, you must design two different BPEL processes with the two receive
activities in alternating order, as follows:
8-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The same also applies for any other combination of IMAs, such as a receive activity
and pick activity, or two pick activities.
Routing Callback Messages to the Correct Endpoint when Multiple Receive or Pick Activities Use the Same Partner Link
8.3.1 How to Route Callback Messages to the Correct Endpoint when Multiple Receive
and Pick Activities Use the Same Partner Link
Set this property to the client's replyToAddress on the invoke activity (for the
callback) following the midprocess receive activity. This means that even if the client
sends WS-Addressing replyTo information for a midprocess receive activity, it is not
set on the partner link unless you use an assign activity to set it dynamically.
For example, assume your BPEL process is as shown in Example 810:
Example 810
BPEL Process
Caller
Callee
----------------------------------------------------------<receive>
<receive> Initiate CS1
<invoke>initiate CS1 -------->
<receive> Use CS1
<wait>
<receive>use CS1
<-------<invoke>
<invoke>
To route callback messages to the correct endpoint when multiple receive and
pick activities use the same partner link:
1. Obtain the clients replyToAddress value from the midprocess receive activity.
<receive name="receiveMsgFromAccessor" partnerLink="midprocess_client"
portType="client:mySingletonBPEL" operation="process"
variable="ReceiveMidProcess" createInstance="no">
<bpelx:property name="replyToAddress" variable="var_replyToAddress"/>
<correlations>
<correlation set="<YourCorrset>" initiate="no"/>
</correlations>
</receive>
2.
On the invoke activity (for the callback), click the Properties tab.
3.
4.
5.
6.
Enter the variable name as the value (for this example, var_replyToAddress
from Step 1 is entered), and click OK.
7.
8-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.
9.
For more information about the idempotent deployment descriptor property, see
Section 12.10.6, "What You May Need to Know About the idempotent Property and
Fault Handling" and Section C.1, "Introduction to Deployment Descriptor Properties."
3.
4.
Click Apply.
5.
Click OK.
For more information about idempotence and the idempotent property, see
Section C.1, "Introduction to Deployment Descriptor Properties."
8.5 Creating a Dynamic Partner Link at Design Time for Use at Runtime
When you design a SOA composite application, you can face the following challenges:
The dynamic partner link feature enables you to dynamically assign an endpoint
reference to a partner link for use at runtime in BPEL versions 1.1 and 2.0. The
dynamic partner link provides conditions, similar to a switch activity, that are
evaluated at runtime.
8-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.5.1 How To Create a Dynamic Partner Link at Design Time for Use at Runtime
To create a dynamic partner link at design time for use at runtime:
1. Create a WSDL file that contains multiple services that use the same portType.
<service name="AmericanLoan">
<port name="LoanServicePort" binding="tns:LoanServiceBinding">
<soap:address location="http://localhost:9700/orabpel/default/AmericanLoan"/>
</port>
</service>
<service name="AlliedLoan">
<port name="LoanServicePort" binding="tns:LoanServiceBinding">
<soap:address location="http://localhost:9700/orabpel/default/AlliedLoan"/>
</port>
</service>
<service name="AcmeLoan">
<port name="LoanServicePort" binding="tns:LoanServiceBinding">
<soap:address location="http://localhost:9700/orabpel/default/AcmeLoan"/>
</port>
</service>
2.
Drag a Web Service binding component into the External References swim lane
of the SOA Composite Editor.
The Create Web Service dialog appears.
3.
Notes:
4.
5.
6.
7.
Above the target partner link, select the XML Fragment icon, as shown in
Figure 85. If you are using BPEL 2.0, drag the Literal icon.
8.
9.
Assign an XML fragment containing the endpoint reference to the partner link,
and click OK. Figure 86 provides details.
When complete, the BPEL file contains one of the services defined in the WSDL.
<copy>
<from>
<EndpointReference
xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing">
<Address>http://myhost.us.example.com:9700/orabpel/default/AlliedLoan</Address>
</EndpointReference>
</from>
<to partnerLink="LoanService"/>
</copy>
8-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
each web service. You can specify a keystore recipient alias value to override the
security certificate in the WSDL file of the web service.
To override security certificates when invoking partner links:
1. Define a variable of type string (for example, KEYSTORE_RECIPIENT_ALIAS).
Figure 87 provides details.
Figure 87 Variable Definition of KEYSTORE_RECIPIENT_ALIAS
2.
In the Copy Rules tab of an assign activity, assign orakey to the variable
KEYSTORE_RECIPIENT_ALIAS. Figure 88 provides details.
3.
In the invoke activity that invokes the partner link for the web service, click the
Properties tab.
4.
5.
6.
Click the Browse (...) icon to display the Adapter Property Value dialog.
7.
Click the Browse icon to display the Variable XPath Builder dialog.
8.
9.
8-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<to partnerLink="Service"/>
</copy>
</assign>
<assign name="AssignAlias">
<copy>
<from expression='"orakey"'/>
<to variable="KEYSTORE_RECIPIENT_ALIAS"/>
</copy>
</assign>
<invoke name="Invoke"
inputVariable="Invoke_InputVariable"
partnerLink="Service"
portType="ns1:ServiceBPELProcess"
operation="process"
bpelx:invokeAsDetail="no">
<bpelx:inputProperty name="endpointURI"
variable="inputVariable"
part="payload"
query="/client:process/client:input"/>
<bpelx:inputProperty name="keystore.recipient.alias"
variable="KEYSTORE_RECIPIENT_ALIAS"/>
</invoke>
You need to integrate with services that use message protection security policies.
The WSDL may contain important information such as the certificate used for
message encryption.
The normalized message property endpointWSDL enables you to specify the WSDL
file of the dynamic partner link. You must specify the entire WSDL dynamically
instead of just the endpoint. This enables it to be passed to Oracle Web Services
Manager (Oracle WSM), which can then retrieve the correct service certificate from the
specified WSDL.
The certificate in the WSDL file is ignored in the following cases:
1.
2.
In the Copy Rules tab of an assign activity, assign the WSDL to the_wsdl_var.
3.
In the invoke activity that invokes the partner link, click the Properties tab.
4.
5.
6.
Click the Browse (...) icon to display the Adapter Property Value dialog.
7.
Click the Browse icon to display the Variable XPath Builder dialog.
8.
Select the_wsdl_var as the variable, and click OK. This value specifies the WSDL
of the dynamic partner link. Figure 810 provides details.
8-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<bpelx:inputProperty name="endpointWSDL"
variable="the_wsdl_var"/>
</invoke>
WSDL
LoanService
PartnerLink
loanApp
<variable>
Initiate
service
<invoke>
[2.05] receive
[2.06] process
[2.22] callback
Initiate Port
d3
Async
Loan
Processor
Service
d3
loanOffer
<variable>
Wait for
callback
<receive>
d3
Callback Port
d4
WS-Addressing Header:
. correlation id (relatesTo)
Note 1: The correlation id
allows the BPEL service
engine to know which
instance of the process is
waiting for this callback
message.
Note 2: The alternative
approach is to use
content-based correlation
using <correlationSet>.
Figure 811 shows how messages are passed along with WS headers so that the
response can be sent to the correct destination.
The example in this chapter uses WS-Addressing for correlation. To view the
messages, you can use TCP tunneling, which is described in Section 8.8.1.1, "Using
TCP Tunneling to View Messages Exchanged Between Programs."
WS-Addressing defines the following information typically provided by transport
protocols and messaging systems. This information is processed independently of the
transport or application:
Conversation ID
Use TCP tunneling to view SOAP messages exchanged between the BPEL process
service component flow and the web service (including those containing the
correlation ID). You can see the exact SOAP messages that are sent to, or received
from, services with which a BPEL process service component flow communicates.
You insert a software listener between your BPEL process service component flow
and the web service. Your BPEL process service component flow communicates
with the listener (called a TCP tunnel). The listener forwards your messages to the
web service, and also displays them. Responses from the web service are returned
to the tunnel, which displays and forwards them back to the BPEL process service
component.
Visit the following URL for instructions on how to download and install Axis TCP
Monitor (tcpmon)
http://ws.apache.org/commons/tcpmon/
2.
3.
4.
Start tcpmon:
C:\...\> java org.apache.axis.utils.tcpmon localport remoteHost
8-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
port_on_which_remote_server_is_running
5.
6.
From the operating system command prompt, compile and deploy the process
with ant.
The same technique can see SOAP messages passed to invoke a BPEL process
service component as a web service from another tool kit such as Axis or .NET.
8.8.1.1.2 Setting Up a TCP Listener for Asynchronous Services Follow these steps to set up
a TCP listener to display the SOAP messages for callbacks from asynchronous services:
1.
Start a TCP listener to listen on a port and send the Oracle BPEL Process Manager
port.
a.
b.
From the SOA Infrastructure menu, select SOA Administration > Common
Properties.
c.
Specify the value for Callback Server URL. This URL is sent by the server as
part of the asynchronous callback address to the invoker.
2.
From the SOA Infrastructure menu, select Administration > System MBean
Browser.
3.
Expand Application Defined MBeans > oracle.soa.config > Server : soa_server >
SCAComposite.
where soa_server is the specific server instance name (for example, AdminServer).
All the SOA composite applications deployed on the server appear.
4.
Follow these steps to set this property on a composite application. This action
enables it to apply to all bindings in the composite application.
a.
b.
c.
d.
e.
Expand the newly added Element_number (appears at the end of the list).
where number is the next sequential number beyond the last property. For
example, if the property list contains twelve elements, adding a new property
causes Element_13 to be displayed.
f.
g.
h.
i.
j.
k.
l.
Note:
5.
6.
b.
Click WSBinding.
c.
Initiate any flow that invokes asynchronous web services. You can combine this
with the synchronous TCP tunneling configuration to send a service initiation
request through your first TCP tunnel.
The callbacks from the asynchronous services are shown in the TCP listener.
If you are an Oracle JDeveloper user, you can also use the built-in Packet Monitor to
see SOAP messages for both synchronous and asynchronous services.
8-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9
Using Correlation Sets and Message
Aggregation
9
This chapter describes how to use correlation sets to ensure that asynchronous
callbacks locate the appropriate client. It also describes how to use aggregation
patterns to route messages to the same instance.
This chapter includes the following sections:
3.
5.
Accept the default values for all remaining settings, and click Next.
6.
7.
Accept the default values for all remaining settings, and click Next.
8.
In the Composite Template section, select Composite With BPEL Process, and
click Finish.
The Create BPEL Process dialog appears.
9.
Table 91
Field
Value
Name
Template
10. Accept the default values for all remaining settings, and click OK.
You create an initial partner link with an adapter service for reading a loan
application.
You create a second partner link with an adapter service for reading an application
response.
You create a third partner link with an adapter service for reading a customer
response.
9.1.1.2.1
1.
2.
3.
Drag an initial Partner Link activity into the right swimlane of the designer.
4.
Click the third icon at the top (the Service Wizard icon). This starts the Adapter
Configuration Wizard, as shown in Figure 91.
9-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
In the Configure Service or Adapter dialog, select File Adapter and click OK.
6.
7.
In the Service Name field of the Service Name dialog, enter a name (for this
example, FirstReceive is entered) and click Next.
8.
In the Adapter Interface dialog, accept the default settings and click Next.
9.
In the Operation dialog, select Read File as the Operation Type and click Next.
The Operation Name field is automatically filled in with Read.
10. Above the Directory for Incoming Files (physical path) field, click Browse.
11. Select a directory from which to read files (for this example,
C:\files\receiveprocess\FirstInputDir is selected).
12. Click Select.
13. Click Next.
14. In the File Filtering dialog, enter appropriate file filtering parameters.
15. Click Next.
16. In the File Polling dialog, enter appropriate file polling parameters.
17. Click Next.
18. In the Messages dialog, click Browse next to the URL field to display the Type
Chooser dialog.
19. Select an appropriate XSD schema file. For this example, Book1_4.xsd is the
The URL field (Book1_4.xsd for this example) and the Schema Element field
(LoanAppl for this example) are filled in.
21. Click Next.
22. Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically
completed. The dialog looks as shown in Table 92:
Table 92
Field
Value
Name
FirstReceive
WSDL URL
directory_path/FirstReceive.wsdl
Read_plt
Partner Role
Leave unspecified.
My Role
Read_role
9.1.1.2.2
At the top, click the third icon (the Service Wizard icon).
3.
In the Configure Service or Adapter dialog, select File Adapter and click OK.
4.
5.
In the Adapter Type dialog, select File Adapter and click Next.
6.
In the Service Name field of the Service Name dialog, enter a name (for this
example, SecondFileRead is entered) and click Next. This name must be unique
from the one you entered in Step 7 of Section 9.1.1.2.1, "Creating an Initial Partner
Link and File Adapter Service."
7.
In the Adapter Interface dialog, accept the default settings and click Next.
8.
9.
In the Operation Name field, change the name (for this example, Read1 is entered).
C:\files\receiveprocess\SecondInputDir is entered).
14. Click Select.
15. Click Next.
16. Enter appropriate file filtering parameters in the File Filtering dialog.
17. Click Next.
18. Enter appropriate file polling parameters in the File Polling dialog.
19. Click Next.
20. Next to the URL field in the Messages dialog, click Browse to display the Type
Chooser dialog.
21. Select an appropriate XSD schema file. For this example, Book1_5.xsd is the
The URL field (Book1_5.xsd for this example) and the Schema Element field
(LoanAppResponse for this example) are filled in.
23. Click Next.
24. Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically
completed. The dialog looks as shown in Table 93:
9-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 93
Field
Value
Name
SecondReceive
WSDL URL
directory_path/SecondFileRead.wsdl
Read1_plt
Partner Role
Leave unspecified.
My Role
Read1_role
9.1.1.2.3
1.
2.
At the top, click the third icon (the Service Wizard icon).
3.
In the Configure Service or Adapter dialog, select File Adapter and click OK.
4.
5.
In the Adapter Type dialog, select File Adapter and click Next.
6.
In the Service Name field of the Service Name dialog, enter a name (for this
example, ThirdFileRead is entered) and click Next. This name must be unique
from the one you entered in Step 7 of Section 9.1.1.2.1, "Creating an Initial Partner
Link and File Adapter Service" and Step 6 of Section 9.1.1.2.2, "Creating a Second
Partner Link and File Adapter Service."
7.
In the Adapter Interface dialog, accept the default settings and click Next.
8.
9.
In the Operation Name field, change the name (for this example, Read2 is entered).
This name must be unique.
C:\files\receiveprocess\ThirdInputDir is entered).
14. Click Select.
15. Click Next.
16. Enter appropriate file filtering parameters in the File Filtering dialog.
17. Click Next.
18. Enter appropriate file polling parameters in the File Polling dialog.
19. Click Next.
20. Next to the URL field in the Messages dialog, click Browse to display the Type
Chooser dialog.
21. Select an appropriate XSD schema file. For this example, Book1_6.xsd is the
The URL field (Book1_6.xsd for this example) and the Schema Element field
(CustResponse for this example) are filled in.
23. Click Next.
24. Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically
completed. The dialog looks as shown in Table 94:
Table 94
Field
Value
Name
ThirdReceive
WSDL URL
directory_path/ThirdFileRead.wsdl
Read2_plt
Partner Role
Leave unspecified.
My Role
Read2_role
Drag a Receive activity beneath the receiveInput receive activity in the designer.
3.
4.
Enter the details described in Table 95 to associate the first partner link
(FirstReceive) with the first receive activity:
Table 95
Field
Value
Name
receiveFirst
Partner Link
FirstReceive
Create Instance
To the right of the Variable field, click the first icon. This is the automatic variable
creation icon.
6.
9-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Ensure that you selected the Create Instance checkbox, as described in Step 4.
8.
Click OK.
9.1.1.3.2
3.
Enter the details described in Table 96 to associate the second partner link
(SecondReceive) with the second receive activity:
Table 96
Field
Value
Name
receiveSecond
Partner Link
SecondFileRead
Create Instance
5.
6.
Click OK.
9.1.1.3.3
3.
Enter the details described in Table 97 to associate the third partner link
(ThirdReceive) with the third receive activity:
Table 97
Field
Value
Name
receiveThird
Partner Link
ThirdFileRead
Create Instance
5.
6.
Click OK.
Each receive activity is now associated with a specific partner link.
In the second Correlation Sets folder, right-click and select Create Correlation Set.
3.
In the Name field of the Create Correlation Set dialog, enter CorrelationSet1.
4.
In the Properties section, click the Add icon to display the Property Chooser
dialog.
5.
Select Properties, then click the Add icon (first icon at the top) to display the
Create Property dialog.
6.
7.
8.
9.
Click OK in each dialog to close the Create Property dialog, the Property Chooser
dialog, and the Create Correlation Set dialog.
9.1.1.4.2
Right-click the Correlation Sets folder and select Create Correlation Set.
3.
In the Name field of the Create Correlation Set dialog, enter CorrelationSet2.
4.
In the Properties section, click the Add icon to display the Property Chooser
dialog.
5.
Select Properties, then click the Add icon to display the Create Property dialog.
6.
7.
8.
9.
Click OK in each dialog to close the Create Property dialog, the Property Chooser
dialog, and the Create Correlation Set dialog.
9-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For the first correlated group, the first and second receive activities are correlated
with the CorrelationSet1 correlation set.
For the second correlated group, the second and third receive activities are
correlated with the CorrelationSet2 correlation set.
9.1.1.5.1
3.
Click the Add icon to display the correlation set dropdown list.
4.
Select CorrelationSet1.
5.
Click the Initiate column to display a dropdown list, and select yes. When set to
yes, the set is initiated with the values of the properties occurring in the message
being exchanged.
6.
Click OK.
9.1.1.5.2
1.
2.
3.
Click the Add icon to display the correlation set dropdown list.
4.
5.
Click the Initiate column to display a dropdown list, and select yes.
6.
7.
Click OK.
8.
Click the Initiate column to display a dropdown list, and select no for
CorrelationSet1.
9.
Click OK.
This groups the first and second receive activities into a correlated group.
9.1.1.5.3
3.
4.
Select CorrelationSet2.
5.
6.
Click OK.
This groups the second and third receive activities into a second correlated group.
You create the following two property aliases for the NameCorr correlation set:
Map NameCorr to the LoanAppl message type part of the receiveFirst receive
activity. This receive activity is associated with the FirstReceive partner link
(defined by the FirstReceive.wsdl file).
Map NameCorr to the incoming LoanAppResponse message type part of the
receiveSecond receive activity. This receive activity is associated with the
SecondReceive partner link (defined by the SecondFileRead.wsdl file).
1.
2.
3.
4.
Expand and select Message Types > Partner Link > FirstReceive >
FirstReceive.wsdl > Message Types > LoanAppl_msg > Part - LoanAppl.
5.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns2:LoanAppl/ns2:Name
6.
Click OK.
7.
Repeat Step 1 through Step 3 to create a second property alias for NameCorr.
8.
Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl
> Message Types > LoanAppResponse_msg > Part - LoanAppResponse.
9.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns4:LoanAppResponse/ns4:APR
9.1.1.6.2
You create the following two property aliases for the IDCorr correlation set:
1.
9-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
4.
Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl
> Message Types > LoanAppResponse_msg > Part - LoanAppResponse.
5.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns4:LoanAppResponse/ns4:APR
6.
Click OK.
7.
Repeat Step 1 through Step 3 to create a second property alias for IDCorr.
8.
Expand and select Message Types > Project WSDL Files > ThirdFileRead.wsdl >
Message Types > CustResponse_msg > Part - CustResponse.
9.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns6:CustResponse/ns6:APR
Because the BPEL process service component is not created as a web services
provider in this example, the MyCorrelationSet.wsdl file is not referenced in the
BPEL process service component. Therefore, you must import the
MyCorrelationSet.wsdl file inside the FirstReceive.wsdl file to reference the
correlation sets defined in the former WSDL.
<import namespace="http://xmlns.oracle.com/MyCorrelationSet"
location="MyCorrelationSet.wsdl"/>
9.1.2 What You May Need to Know About Conversion IDs and Different Composite
Revisions
Do not use the same conversion ID for different revisions of a SOA composite
application. When correlation sets are used in a BPEL process, you have explicit
control over the conversation ID value. Oracle SOA Suite does not interfere or add
restrictions on conversation ID value generation. This situation means that even
though it appears that Oracle SOA Suite is generating the same conversation ID for
different revisions, you actually control this behavior. Oracle SOA Suite suite does not
restrict you from using the same conversation ID for different instances of different
revisions.
If you do not use correlation sets, the conversation ID generated is unique and this is
not a problem because Oracle SOA Suite decides which conversation ID to generate,
and not you.
Oracle SOA Suite does not execute a revision check for callback routing. Routing of
callback messages is only based on the following:
Conversation ID: This is calculated based on the input value and correlation set. If
you use the same correlation set for two revisions of processes and enter the same
input when creating an instance, both revisions subscribe using the same
conversation ID. This causes confusion when a callback for one revision is
delivered to another revision.
BPEL service component name (is also the same for both revisions).
An entry receive activity named receive_1 (on which a correlation set is used)
2.
Create an instance of revision 1.0, which is using a correlation set, and input a
value of 123, which generates conv_id = "123".
9-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This process now invokes a web service through a one-way invoke activity and
then waits on the receive_2 activity for a callback to arrive.
3.
Deploy revision 2.0 of composite_A, which now becomes the default revision.
A web service sends a callback for the instance for revision 1.0. However, as a part
of its URL, it does not specify the revision number. You typically create a callback
so that the URL does not use the revision number. This is because web services are
external and you cannot change web service settings to continue using a revision
tag because it is internal to Oracle SOA Suite and is a concept that the external
world does not understand.
Since a revision number is not specified, the SOA server assumes that the revision
number must be 2.0 and, if the routing of the callback takes the revision number
into account, it cannot forward this callback intended for 1.0 to the correct revision
1.0. Instead, it attempts to route it to the default revision of 2.0, which does not
have any instance waiting for the callback.
You cannot route callback messages based on revisions. You only receive the
option to route callback messages based on the conversion ID (if the correlation set
is not used, then even this is not under your control), operation name, and
component name.
For these reasons, different instances must use different conversation IDs (which
means different input is used for creating a conversion ID) to avoid confusion, and
routing should be solely based on a conversation ID.
9.1.3 What You May Need to Know About Setting Correlations for an IMA Using a
fromParts Element With Multiple Parts
Assume you have the following scenario:
A BPEL 2.0 process with a WSDL message type that has multiple parts that are
identical in type.
A property alias has been defined based on the element type of the above part.
For a process that has an inbound message activity (IMA) (for example, a receive
activity, onMessage branch of a scope or pick activity, or onEvent branch of a scope
activity in BPEL 2.0) that uses the fromParts element with fromParts defined for each
part, correlations cannot be defined because the runtime environment cannot
determine the part to which to apply the property alias.
For more information about mapping WSDL message parts with the toParts and
fromParts elements, see Section 6.18, "Mapping WSDL Message Parts in BPEL 2.0."
Notes:
1.
2.
Go to the Property Inspector in the lower right corner of Oracle JDeveloper. If the
Property Inspector is not displayed, select Property Inspector from the View main
menu.
3.
In the Properties section, click the Add icon, as shown in Figure 93.
9-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
Table 98
Value
Description
Example
true
false
6.
Click OK.
9.2.2 How to Use the Same Operation in Entry and Midprocess Receive Activities
Assume you create a correlation set as shown in Example 91. All messages to Oracle
BPEL Process Manager are routed to the same operation name. The messages have the
same correlation ID. The interface WSDL does not differentiate between the entry
activity (receiveInput) and the midprocess receive activity (Continue_Receive). All
messages are processed using the initiate operation. A single instance is created to
which to route all messages.
This differs from releases before 11g Release 1 11.1.1.6, in which you needed to define
different operation names on the same partner link. The process had to expose two
operations and the caller had to choose the correct operation name.
Example 91 Correlation with Same Operation in Entry and Midprocess Receive
Activities
<receive name="receiveInput" partnerLink="client" portType="client:BPELProcess1"
operation="initiate" variable="inputVariable" createInstance="yes">
<correlations>
<correlation initiate="yes" set="CorrelationSet_1"/>
</correlations>
</receive>
<!-- Asynchronous callback to the requester. (Note: the callback location and
correlation id is transparently handled using WS-addressing.) -->
<assign name="Assign_1">
<copy>
<from variable="inputVariable" part="payload"
query="/client:BPELProcess1ProcessRequest/client:input"/>
<to variable="Invoke_1_initiate_InputVariable" part="payload"
query="/ns1:BPELProcess2ProcessRequest/ns1:input"/>
</copy>
</assign>
<receive name="Continue_Receive" partnerLink="client"
portType="client:BPELProcess1" operation="initiate" variable="inputVariable"
createInstance="no">
<correlations>
<correlation initiate="no" set="CorrelationSet_1"/>
</correlations>
</receive>
For event delivery network (EDN) business events, you substitute the operation
attribute with bpelx:eventName in both the entry and midprocess receive activities.
bpelx:eventName="ns3:initiateEvent"/>
Conversation ID
Domain name
State
Received date
CI key
9-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Primary key
This information can be deleted from this table with the purge scripts or from the
Delete With Options dialog in Oracle Enterprise Manager Fusion Middleware Control.
For more information about both of these options, see the Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
9.2.3 How to Route a Message to a New or Existing Instance when Using Correlation
Sets
For a BPEL process using correlation sets, the correct routing is performed. The
message can be either of the following:
Figure 95 shows entry and midprocess receive activities using the same operation
(process).
Figure 95 Routing a New Message to a New or Existing Instance
Example 92 provides an example of the entry and midprocess receive activities using
the same operation (process).
Example 92 Routing a New Message to a New or Existing Instance
<receive name="receiveInput" partnerLink="client" portType="client:BPELProcess1"
operation="process" variable="inputVariable" createInstance="yes">
<correlations>
<correlation initiate="yes" set="CorrelationSet_1"/>
</correlations>
</receive>
<!-- some business logic -->
<while name="While_1" condition=*loop for 3 iterations*>
<sequence name="Sequence_1">
<receive name="Continue_Receive" partnerLink="client"
portType="client:BPELProcess1" operation="process" variable="inputVariable"
createInstance="no">
<correlations>
<correlation initiate="no" set="CorrelationSet_1"/>
</correlations>
</receive>
<!-- some business logic -->
</sequence>
</while>
In the initial scenario in Example 92, the following actions occur in BPEL process P1:
Assume now that additional messages are routed, which can potentially cause race
conditions to occur. Table 99 provides details.
9-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 99
Scenario Description
Marked as
Marked as
Invoke Message Callback Message
Message 1
Message 2
Message 5
Message 3
Message 4
Message 6
Message 7
Message 8
Message 1
Message 2
Message 6
Message 3
Message 4
Message 5
Message 7
Message 8
Message 1
Message 2
Message 6
Message 3
Message 4
Message 5
9-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
10
10
The two warehouses return their bids for the order to the flow activity. Here, two
asynchronous callbacks execute in parallel. One callback does not have to wait for the
other to complete first. Each response is stored in a different global variable.
WSDL
<flow>
<sequence>
<sequence>
Initiate
service
<invoke>
Initiate
service
<invoke>
Wait for
callback
<receive>
Wait for
callback
<receive>
PartnerSupplierMediator
InternalWarehouseService
10.1.1 What You May Need to Know About the Execution of Parallel Flow Branches in a
Single Thread
Branches in flow, flowN, and forEach activities are executed serially in a single thread
(that is, the Nth branch is executed only after N-1 execution has completed). Execution
is not completely parallel. This is because the branches do not execute in concurrent
threads in this mode. Instead, one thread starts executing a flow branch until it reaches
a blocking activity (for example, an synchronous invoke). At this point, a new thread is
created that starts executing the other branch, and the process continues. This creates
the impression that the flow branches are executing in parallel. In this mode, however,
if the flow branches do not define a blocking activity, the branches still execute serially.
This design is intended for several reasons:
To prevent you from accidentally spawning too many threads and overloading the
system, single threading is the default method. However, you can tune threads in
other places, such as adapter polling threads, BPEL process invoke/service engine
threads, and Oracle WebLogic Server work managers.
The BPEL process specification does not provide a mechanism to ensure the thread
safety of BPEL variables (that is, a lack of a synchronized qualifier such as in Java),
which is necessary for true multithreaded programming.
The implication of transaction rollbacks in one of the branches is undefined.
10-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
completes when all activities in the flow have finished processing. Completion of this
activity includes the possibility that it can be skipped if its enabling condition is false.
Branches in a flow activity are executed serially in a single
thread. For more information, see Section 10.1.1, "What You May Need
to Know About the Execution of Parallel Flow Branches in a Single
Thread."
Note:
3.
Click the + sign to expand the flow activity, as shown in Figure 102.
The flow activity initially includes two branches, each with a box for functional
elements. Populate these boxes as you do a scope activity, either by building a
function or dragging activities into the boxes. You can add additional branches by
highlighting the flow activity and clicking the Add Sequence icon.
4.
Drag and define additional activities on each side of the flow to invoke multiple
services at the same time. Figure 103 provides details.
When complete, flow activity design can look as shown in Figure 104. This
example shows the Retrieve_QuotesFromSuppliers flow activity of the Fusion
Order Demo application. Two branches are defined for receiving bids: one for
InternalWarehouseService and the other for PartnerSupplierMediator.
Flow Activity
<flow name="Retrieve_QuotesFromSuppliers">
<sequence name="Sequence_4">
<assign name="Assign_InternalWarehouseRequest">
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO/ns4:OrderId"/>
<to variable="lInternalWarehouseInputVariable"
part="payload"
query="/ns1:WarehouseRequest/ns1:orderId"/>
</copy>
</assign>
<invoke name="Invoke_InternalWarehouse"
inputVariable="lInternalWarehouseInputVariable"
partnerLink="InternalWarehouseService"
portType="ns1:InternalWarehouseService"
operation="process"/>
<receive name="Receive_InternalWarehouse"
createInstance="no"
variable="lInternalWarehouseResponseVariable"
partnerLink="InternalWarehouseService"
portType="ns1:InternalWarehouseServiceCallback"
operation="processResponse"/>
<assign name="Assign_InterWHResponse">
<bpelx:append>
10-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<bpelx:from variable="lInternalWarehouseResponseVariable"
part="payload"
query="/ns1:WarehouseResponse"/>
<bpelx:to variable="gWarehouseQuotes"
query="/ns1:WarehouseList"/>
</bpelx:append>
</assign>
</sequence>
<sequence name="Sequence_4">
<assign name="Assign_PartnerRequest">
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO"/>
<to variable="lPartnerSupplierInputVariable"
part="request" query="/ns4:orderInfoVOSDO"/>
</copy>
</assign>
<invoke name="Invoke_PartnerSupplier"
partnerLink="PartnerSupplierMediator"
portType="ns15:execute_ptt" operation="execute"
inputVariable="lPartnerSupplierInputVariable"/>
<receive name="Receive_PartnerResponse"
createInstance="no"
variable="lPartnerResponseVariable"
partnerLink="PartnerSupplierMediator"
portType="ns15:callback_ptt" operation="callback"/>
<assign name="Assign_PartnerWHResponse">
<bpelx:append>
<bpelx:from variable="lPartnerResponseVariable"
part="callback"
query="/ns1:WarehouseResponse"/>
<bpelx:to variable="gWarehouseQuotes"
query="/ns1:WarehouseList"/>
</bpelx:append>
</assign>
</sequence>
</flow>
<flow ...>
<links>
<link name="verifyFlight-To-scheduleFlight" />
</links>
<documentation>
Verify the availability of a flight, hotel, and rental car in parallel
</documentation>
<invoke name="verifyFlight" ...>
<sources>
<source linkName="verifyFlight-To-scheduleFlight" />
</sources>
</invoke>
<invoke name="verifyHotel" ... />
<invoke name="verifyCarRental" ... />
<invoke name="scheduleFlight" ...>
<targets>
<target linkName="verifyFlight-To-scheduleFlight" />
</targets>
</invoke>
</flow>
Example 102 provides an example of link syntax in BPEL version 2.0. The link syntax
between BPEL version 1.1 and BPEL version 2.0 is slightly different.
<flow>
<links>
<link name="XtoY"/>
<link name="CtoD"/>
</links>
<sequence name="X">
<source linkName="XtoY"/>
<invoke name="A" .../>
<invoke name="B" .../>
</sequence>
<sequence name"Y">
<target linkName="XtoY"/>
<receive name="C" ...>
<source linkName="CtoD"/>
</receive>
<invoke name="E" .../>
</sequence>
<invoke partnerLink="D" ...>
<target linkName="CtoD"/>
</invoke>
</flow>
<flow>
<links>
<link name="AtoB"/>
</links>
<assign name="B">
<targets>
<target linkName="AtoB"/>
</targets>
<copy>
<from>concat($output.payload,
'B')</from>
<to>$output.payload</to>
</copy>
</assign>
<assign name="A">
<sources>
<source linkName="AtoB"/>
</sources>
<copy>
<from>concat($output.payload,
'A')</from>
<to>$output.payload</to>
</copy>
</assign>
</flow>
10-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
1.
Create a flow activity. For information, see Section 10.2.1, "How to Create a Parallel
Flow."
2.
In the General tab of the Flow activity, click the Add icon.
3.
4.
5.
Drag appropriate activities into the flow activity to define as the source with the
same link name as defined in Step 3. The value of the link name of the source and
target must be the same as the link name declared in the flow activity. For this
example, an assign activity named A is defined as the source in Figure 106.
Each source activity can specify an optional Transition Condition as a safe guard
for following the specified link. Click the row in this column to invoke the
Browser icon for accessing the Expression Builder dialog for creating a condition.
If the Transition Condition column is left blank, it is assumed to evaluate to true.
6.
7.
8.
Drag an additional activity into the flow activity to define as the target with the
same link name as defined in Step 3. For this example, another assign activity
named B is defined as the target in Figure 107.
10-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
When complete, design can appear similar to that shown in Figure 108.
Figure 108 Three Flow Activities Synchronized with Links
10.2.5 What Happens When You Create Synchronization Between Activities Within a
Flow Activity
Example 103 shows the .bpel file after design is complete for three flow activities
with links for synchronizing activity execution.
Example 103
10-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<from>concat($output.payload, 'A')</from>
<to>$output.payload</to>
</copy>
</assign>
</scope>
<assign name="B">
<targets>
<target linkName="AtoB"/>
</targets>
<copy>
<from>concat($output.payload, 'B')</from>
<to>$output.payload</to>
</copy>
</assign>
</flow>
<!-- link between composite activities -->
<flow name=Flow_3>
<links>
<link name="AtoB"/>
</links>
<scope name="scope2">
<sources>
<source linkName="AtoB"/>
</sources>
<assign name="A">
<copy>
<from>concat($output.payload, 'A')</from>
<to>$output.payload</to>
</copy>
</assign>
</scope>
<sequence name="Sequence_1>
<targets>
<target linkName="AtoB"/>
</targets>
<assign name="B">
<copy>
<from>concat($output.payload, 'B')</from>
<to>$output.payload</to>
</copy>
</assign>
</sequence>
</flow>
</sequence>
10.2.6 What You May Need to Know About Join Conditions in Target Activities
You can specify an optional join condition in target activities. The value of the join
condition is a boolean expression. If a join condition is not specified, the join condition
is the disjunction (that is, a logical OR operation) of the link status of all incoming links
of this activity.
Oracle BPEL Designer does not provide design support for adding join conditions. To
add a join condition, you must manually add the condition to the .bpel file in Source
view in Oracle BPEL Designer.
Example 104 provides an example of a join condition.
Example 104
<flow>
<links>
<link name="linkStatus2"/>
</links>
<empty name="E2">
<sources>
<source linkName="linkStatus2">
<transitionCondition>false()</transitionCondition>
</source>
</sources>
</empty>
<empty name="E2">
<targets>
<joinCondition>bpws:getLinkStatus('linkStatus2')=true()</joinCondition>
<target linkName="linkStatus2"/>
</targets>
</empty>
</flow>
10.3.1 Customizing the Number of Flow Activities with the flowN Activity in BPEL 1.1
In the flow activity, the BPEL code determines the number of parallel branches.
However, often the number of branches required is different depending on the
available information. The flowN activity creates multiple flows equal to the value of
N, which is defined at runtime based on the data available and logic within the
process. An index variable increments each time a new branch is created, until the
index variable reaches the value of N.
The flowN activity performs activities on an arbitrary number of data elements. As the
number of elements changes, the BPEL process service component adjusts accordingly.
The branches created by flowN perform the same activities, but use different data.
Each branch uses the index variable to look up input variables. The index variable can
be used in the XPath expression to acquire the data specific for that branch.
For example, suppose there is an array of data. The BPEL process service component
uses a count function to determine the number of elements in the array. The process
then sets N to be the number of elements. The index variable starts at a preset value
(zero is the default), and flowN creates branches to retrieve each element of the array
and perform activities using data contained in that element. These branches are
generated and performed in parallel, using all the values between the initial index
value and N. flowN terminates when the index variable reaches the value of N. For
10-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
example, if the array contains 3 elements, N is set to 3. Assuming the index variable
begins at 1, the flowN activity creates three parallel branches with indexes 1, 2, and 3.
The flowN activity can use data from other sources as well, including data obtained
from web services.
Figure 109 shows the runtime flow of a flowN activity in Oracle Enterprise Manager
Fusion Middleware Control that looks up three hotels. This is different from the view,
because instead of showing the BPEL process service component, it shows how the
process has actually executed. In this case, there are three hotels, but the number of
branches changes to match the number of hotels available.
Figure 109 Oracle Enterprise Manager Fusion Middleware Control View of the
Execution of a flowN activity
3.
4.
5.
Sequence Name
<sequence name="main">
<!-- Received input from requester.
Note: This maps to operation defined in NflowHotels.wsdl
10-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The requester sends a set of hotels names wrapped into the "inputVariable"
-->
A receive activity calls the client partner link to get the information that the flowN
activity must define N times and look up the hotel information. Example 106 provides
an example.
Example 106
Receive Activity
The flowN activity begins next. After defining a name for the activity of flowN, N is
defined as a value from the inputVariable, which is the number of hotel entries.
The activity also assigns index as the index variable. Example 107 provides an
example.
Example 107
FlowN Activity
The copy rule shown in Example 108 then uses the index variable to concatenate the
hotel entries into a list:
Example 108
Assign Activity
<assign name="setHotelId">
<copy>
<from expression=
"bpws:getVariableData('inputVariable','payload',concat('/client:Nflo
wHotelsProcessRequest/client:ListOfHotels/client:HotelName[',
bpws:getVariableData('Index'),']'))"/>
<to variable="InvokeHotelDetailInputVariable" part="payload"
query="/ns2:hotelInfoRequest/ns2:id"/>
</copy>
</assign>
Using the hotel information, an invoke activity looks up detailed information for each
hotel through a web service. Example 109 provides an example.
Example 109
Invoke Activity
<!-- For each hotel, invoke the web service giving detailed information
on the hotel -->
<invoke name="InvokeHotelDetail" partnerLink="getHotelDetail"
portType="ns2:getHotelDetail" operation="process"
inputVariable="InvokeHotelDetailInputVariable"
outputVariable="InvokeHotelDetailOutputVariable"/>
</sequence>
</bpelx:flowN>
Finally, the BPEL process sends detailed information on each hotel to the client partner
link. Example 1010 provides an example.
Example 1010 Invoke Activity
<invoke name="callbackClient" partnerLink="client"
portType="client:NflowHotelsCallback" operation="onResult"
inputVariable="outputVariable"/>
</sequence>
</sequence>
10.3.2 Processing Multiple Sets of Activities with the forEach Activity in BPEL 2.0
You can use a forEach activity to process multiple sets of activities sequentially or in
parallel. The forEach activity executes a contained (child) scope activity exactly N+1
times, where N equals a final counter value minus a starting counter value that you
specify in the Counter Values tab of the For Each dialog. While other structured
activities such as a flow activity can have any type of activity as its contained activity,
the forEach activity can only include a scope activity.
When the forEach activity is started, the expressions you specify for the starting
counter and final counter values are evaluated. Once the two values are returned, they
remain constant for the lifecycle of the activity. Both expressions must return a value
containing at least one character. If these expressions do not return valid values, a fault
is thrown. If the starting counter value is greater than the final counter value, the
contained scope activity is not performed and the forEach activity is considered
complete.
During each iteration, the variable specified in the Counter Name field on the General
tab is implicitly declared in the forEach activity's contained scope. During the first
iteration of the scope, the counter variable is initialized with the starting counter value.
The next iteration causes the counter variable to be initialized with the starting counter
value, plus one. Each subsequent iteration increments the previously initialized
counter variable value by one until the final iteration, where the counter is set to the
final counter value. The counter variable is local to the enclosed scope activity.
Although its value can be changed during an iteration, that value is lost after each
iteration. Therefore, the counter variable value does not impact the value of the next
iteration's counter.
The forEach activity supports the following looping iterations:
Sequential (default)
10-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The forEach activity performs looping iterations sequentially N times over a given
set of activities defined within a scope activity. As an example, the forEach activity
iterates over an incoming purchase order message where the purchase order
message consists of N order items. The enclosed scope activity must be executed
N+1 times, with each instance starting only after the previous iteration has
completed.
Parallel
All looping iterations are started at the same time and processed in parallel.
Parallel iterations are useful in environments in which sets of independent data
are processed or independent interaction with different partners is performed in
parallel. To enable parallel looping, you select the Parallel Execution checkbox on
the General tab. In these scenarios, execution of the N+1 instances of the contained
scope activity occurs in parallel. Each copy of the scope activity has the same
counter variable that you specify in the Counter Name field of the General tab
declared in the same way as specified for a sequential forEach activity. Each
instance's counter variable must be uniquely initialized in parallel with one of the
integer values beginning with the starting counter value and proceeding up to and
including the final counter value.
Unlike a flow activity, the number of parallel branches is not known at design time
with the forEach activity. The specified counter variable iterates through the
number of parallel branches, controlled by the starting counter value and final
counter value.
You can also specify a completion condition on the Completion tab. This condition
enables the forEach activity to execute the condition and complete without executing
or finishing all the branches specified. As an example, you send out parallel requests
and a sufficient subset of the recipients have responded. A completion condition is
optionally specified to prevent the following:
To force early termination of some of the children (in the parallel case)
If you do not specify a completion condition, the forEach activity completes when the
contained scope has completed.
If a premature termination occurs (due to a fault or the completion condition
evaluating to true), then the N+1 requirement does not apply.
Example 1011 shows the forEach activity syntax.
Example 1011 forEach Activity
<forEach counterName="MyVariableName" parallel="yes|no"
standard-attributes>
standard-elements
<startCounterValue expressionLanguage="anyURI"?>
unsigned-integer-expression
</startCounterValue>
<finalCounterValue expressionLanguage="anyURI"?>
unsigned-integer-expression
</finalCounterValue>
<completionCondition>?
<branches expressionLanguage="anyURI"?
successfulBranchesOnly="yes|no"?>?
unsigned-integer-expression
</branches>
</completionCondition>
<scope ..>...</scope>
</forEach>
Drag a For Each activity into the designer, as shown in Figure 1012.
Note the contained scope activity in the forEach activity.
3.
4.
In the Counter Name field of the General tab, enter a counter value name, as
shown in Figure 1013.
If the Parallel Execution checkbox is selected, all looping iterations are started at
the same time and processed in parallel. The next branch starts even if the
previous branch has not completed. If not selected, the next branch does not start
until the previous branch has completed.
5.
10-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Enter the starting counter value and final counter value, as shown in Figure 1014.
Figure 1014
7.
8.
If you want to specify a completion condition that enables the forEach activity to
execute the condition and complete without executing or finishing all the branches
specified, click the XPath Expression Builder icon above the Expression field to
enter a condition. Figure 1015 provides details.
Figure 1015
9.
When complete, the forEach and contained scope activity can appear similar in
structure to that shown in Figure 1016.
Figure 1016 forEach Activity with Contained and Expanded Scope Activity
<to>$output.payload</to>
</copy>
</assign>
<forEach counterName="i" parallel="no">
<startCounterValue>$input.payload/tns:startCounter+1</startCounterValue>
<finalCounterValue>$input.payload/tns:finalCounter+1</finalCounterValue>
<completionCondition>
<branches>$input.payload/tns:branches+1</branches>
</completionCondition>
<scope name="scope1">
<partnerLinks>
<partnerLink name="DummyService" partnerLinkType="tns:DummyService"
myRole="DummyServiceClient" partnerRole="DummyServiceProvider"/>
</partnerLinks>
<sequence>
<assign>
<copy>
<from>concat($output.payload, $i, 'A')</from>
<to>$output.payload</to>
</copy>
</assign>
<invoke name="invokeDummyService" partnerLink="DummyService"
portType="tns:DummyPortType"
operation="initiate" inputVariable="request"/>
<receive name="receiveFromDummyService" partnerLink="DummyService"
portType="tns:DummyCallbackPortType"
operation="onResult" variable="response"/>
<assign>
<copy>
<from>concat($output.payload, $i, 'B')</from>
<to>$output.payload</to>
</copy>
</assign>
</sequence>
</scope>
</forEach>
<!-- respond output to requester -->
<reply name="replyOutput" partnerLink="client"
portType="tns:Test" operation="process" variable="output"/>
</sequence>
Example 1013 shows the .bpel file after design is complete for a parallel forEach
activity.
Example 1013 forEach Activity - Parallel
<sequence>
<!-- pick input from requester -->
<receive name="receive" createInstance="yes"
partnerLink="client" portType="tns:Test"
operation="process" variable="input"/>
<assign>
<copy>
<from>$input.payload/tns:value1</from>
<to>$request.payload</to>
</copy>
<copy>
<from>''</from>
<to>$output.payload</to>
</copy>
</assign>
<forEach counterName="i" parallel="yes">
<startCounterValue>($input.payload/tns:value1 + 1)</startCounterValue>
<finalCounterValue>($input.payload/tns:value2 + 2)</finalCounterValue>
<scope name="scope1">
<partnerLinks>
<partnerLink name="DummyService" partnerLinkType="tns:DummyService"
myRole="DummyServiceClient" partnerRole="DummyServiceProvider"/>
</partnerLinks>
<sequence>
<assign>
<copy>
<from>concat($output.payload, 'A')</from>
<to>$output.payload</to>
</copy>
</assign>
<invoke name="invokeDummyService" partnerLink="DummyService"
portType="tns:DummyPortType"
operation="initiate" inputVariable="request"/>
<receive name="receiveFromDummyService" partnerLink="DummyService"
portType="tns:DummyCallbackPortType"
operation="onResult" variable="response"/>
<assign>
<copy>
<from>concat($output.payload, 'B')</from>
<to>$output.payload</to>
</copy>
</assign>
</sequence>
</scope>
</forEach>
<!-- respond output to requester -->
<reply name="replyOutput" partnerLink="client"
portType="tns:Test" operation="process" variable="output"/>
</sequence>
10-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
11
11
While activity
Enables you to create a while loop to select between two actions. Section 11.3,
"Defining Conditional Branching with the While Activity" describes while
activities.
Many branches are set up, and each branch has a condition in the form of an XPath
expression.
You can program a conditional branch to have a timeout. That is, if a response cannot
be generated in a specified period, the BPEL flow can stop waiting and resume its
activities. Chapter 15, "Using Events and Timeouts in BPEL Processes" explains this
feature in detail.
You can also define conditional branching logic with business
rules. See Oracle Fusion Middleware User's Guide for Oracle Business
Rules and the WebLogic Fusion Order Demo application for details.
Note:
11.2.1 Defining Conditional Branching with the Switch Activity in BPEL 1.1
Assume you designed a flow activity in the BPEL process service component that
gathered loan offers from two companies at the same time, but did not compare either
of the offers. Each offer was stored in its own global variable. To compare the two bids
and make decisions based on that comparison, you can use a switch activity.
Figure 111 provides an overview of a BPEL conditional branching process that has
been defined in a switch activity.
Figure 111 Conditional Branching
condition 1 Boolean XPATH Expession
BPEL Process
<switch>
<case
condition 1>
<otherwise>
Select
unitedLoan
<assign>
Select
starLoan
<assign>
11-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
In the Label field, enter a name for the condition branch. When complete, this
name is displayed in Oracle BPEL Designer.
5.
6.
In the Condition field, click the Expression Builder icon to access the Expression
Builder dialog.
7.
In this example, two loan offers from completing loan companies are stored in the
global variables loanOffer1 and loanOffer2. Each loan offer variable contains
the loan offers APR. The BPEL flow must choose the loan with the lower APR.
One of the following switch activities takes place:
If loanOffer1 has the higher APR, then the first branch selects loanOffer2
by assigning the loanOffer2 payload to the selectedLoanOffer payload.
Using Conditional Branching in a BPEL Process 11-3
8.
If loanOffer1 does not have the lower APR than loanOffer2, the
otherwise case assigns the loanOffer1 payload to the
selectedLoanOffer payload.
Click OK.
The expression is displayed. The value you entered in the Label field of the dialog
becomes the name of the condition branch. Figure 114 provides details.
9.
Click OK.
10. Add and configure additional activities as needed. Figure 115 provides details.
Figure 115 Switch Activity Design
Switch Activity
<switch name="switch-1">
<case condition="bpws:getVariableData('loanOffer1','payload',
'/autoloan:loanOffer/autoloan:APR') >
bpws:getVariableData('loanOffer2','payload','/autoloan:loanOffer/autoloan:APR
')">
11-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
" name="Choose_the_Loan_with_the_Lower_APR">
<bpelx:annotation>
<bpelx:general>
<bpelx:property name="userLabel">Choose the Loan with
the Lower APR</bpelx:property>
</bpelx:general>
</bpelx:annotation>
<assign name="selectUnitedLoan">
<copy>
<from variable="loanOffer1" part="payload">
</from>
<to variable="selectedLoanOffer" part="payload"/>
</copy>
</assign>
</case>
<otherwise>
<assign name="selectStarLoan">
<copy>
<from variable="loanOffer2" part="payload">
</from>
<to variable="selectedLoanOffer" part="payload"/>
</copy>
</assign>
</otherwise>
</switch>
The if branch
The first branch whose condition evaluates to true is taken, and its contained activity
is performed. If no branch with a condition is taken, then the else branch is taken (if
present). The if activity is complete when the contained activity of the selected branch
completes, or immediately when no condition evaluates to true and no else branch is
specified.
The if activity is a BPEL version 2.0 feature that replaces the switch activity that was
included in BPEL version 1.1.
Example 112 shows the if activity syntax.
Example 112
If Activity
<if standard-attributes>
standard-elements
<condition>some conditon expression</condition>
activity
<elseif>*
<condition>some condition expression</condition>
some activity
</elseif>
<else>?
some activity
Using Conditional Branching in a BPEL Process 11-5
</else>
</if>
3.
If you want to add elseif conditions, highlight the If activity, and select the Add
icon to invoke a menu.
4.
5.
In the Condition field, enter a condition, as shown in Figure 117. You can also
click the XPath Expression Builder icon to invoke the Expression Builder dialog.
6.
Click OK.
7.
Drag and define additional activities into the if condition, as needed. These
activities are executed if the if condition evaluates to true.
8.
9.
11-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
activities are executed if the if branch did not evaluate to true, and this elseif
branch evaluates to true.
12. Click the else label.
13. Enter a condition or drag and define additional activities into the else condition,
as needed. These activities are executed if the if and any elseif branches did not
evaluate to true, and this else branch evaluates to true.
Figure 119 shows a completed if activity in which each branch includes contained
activities.
Figure 119 Completed If Activity
If Activity
<sequence>
<!-- receive input from requester -->
<receive name="receiveInput" partnerLink="client" portType="tns:Test"
operation="process" variable="input" createInstance="yes"/>
<!-- assign default value -->
<assign>
<copy>
11-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
4.
Drag and define additional activities for using the while condition into the Drop
Activity Here area of the While activity (for example, a Scope activity).
The activities can be existing or new activities.
5.
Click the XPath Expression Builder icon to open the Expression Builder dialog.
6.
Figure 1110
7.
There is no exception, upon which the dbStatus value is set to a value of 10,
which results in the while condition evaluating to false.
After throwing a fault five times, the dbStatus value is 5, and the while
condition returns false.
Example 114
While Activity
Note: The while activity code fragment in Example 114 uses a BPEL
1.1 construct of bpws:getVariableData('dbStatus'). For BPEL
2.0, variables are referenced directly using $ sign and dot (.) notation.
For example:
<while name="While1">
<condition>$inputVariable.payload/client:counter > 0
</condition>
11-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
5.
In the Condition field, click the XPath Expression Builder icon to enter an XPath
expression condition.
The Expression Builder dialog is displayed.
6.
Figure 1111
7.
8.
Figure 1112
9.
Design the body of the activity by dragging in activities from the Component
Palette and defining their property values. These activities are evaluated until the
XPath expression condition is evaluated to true.
Example 115
repeatUntil Activity
<repeatUntil>
<sequence>
<invoke name="PurchaseOrderValidation" ... />
<receive name="receiveValidation"
partnerLink="PurchaseOrderValidation"
operation="returnPurchaseOrderValidation"
variable="PurchaseOrderStatusResponse" />
</sequence>
<condition>
bpel:getVariableProperty(
"PurchaseOrderStatusResponse","tst:completionStatus") < 5
</condition>
</repeatUntil>
<assign bpelx:skipCondition="bpws:getVariableData('input',
'payload','/tns:inputMsg/tns:myvalue') <= 0">
<copy>
<from expression="'Value is greater than zero'"/>
<to variable="output" part="payload"
query="/tns:resultMsg/tns:valueResult"/>
</copy>
</assign>
The equivalent functionality used with a switch activity is shown in Example 117.
Example 117
<switch>
<case condition="bpws:getVariableData('input',
'payload','/tns:inputMsg/tns:value') > 0">
<assign>
<copy>
11-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<assign name="Assign4">
<bpelx:skipCondition>ora:getNodeValue($inputVariable.payload/client:input) > 5
</bpelx:skipCondition><copy>
<from>"dummy result"</from>
<to>$outputVariable.payload/client:result</to>
</copy></assign>
You can also use built-in and custom XPath functions within the skip condition
expression. Example 119 provides several examples.
Example 119
If an error is thrown by the XPath expression evaluation, the error is wrapped with a
BPEL fault and thrown from the activity.
An event is added to the BPEL instance audit trail for activities that are bypassed due
to the skip condition expression evaluating to true. Even if the skip condition
evaluates to false (meaning the activity is performed), the fact that a skip condition
expression was evaluated is still logged to the audit trail for debugging purposes.
If the XPath engine fails to evaluate the boolean value, bpws:subLanguageFault is
thrown. This is the same fault thrown when a switch/case condition does not evaluate
to a boolean value. This is also logged to the audit trail for debugging purposes.
Drag the activity into the designer in which to create the skip condition.
3.
4.
5.
11.5.2 What Happens When You Specify XPath Expressions to Bypass Activity
Execution
The code segment in the .bpel file defines the specific operation after design
completion.
For example, the XPath expression shown in Example 1110, when evaluated to true
(for example, input is 20), causes the assign activity to be skipped.
Example 1110 skipCondition Attribute For Bypassing Activity Execution
<sequence name="main">
. . .
. . .
<assign name="Assign_1"
bpelx:skipCondition="number(bpws:getVariableData('inputVariable','payload','/clien
t:
process/client:input')) > 10">
<copy>
<from expression="'Assign Block is not Skipped'"/>
<to variable="inputVariable" part="payload"
query="/client:process/client:input"/>
</copy>
</assign>
. . .
. . .
</sequence>
11-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12
12
Section 12.3, "Introduction to the Business and Runtime Fault Categories of BPEL
Faults"
Section 12.6, "Getting Fault Details with the getFaultAsString XPath Extension
Function"
error message instead of a number). An example of a fault handler is where the web
service normally returns a credit rating number, but instead returns a negative credit
message.
Figure 121 provides an example of how a fault handler sets a credit rating variable to
-1000.
Figure 121 Fault Handling
BPEL Process
WSDL
<receive>
d1
WSDL
Negative
Credit
<scope>
prepare
crin
<assign>
d3
f1
Credit
Rating
Service
call
service
<invoke>
Read
crOut
<assign>
<scope>
credit to
-1000
<assign>
d2
<reply>
The code segment in Example 121 defines the fault handler for this operation in the
BPEL file:
Example 121
<faultHandlers>
<catch faultName="services:NegativeCredit" faultVariable="crError">
<assign name="crin">
<copy>
<from expression="-1000">
</from>
<to variable="input" part="payload"
query="/autoloan:loanApplication/autoloan:creditRating"/>
</copy>
</assign>
</catch>
</faultHandlers>
12-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The faultHandlers tag contains the fault handling code. Within the fault handler is
a catch activity, which defines the fault name and variable, and the copy instruction
that sets the creditRating variable to -1000.
When you select web services for the BPEL process service component, determine the
possible faults that may be returned and set up a fault handler for each one.
conflictingReceive
conflictingRequest
correlationViolation
forcedTermination
invalidReply
joinFailure
mismatchedAssignmentFailure
repeatedCompensation
selectionFailure
uninitializedVariable
Not associated with any Web Services Description Language (WSDL) message
ambiguousReceive
completionConditionFailure
conflictingReceive
conflictingRequest
correlationViolation
invalidBranchCondition
invalidExpressionValue
invalidVariables
joinFailure
mismatchedAssignmentFailure
missingReply
missingRequest
scopeInitializationFailure
selectionFailure
subLanguageExecutionFault
uninitializedPartnerRole
uninitializedVariable
unsupportedReference
xsltInvalidSource
xsltStylesheetNotFound
If there is a catch activity with a matching faultName value that does not specify
a faultVariable attribute, the fault is sent to the identified catch activity.
Otherwise, if there is a catchAll activity, the fault is sent to the catchAll fault
handler.
Otherwise, the fault is processed by the default fault handler.
In BPEL 2.0, the order of precedence for catching faults thrown with associated data is
as follows:
If there is a catch activity with a matching faultName value that does not specify
a faultVariable attribute, the fault is sent to the identified catch activity.
If the fault data is a WSDL message type in which the following exists:
There exists a catch activity with a matching faultName value that has a
faultVariable whose associated faultElement QName matches the
QName of the runtime element data of the single WSDL message part.
Then, the fault is sent to the identified catch activity with the faultVariable
initialized to the value in the single parts element.
Otherwise, if there is a catch activity with a matching faultName value that does
not specify a faultVariable attribute, the fault is sent to the identified catch
activity. In this case, the fault value is not available from within the fault handler,
but is available to the rethrow activity.
12-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Business faults
Runtime faults
Several runtime faults are automatically provided. These faults are included in the
http://schemas.oracle.com/bpel/extension namespace. These faults are
associated with the messageType RuntimeFaultMessage. The WSDL file shown in
Example 122 defines the messageType:
Example 122
messageType Definition
12.3.2.1 bindingFault
A bindingFault is thrown inside an activity if the preparation of the invocation
fails. For example, the WSDL of the process fails to load. A bindingFault is not
retryable. This type of fault usually must be fixed by human intervention.
12.3.2.2 remoteFault
A remoteFault is also thrown inside an activity. It is thrown because the invocation
fails. For example, a SOAP fault is returned by the remote service.
12.3.2.3 replayFault
A replayFault replays the activity inside a scope. At any point inside a scope, this
fault is migrated up to the scope. The server then re-executes the scope from the
beginning.
12.3.3 How to Add and Propagate Fault Handling in a Synchronous BPEL Process
This section describes how to add and propagate fault handling in a synchronous
BPEL process. During the design, you perform the following tasks:
Modify the existing schema and WSDL files to include fault element, fault
message, and fault operation details.
Create a fault variable with the fault message type you specified in the WSDL file.
Add assign and reply activities with additional fault handling details.
3.
12-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<element name="processFault">
<complexType>
<sequence>
<element name="result" type="string"/>
</sequence>
</complexType>
</element>
4.
5.
6.
7.
Click the Add Catch icon in the BPEL process to add a catch activity as the fault
handler for the BPEL process. You can also use a CatchAll activity. Figure 122
provides details.
3.
Double-click the catch activity to specify the system fault. Figure 123 provides
details.
There is no assert activity to trigger this system fault, you can add one to assert an
input field.
4.
5.
Select a system fault (for this example, assertFailure), and click OK. There are
many other system faults that can be selected. Figure 124 provides details.
12-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
Copy the RuntimeFault.wsdl file into the SOA Content folder. This is the same
location as the BPEL process WSDL file.
8.
3.
4.
5.
Expand Message Types > Project WSDL Files > TestProcess.wsdl > Message
Types > TestProcessFaultMessage, and click OK. Figure 126 provides details.
6.
3.
Concatenate the code, summary, and detail fields of the FaultVar variable to the
FaultResponse variable, and click OK. Figure 127 provides details.
4.
In the Name field of the General tab, enter a name (for this example,
FaultDataForClient).
3.
4.
Expand Project WSDL Files > TestProcess.wsdl, and select the fault named
FaultResponse. Figure 128 provides details.
12-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
6.
7.
Select the same partner link to which the replyOutput reply activity is connected,
and click OK.
8.
9.
Select the FaultResponse variable, and click OK. Figure 129 provides details.
The BPEL process looks as shown in Figure 1210. Both reply activities are
connected to the same partner link.
Figure 1210 BPEL Process Design
The fault management framework catches all faults (business and runtime) for an
invoke activity.
A fault policy file defines fault conditions and their corresponding fault recovery
actions. Each fault condition specifies a particular fault or group of faults, which it
attempts to handle, and the corresponding action for it. A set of actions is
identified by an ID in the fault policy file.
A set of conditions invokes an action (known as fault policy).
A fault policy bindings file associates the policies defined in the fault policy file
with the following:
The framework looks for fault policy bindings in the same directory as the
composite.xml file of the SOA composite application or in a remote location
identified by two properties that you set.
12-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
The fault policy file (fault-policies.xml) and fault policy bindings file
(fault-bindings.xml) are placed in either of the following locations:
In a different location that is specified with two properties that you add to the
composite.xml file. This option is useful if a fault policy must be used by
multiple SOA composite applications. This option overrides any fault policy
files that are included in the same directory as the composite.xml file.
Example 123 provides details about these two properties. In this example, the
fault policy files are placed into the SOA part of the Oracle Metadata Services
(MDS) Repository shared area.
Example 123
<property
name="oracle.composite.faultPolicyFile">oramds:/apps/faultpolicyfiles/
fault-policies.xml
</property>
<property
name="oracle.composite.faultBindingFile">oramds:/apps/faultpolicyfiles/
fault-bindings.xml
</property>
For details about Oracle Mediator fault handling capabilities., see Chapter 22, "Using
Oracle Mediator Error Handling."
For details about creating a fault policy with Oracle Business Process Management
(BPM) Suite, see Chapter "Using Fault Handling in BPM" of Oracle Fusion Middleware
Modeling and Implementation Guide for Oracle Business Process Management.
Note:
During the resolution process, if no action is found that matches the condition, the
framework assumes that resolution failed and moves to the next resolution level.
For example, assume an invoke activity faults with faultname="abc". There is a
policy binding specified in the fault-binding.xml file:
If the fault resolution fails, go to the next possible match (in this case,
policy-id-1).
If the fault resolution still fails, the fault is sent to the BPEL fault catch activity.
Place the file in the same directory as the composite.xml file or place it in a
different location and define the oracle.composite.faultPolicyFile
property.
<property
name="oracle.composite.faultPolicyFile">oramds:/apps/faultpolicyfiles/
fault-policies.xml
</property>
<property
name="oracle.composite.faultBindingFile">oramds:/apps/faultpolicyfiles/
fault-bindings.xml
</property>
If the fault policy file is located in a file system, use the following format.
<property
name="oracle.composite.faultPolicyFile">file:/project/apps/fault-policies.xml
</property>
3.
12-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Each condition has one test section (an XPath expression) and one
action section.
The test section (XPath expression) is evaluated for the fault variable
available in the fault.
The action section has a reference to the action defined in the same file.
You can only query the fault variable available in the fault.
Table 121 provides examples of the condition section in the fault policy
file. All actions defined in the condition section must be associated with an
action in the action section.
Table 121
Condition Example
<condition>
<test>$fault.code="WSDLReading Error"
</test>
<action ref="ora-terminate"/>
</condition>
<condition>
<action ref="ora-rethrow"/>
</condition>
4.
Define the action section of the fault policy file. Validation of fault policy files is
done during deployment. If you change the fault policy, you must redeploy the
SOA composite application that includes the fault policy.
Table 122 provides several examples of the action section in the fault policy file.
You can provide automated recovery actions for some faults. In all recovery
actions except retry and human intervention, the framework performs the actions
synchronously.
Table 122
Recovery Actions
<Action id="ora-terminate"><abort/></Action>
<Action id="ora-replay-scope"><replayScope/></Action>
12-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
A fault policy file with fully-defined condition and action sections looks as
follows:
Notes:
Fault policy file names are not restricted to one specific name.
However, they must conform to the fault-policy.xsd schema
file.
This fault policy file provides an example of catching faults based
on fault names. You can also catch faults based on message types,
or on both:
<faultName name="myfault" type="fault:faultType">
<abort/>
</Action>
<Action id="default-replay-scope">
<replayScope/>
</Action>
<Action id="default-rethrow-fault">
<rethrowFault/>
</Action>
<Action id="default-human-intervention">
<humanIntervention/>
</Action>
<Action id="MediatorJavaAction">
<!-- this is user provided class-->
<javaAction className="MediatorJavaAction.myClass"
defaultAction="default-terminate">
<returnValue value="MANUAL" ref="default-human-intervention"/>
</javaAction>
</Action>
<Action id="BPELJavaAction">
<!-- this is user provided class-->
<javaAction className="BPELJavaAction.myAnotherClass"
defaultAction="default-terminate">
<returnValue value="MANUAL" ref="default-human-intervention"/>
</javaAction>
</Action>
</Actions>
</faultPolicy>
</faultPolicies>
Note:
Place the file in the same directory as the composite.xml file or place it in a
remote location and define the oracle.composite.faultBindingFile
property as shown in Step 2 of Section 12.4.1.2, "Creating a Fault Policy File for
Automated Fault Recovery."
This fault policy bindings file associates the fault policies defined in the
fault-policies.xml file with the FusionMidFaults SOA composite
application.
<?xml version="1.0" encoding="UTF-8" ?>
<faultPolicyBindings version="0.0.1"
xmlns="http://schemas.oracle.com/bpel/faultpolicy"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<composite faultPolicy="FusionMidFaults"/>
<!--<composite faultPolicy="ServiceExceptionFaults"/>-->
<!--<composite faultPolicy="GenericSystemFaults"/>-->
</faultPolicyBindings>
12-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12.4.1.4 Additional Fault Policy and Fault Policy Binding File Samples
This section provides additional samples of fault policy and fault policy binding files.
Example 124 shows the fault-policies.xml file contents.
Example 124
fault-policies.xml File
<condition>
<test>$fault.payload="Bankruptcy Report-abort"</test>
<action ref="ora-terminate"/>
</condition>
<!-- you get this fault when SSN starts with 2-->
<condition>
<test>$fault.payload="Bankruptcy Report-rethrow"</test>
<action ref="ora-rethrow-fault"/>
</condition>
<!-- you get this fault when SSN starts with 3-->
<condition>
<test>$fault.payload="Bankruptcy Report-replay"</test>
<action ref="ora-replay-scope"/>
</condition>
<!-- you get this fault when SSN starts with 4-->
<condition>
<test
xmlns:myError="http://services.otn.com">$fault.payload="Bankruptcy
Report-human"</test>
<action ref="ora-human-intervention"/>
</condition>
<!-- you get this fault when SSN starts with 5-->
<condition>
<test>$fault.payload="Bankruptcy Report-java"</test>
<action ref="ora-java"/>
</condition>
</faultName>
</Conditions>
<Actions>
<Action id="ora-retry">
<retry>
<retryCount>3</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff/>
<retryFailureAction ref="ora-java"/>
<retrySuccessAction ref="ora-java"/>
</retry>
</Action>
<Action id="ora-retry-crm-endpoint">
<retry>
<retryCount>5</retryCount>
<retryFailureAction ref="ora-java"/>
<retryInterval>5</retryInterval>
<retrySuccessAction ref="ora-java"/>
</retry>
</Action>
<Action id="ora-replay-scope">
<replayScope/>
</Action>
<Action id="ora-rethrow-fault">
<rethrowFault/>
</Action>
<Action id="ora-human-intervention">
<humanIntervention/>
</Action>
<Action id="ora-terminate">
<abort/>
</Action>
<Action id="ora-java">
12-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 125 shows the fault-bindings.xml file that associates the fault policies
defined in fault-policies.xml.
Example 125
<faultName xmlns:rjm="http://schemas.oracle.com/sca/rejectedmessages"
name="rjm:FileIn">
<condition>
<action ref="ora-queue"/>
</condition>
</faultName>
<faultName xmlns:rjm="http://schemas.oracle.com/sca/rejectedmessages"
name="rjm:FileIn">
<condition>
<action ref="ora-file"/>
</condition>
</faultName>
12-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For additional information, see Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for the following:
The Java class provided follows a specific interface. This interface returns a string.
Multiple values can be provided for output and fault policy to take after
execution.
Additional fault policy can be executed by providing a mapping from the output
value (return value) of implemented methods to a fault policy.
If no ReturnValue is specified, the default fault policy is executed, as shown in
Example 127.
Example 127
<Action id="ora-java">
<javaAction className="mypackage.myclass"
defaultAction="ora-human-intervention" propertySet="prop-for-billing">
<!--defaultAction is a required attribute, but propertySet is optional-->
<!-- attribute-->
<ReturnValue value="RETRY" ref="ora-retry"/>
<!--value is not nilable attribute & cannot be empty-->
<ReturnValue value="RETRHOW" ref="ora-rethrow-fault"/>
</javaAction>
</Action>
Code
Description
<ReturnValue value="RETRY"
ref="ora-retry"/>
<ReturnValue value="
ref=ora-rethrow/>
Fails in validation.
Description
<ReturnValue value="RETRY"
ref="ora-retry"/>
<ReturnValue value=" ref=/>
Fails in validation.
<javaAction
className="mypackage.myclass"
defaultAction="
ora-human-intervention">
<ReturnValue></ReturnValue>
Fails in validation.
To invoke a Java class, you can provide a class that implements the
IFaultRecoveryJavaClass interface. IFaultRecoveryJavaClass is included
in the fabric-runtime.jar file. The package name is
oracle.integration.platform.faultpolicy.
The IFaultRecoveryJavaClass interface has two methods, as shown in
Example 128.
Example 128
implementation of IFaultRecoveryJavaClass
12-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The service engine implementation of this interface provides more information (for
example, Oracle BPEL Process Manager). Example 1210 provides details.
Example 1210 Service Engine Implementation of IFaultRecoveryContext
public class BPELFaultRecoveryContextImpl extends BPELXExecLetUtil implements
IBPELFaultRecoveryContext, IFaultRecoveryContext{
...
}
12-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
* @return
*/
public String setTitle(String title);
public void setVariableData(String name, Object value) throws BPELFault;
public void setVariableData(String name, String partOrQuery, Object value)
throws BPELFault;
public void setVariableData(String name, String part, String query,
Object value) throws BPELFault;
}
12.4.5 What You May Need to Know About Fault Management Behavior When the
Number of Instance Retries is Exceeded
When you configure a fault policy to recover instances with the ora-retry action
and the number of specified instance retries is exceeded, the instance is marked as
open.faulted (in-flight state). The instance remains active.
Marking instances as open.faulted ensures that no instances are lost. You can then
configure another fault handling action following the ora-retry action in the fault
policy file, such as the following:
However, if you do not set an action to be performed after an ora-retry action in the
fault policy file and the number of instance retries is exceeded, the instance remains
marked as open.faulted, and recovery attempts to handle the instance.
For example, if no action is defined in the fault policy file shown in Example 1213
after ora-retry:
Example 1213 No Action Defined
<Action id="ora-retry">
<retry>
<retryCount>2</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff/>
</retry>
</Action>
The invoke activity is attempted (using the above-mentioned fault policy code to
handle the fault).
Two retries are attempted at increasing intervals (after two seconds, then after
four seconds).
If all retry attempts fail, the following actions are performed:
Recovery may also fail. In that case, the invoke activity is re-executed. Additional
audit messages are logged.
12.4.6 What You May Need to Know About Executing the Retry Action with Multiple
Faults in the Same Flow
The fault policy retry action may not execute with multiple faults in the same flow.
This may be because the retry count has already been reached for any of the previous
faults.
For example, assume you define a fault policy with two fault conditions: fault1 and
fault2. For both fault conditions, the retry action is specified with a retry count of
three. Assume fault1 occurs and the retry action executes three times. You correct
the problem for fault1 by modifying the payload, but ensure that fault2 is to be
raised when the instance is resubmitted. You then resubmit the faulted instance using
Oracle Enterprise Manager Fusion Middleware Control. You expect the second fault
condition, fault2, to retry three times according to the fault policy specification.
However, this does not occur because the maximum number of retries was already
executed for the previous fault1 fault condition.
12.4.7 What You May Need to Know About Binding Level Retry Execution Within Fault
Policy Retries
If you are testing retry actions on adapters with both JCA-level retries for the
outbound direction and a retry action in the fault policy file for outbound failures, the
JCA-level (or binding level) retries are executed within the fault policy retries. For
example, assume you have designed the application shown in Figure 1211:
12-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1211
You specify the retry parameters shown in Example 1214 in the composite.xml file:
Example 1214 Retry Parameters
<property name="jca.retry.count" type="xs:int" many="false"
override="may">2</property>
<property name="jca.retry.interval" type="xs:int" many="false"
override="may">2</property>
<property name="jca.retry.backoff" type="xs:int" many="false"
override="may">2</property>
In the fault policy file for the EQ reference binding component for the outbound
direction, you specify the actions shown in Example 1215.
Example 1215 Retry Actions
<retryCount>3</retryCount>
<retryInterval>3</retryInterval>
If an outbound failure occurs, the expected behavior is for the JCA retries to occur
within the fault policy retries. When the first retry of the fault policy is executed, the
JCA retry is called. In this example, a JCA retry of 2 with an interval of 2 seconds and
exponential back off of 2 is executed for every retry of the fault policy:
12.4.8 What You May Need to Know About Defining the ora-java Option
Assume you invoke a SOA composite application with a fault policy/binding defined
and see a recoverable fault in Oracle Enterprise Manager Fusion Middleware Control.
After you perform a successful fault recovery retry, there is no ora-java option
available for selection by default in the After Successful Retry list of the Faults tab of
the Instance of process_name page.
This is the expected behavior. For the ora-java option to display, you must explicitly
define it in the fault-policies.xml file during design-time. For example, perform
the following steps.
3.
Click the composite instance to invoke the instance trace of the composite.
4.
Click the component in which there is a recoverable fault (for example, Oracle
BPEL Process Manager, Oracle Mediator, or Oracle BPM).
5.
6.
7.
Select the list and note that the ora-java option is now listed.
For more information about recovering from faults in Oracle Enterprise Manager
Fusion Middleware Control, see Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
3.
| "bpelx:bindingFault"
12-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12.6.1 How to Get Fault Details with the getFaultAsString XPath Extension Function
Example 1216 shows how to use this function.
Example 1216 getFaultAsString() XPath Extension Function
<catchAll>
<sequence>
<assign>
<from expression="bpelx:getFaultAsString()"/>
<to variable="faultVar" part="message"/>
</assign>
<reply faultName="ns1:myFault" variable="faultVar" .../>
</sequence>
</catchAll>
3.
4.
5.
To the right of the Namespace URI field, click the Search icon to select the fault to
monitor.
6.
Select the fault in the Fault Chooser dialog, and click OK.
The namespace URI for the selected fault displays in the Namespace URI field.
Your fault selection also automatically displays in the Local Part field.
Figure 1212 provides an example of a completed Throw dialog. This example
shows the Throw_Fault_CC_Denied throw activity of the Scope_
AuthorizeCreditCard scope activity in the Fusion Order Demo application. This
activity throws a fault for orders that are not approved.
7.
12.7.3 How to Roll Back Activities with a bpelx:rollback Extension in a Throw Activity
Section 13.1.1, "Oracle BPEL Process Manager Transaction Semantics" and Section 13.2,
"Introduction to Execution of One-way Invocations" describe transaction behavior
when you specify the bpelx:rollback extension. You can specify this extension
when designing a throw activity. This action rolls back all activities that are part of the
rolled back transaction.
To roll back activities with a bpelx:rollback extension in a throw activity:
1. Create a throw activity, as described in Section 12.7.1, "How to Create a Throw
Activity."
2.
To the right of the Namespace URI field, click Add to invoke the Fault Chooser
dialog.
3.
4.
5.
12-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1213
6.
Click Source.
The bpelx:rollback extension is defined as shown in Example 1218.
If the fault handler modifies fault data and then calls a rethrow activity, the
original fault data is rethrown, and not the modified fault data.
If a fault is captured using the functionality that enables message type faults with
one part defined using an element to be caught by fault handlers looking for the
same element type, then the rethrow activity rethrows the original message type
data.
Note:
3.
4.
Optionally enter a name or accept the default value, as shown in Figure 1214.
Using Fault Handling in a BPEL Process 12-33
5.
</assign>
<rethrow name="Rethrow_1"/>
</sequence>
</catch>
</faultHandlers>
<throw faultName="tns:error" faultVariable="fault"/>
</scope>
grouping enables you to collapse them into what appears to be a single element in
Oracle BPEL Designer.
Example 1221 shows a scope named Scope_FulfillOrder from the WebLogic
Fusion Order Demo application. This scope invokes the FulfillOrder Oracle
Mediator component, which determines the shipping method for the order.
Example 1221 Scope Activity
<scope name="Scope_FulfillOrder">
<variables>
<variable name="lFulfillOrder_InputVariable"
messageType="ns17:requestMessage"/>
</variables>
<sequence>
<assign name="Assign_OrderData">
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO"/>
<to variable="lFulfillOrder_InputVariable"
part="request" query="/ns4:orderInfoVOSDO"/>
</copy>
</assign>
<invoke name="Invoke_FulfillOrder"
inputVariable="lFulfillOrder_InputVariable"
partnerLink="FulfillOrder.FulfillOrder"
portType="ns17:execute_ptt" operation="execute"/>
</sequence>
</scope>
3.
4.
From the Component Palette, drag and define activities to build the functionality
within the scope. Figure 1216 provides details.
5.
Click OK.
12-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When complete, scope activity design can look as shown in Figure 1217. This
example shows the Scope_AuthorizeCreditCard scope activity of the Fusion
Order Demo application.
Figure 1217
In the Comment field, enter a brief description of the functionality of the scope.
3.
In the Image field, click the Search icon to optionally change the graphical image
for the scope.
4.
Click OK.
Your changes display in Oracle BPEL Designer, as shown in Figure 1218.
5.
A catch activity for catching faulted orders in which the credit card number is not
provided or the credit type is not valid.
A throw activity that throws a fault for orders that are not approved.
An assign activity that takes the credit card type, credit card number, and
purchase amount, and assigns this information to the input variable for the
CreditCardAuthorizationService service.
An invoke activity that calls a CreditCardAuthorizationService service to
retrieve customer information.
A switch activity that checks the results of the credit card validation.
12-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
CreditCard')"/>
<to variable="gOrderProcessorFaultVariable"
part="code"/>
</copy>
</assign>
<throw name ="Throw_NoCreditCard"
faultVariable="gOrderProcessorFaultVariable"
faultName="ns9:OrderProcessingFault"/>
</sequence>
</catch>
<catch faultName="ns2:InvalidCredit">
<sequence>
<assign name="Assign_InvalidCreditFault">
<copy>
<from expression="concat(bpws:getVariableData
('gOrderInfoVariable','/ns4:orderInfoVOSDO/
ns4:CardTypeCode'), ' is not a valid
creditcard type')"/>
<to variable="gOrderProcessorFaultVariable"
part="summary"/>
</copy>
<copy>
<from expression="string('CreditCardCheck - NOT VALID')"/>
<to variable="gOrderProcessorFaultVariable"
part="code"/>
</copy>
</assign>
<throw name="Throw_OrderProcessingFault"
faultName="ns9:OrderProcessingFault"
faultVariable="gOrderProcessorFaultVariable"/>
</sequence>
</catch>
</faultHandlers>
<sequence>
<assign name="Assign_CreditCheckInput">
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO/ns4:OrderTotal"/>
<to variable="lCreditCardInput" part="Authorization"
query="/ns8:AuthInformation/ns8:PurchaseAmount"/>
</copy>
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO/ns4:CardTypeCode"/>
<to variable="lCreditCardInput" part="Authorization"
query="/ns8:AuthInformation/ns8:CCType"/>
</copy>
<copy>
<from variable="gOrderInfoVariable"
query="/ns4:orderInfoVOSDO/ns4:AccountNumber"/>
<to variable="lCreditCardInput" part="Authorization"
query="/ns8:AuthInformation/ns8:CCNumber"/>
</copy>
</assign>
<invoke name="InvokeCheckCreditCard"
inputVariable="lCreditCardInput"
outputVariable="lCreditCardOutput"
partnerLink="CreditCardAuthorizationService"
portType="ns2:CreditAuthorizationPort"
operation="AuthorizeCredit"/>
<switch name="Switch_EvaluateCCResult">
<case condition="bpws:getVariableData('lCreditCardOutput','status','
/ns8:status') != 'APPROVED'">
<bpelx:annotation>
<bpelx:pattern>status <> approved</bpelx:pattern>
</bpelx:annotation>
<throw name="Throw_Fault_CC_Denied"
faultName="client:OrderProcessorFault"/>
</case>
/switch>
</sequence>
</scope>
The catch activity works within a scope to catch faults and exceptions before they
can throw the entire process into a faulted state. You can use specific fault names
in the catch activity to respond in a specific way to an individual fault.
The catchAll activity catches any faults that are not handled by name-specific
catch activities.
Example 1223 shows the syntax for catch and catchAll activities. Assume that a fault
named x:foo is thrown. The first catch is selected if the fault carries no fault data. If
there is fault data associated with the fault, the third catch is selected if the type of the
fault's data matches the type of variable bar. Otherwise, the default catchAll handler
is selected. Finally, a fault with a fault variable whose type matches the type of bar
and whose name is not x:foo is processed by the second catch. All other faults are
processed by the default catchAll handler.
Example 1223 Catch and CatchAll Activities
<faulthandlers>
<catch faultName="x:foo">
<empty/>
</catch>
<catch faultVariable="bar">
<empty/>
</catch>
<catch faultName="x:foo" faultVariable="bar">
<empty/>
</catch>
<catchAll>
<empty/>
</catchAll>
</faulthandlers>
12-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12.10.6 What You May Need to Know About the idempotent Property and Fault
Handling
If the idempotent deployment descriptor property is set to false in the
composite.xml file and the invocation of a partner link fails, recovery does not start
from the invoke activity. Relying on the idempotent property for retrying the invoke
activity is not recommended. Instead, recovery is attempted by fault handling you
have designed into the BPEL process (such as with a catchAll activity). As a best
practice, Oracle recommends that you instead use a fault policy to retry the invoke
activity.
Table 124 describes the behavior when the idempotent property is set to false and
partner link invocation either succeeds or fails.
Table 124
Then...
Successful
For example, assume your BPEL process includes the following design:
This setting causes the BPEL process to dehydrate immediately after execution of
this activity and be recorded in the dehydration store.
You can also set this property to false in the Edit Partner Link dialog.
Figure 1219 provides details.
For more information, see Section 8.4, "Managing Idempotence at the Partner Link
Operation Level."
A catchAll activity error handler in a scope activity catches faults and throws a
rollback fault.
If the invocation by the invoke activity to the partner link fails, recovery starts from
the catchAll activity error handler, and not from the invoke activity. The recovery from
the catchAll activity can be observed in the flow activity for the BPEL process in
Oracle Enterprise Manager Fusion Middleware Control.
This is by design. The idempotent property setting is checked after execution of the
invoke activity. If the execution failed and an exception is raised, the idempotent
property setting is never reached. The BPEL process service engine saves the instance
right after opening the catchAll activity. The instance must be saved because the
idempotent property is set to false. This is why recovery resumes in the catchAll
activity.
Oracle recommends that you instead recover the failed invoke activity with a fault
policy. For more information about creating fault polices, see Section 12.4, "Handling
Faults with the Fault Management Framework."
For more information about the idempotent property, see Section C.1, "Introduction
to Deployment Descriptor Properties."
12-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1220
Add Catch
This creates a catch activity on the right side of the scope activity.
2.
3.
4.
To the right of the Namespace URI field, click the Search icon to select the fault.
5.
Select the fault in the Fault Chooser dialog, and click OK.
The namespace URI for the selected fault displays in the Namespace URI field.
Your fault selection also automatically displays in the Local Part field.
Figure 1221 provides an example of a Catch dialog. This example shows the
selectionFailure catch activity of the Scope_AuthorizeCreditCard scope activity
in the Fusion Order Demo application. This catch activity catches orders in which
the credit card number is not provided.
Figure 1221
Catch Dialog
6.
7.
Click OK.
Figure 1222 provides an example of two catch activities for the Scope_
AuthorizeCreditCard scope activity. The second catch activity catches credit types
that are not valid.
12-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12.10.9 How to Create an Empty Activity to Insert No-Op Instructions into a Business
Process
There is often a need to use an activity that does nothing. An example is when a fault
must be caught and suppressed. In this case, you can use the empty activity to insert a
no-op instruction into a business process.
To create an empty activity:
1. In the Component Palette, expand BPEL Constructs.
2.
3.
Figure 1223
Empty Activity
4.
5.
Click OK.
If no catch or catchAll activity is selected, the fault is not caught by the current scope
and is rethrown to the immediately enclosing scope. If the fault occurs in (or is
rethrown to) the global process scope, and there is no matching fault handler for the
fault at the global level, the process terminates abnormally. This is as though a
terminate activity (described in Section 12.13.1, "Stopping a Business Process Instance
with the Terminate Activity in BPEL 1.1") had been performed.
3.
4.
5.
6.
7.
12-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1225
In a fault handler of the scope that immediately encloses the scope for which to
perform compensation.
In the compensation handler of the scope that immediately encloses the scope for
which to perform compensation.
For example:
<compensate scope="RecordPayment"/>
If a scope being compensated by name was nested in a loop, the BPEL process service
component invokes the instances of the compensation handlers in the successive
iterations in reverse order.
If the compensation handler for a scope is absent, the default compensation handler
invokes the compensation handlers for the immediately enclosed scopes in the reverse
order of the completion of those scopes.
12-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The compensate form, in which the scope name is omitted in a compensate activity,
explicitly invokes this default behavior. This is useful when an enclosing fault or
compensation handler must perform additional work, such as updating variables or
sending external notifications, in addition to performing default compensation for
inner scopes. The compensate activity in a fault or compensation handler attached to
the outer scope invokes the default order of compensation handlers for completed
scopes directly nested within the outer scope. You can mix this activity with any other
user-specified behavior except for the explicit invocation of the nested scope within
the outer scope. Explicitly invoking compensation for such a scope nested within the
outer scope disables the availability of default-order compensation.
3.
4.
Figure 1226
5.
Compensate Activity
3.
4.
5.
12-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<catchAll>
<compensateScope target="ScopeAssignScreditRating2" />
</catchAll>
</faultHandlers>
<sequence>
<scope name="ScopeAssignScreditRating2">
<compensationHandler>
<!-- undo work -->
</compensationHandler>
<!-- do some work -->
</scope>
<!-- do more work -->
<!-- a fault is thrown here; results of ScopeAssignScreditRating2 must be
undone -->
</sequence>
</scope>
12.13.1 Stopping a Business Process Instance with the Terminate Activity in BPEL 1.1
The terminate activity immediately terminates the behavior of a business process
instance within which the terminate activity is performed. All currently running
activities must be terminated as soon as possible without any fault handling or
compensation behavior. The terminate activity does not send any notifications of the
status of a BPEL process service component. If you are going to use the terminate
activity, first program notifications to the interested parties.
Drag a Terminate activity into the designer. Figure 1228 provides an example.
Figure 1228
Terminate Activity
3.
4.
5.
Click OK.
12.13.2 Immediately Ending a Business Process Instance with the Exit Activity in BPEL
2.0
You can use the exit activity to immediately end all currently running activities on all
parallel branches without involving any termination handling, fault handling, or
compensation handling mechanisms. This activity is useful for environments in which
there may not be a reasonable way for dealing with unexpected, severe failures.
Any open conversations are also impacted by the exit activity.
For example, other partners interacting with the process may wait for
a response that never arrives.
Note:
Drag an Exit activity into the section of your BPEL process in which you want to
execute the exit activity.
3.
4.
5.
12-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When complete, the exit activity in a BPEL process appears similar to that shown
in Figure 1230.
Figure 1230
Preassert: This condition is executed before the invoke or reply activity send out
the outbound message.
Example 1233 shows the postassertion condition schema definition in BPEL 2.0. Note
the differences between BPEL 1.1 and BPEL 2.0.
Example 1233 Postassertion Condition Schema Definition in BPEL 2.0
<invoke | receive | onMessage>
standard-elements
<bpelx:postAsserts>
<bpelx:postAssert faultName="QName">
<bpelx:expression expressionLanguage="anyURI"?>expression
</bpelx:expression>
<bpelx:message expressionLanguage="anyURI"?>expression</bpelx:message>
</bpelx:postAssert>
</bpelx:postAsserts>
</invoke | receive | onMessage>
Example 1235 shows the preassertion condition schema definition in BPEL 1.1.
Example 1235 Preassertion Condition Schema Definition in BPEL 1.1
<invoke | reply>
standard-elements
<bpelx:preAssert name="NCName" expression="string" message="string"
faultName="QName"/>
</invoke | reply>
12-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 1237 shows the preassertion condition schema definition in BPEL 2.0. Note
the differences between BPEL 1.1 and BPEL 2.0.
Example 1237 Preassertion Condition Schema Definition in BPEL 2.0
<invoke | reply>
standard-elements
<bpelx:preAsserts>
<bpelx:preAssert faultName="QName">
<bpelx:expression expressionLanguage="anyURI"?>expression</bpelx:expression>
<bpelx:message expressionLanguage="anyURI"?>expression</bpelx:message>
</bpelx:preAssert>
</bpelx:preAsserts>
</invoke | reply>
<empty/>
</catch>
</faultHandlers>
<sequence>
<invoke name="invokeCR" partnerLink="creditRatingService"
portType="services:CreditRatingService" operation="process"
inputVariable="crInput" outputVariable="crOutput">
<bpelx:postAssert name="negativeCredit"
expression="$crOutput.payload/tns:rating > 0"
faultName="services:NegativeCredit" message="'Negative
Credit'" />
</invoke>
</sequence>
</scope>
bpelx:preAssert: If you select Pre Assert, the condition is executed before the
invoke or reply activity send out the outbound message.
bpelx:postAssert: If you select Post Assert, the condition is executed after an
invoke activity, receive activity, or onMessage branch receives the inbound
message.
12-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For information on using the Assertions tab, see Section 12.14.2, "How to Create
Assertion Conditions."
Example 1243 shows the syntax for the faultname and message attributes.
Example 1243 faultName and message Attributes Syntax in BPEL 1.1
<bpelx:postAssert name="Assert_2"
message=multiple post assert Greater value fired
faultName="ns2:GreaterValue"
expression="bpws:getVariableData('invar','payload','/ns1:process/ns1:input') <
500"/>
The specified fault is thrown whenever the assertion condition evaluates to false.
Analysis is performed on the faultName QName to ensure that it properly resolves to
a fault that has been defined in the partner WSDL portType. The message expression
is a general expression that can evaluate to any XPath value type (string, number, or
boolean). If a nonstring value is returned, the string equivalent of the value is used.
inputVariable="crInput" outputVariable="crOutput">
<bpelx:postAssert name="negativeCredit"
expression="$crOutput.payload/tns:rating >
0"
faultName="services:NegativeCredit" message="'Negative Credit'"
/>
<bpelx:postAssert name="insufficientCredit"
expression="$crOutput.payload/tns:rating > 600"
faultName="services:InsufficientCredit" message="'Insufficient
Credit'" />
</invoke>
In Example 1244, the assertion with the expression that checks that the response
credit rating is greater than zero is evaluated first. Table 125 describes the assertion
behavior.
Table 125
Assertion Behavior
Any number of assertions can be nested. For no fault to be thrown from the activity, all
assertions specified must evaluate to true.
This construct enables you to apply multiple levels of validation on an incoming
payload, similar to if...else if...else statements in Java.
To enable a fault to always be thrown regardless of validation logic, the assertion
expression can be specified as false(). This is similar to the else construct in Java.
12.14.1.4 Use of Built-in and Custom XPath Functions and $variable References
You can also use built-in and custom XPath functions and $variable references
within the assertion condition. Example 1245 provides several examples.
Example 1245 Built-in and Custom XPath Functions in BPEL 1.1
<bpelx:postAssert expression="bpws:getVariableData( 'crOutput', 'payload',
'/tns:rating' ) > 0" ... />
<bpelx:postAssert expression="custom:validateRating()" ... />
<bpelx:postAssert xmlns:fn='http://www.w3.org/2005/xpath-functions'
expression="fn:false()" ... />
If an error is thrown by the XPath expression evaluation, the error is wrapped with a
BPEL fault and thrown from the activity.
Faults that are thrown from a request-response invoke activity, receive activity, or
onMessage branch of a pick or scope activity because of a failed assertion evaluation
can be caught and handled by BPEL's fault management framework. For information,
see Section 12.4, "Handling Faults with the Fault Management Framework."
12-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Faults that are not caught and handled within a BPEL process flow are thrown from a
BPEL component if the component WSDL declares the fault on the operation. If the
fault is not declared on the operation, the fault is converted into a
FabricInvocationException, which is a runtime fault. This fault can be caught
by any caller components (including BPEL components), but the fault type is no longer
the one originally thrown (however, the fault message string still retains traces of the
original fault message).
For more information about runtime faults, see Section 12.3, "Introduction to the
Business and Runtime Fault Categories of BPEL Faults."
For more information about fault policies, see Section 12.4, "Handling Faults with the
Fault Management Framework."
Analysis of the assertion expression is performed by the BPEL compiler and errors are
reported if an expression does not evaluate to an XML schema boolean type. For
custom XPath functions, this type of analysis is not performed.
For information on using the standalone assert activity, see Section 12.14.2, "How to
Create Assertion Conditions."
3.
Drag a Receive activity, Invoke activity, Pick activity, or Scope activity into the
designer.
4.
Expand the Receive, Invoke, or onMessage branch of the Pick or Scope activity.
5.
6.
If you are creating an assertion for a BPEL 1.1 project, perform the following tasks.
Otherwise, go to Step 7.
a.
b.
Table 126
Element
Description
Pre Assert
If selected, the condition is executed before the invoke or reply activity send out
the outbound message.
Post Assert
Based on your selection, the Pre Assert or Post Assert dialog is displayed.
7.
If you are creating an assertion for a BPEL 2.0 project, perform the following tasks.
a.
Table 127
To Create A...
Select The...
Preassertion condition
Postassertion condition
12-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
b.
Figure 1232
Specify values for the assertion condition, as shown in Figure 1233. For this
example, Post Assert was selected for an assertion condition on a receive activity
in a BPEL 1.1 project.
a.
Select the Fault QName to be thrown by clicking the Search icon and selecting
an existing fault from the Fault Chooser dialog. You can also provide your
own values for the Namespace URI and Local Part fields of the fault. If you
do not specify anything for the Fault QName, then a
bpelx:assertFailure fault is thrown.
Figure 1233
9.
When complete, click OK to return to the Assertions tab of the activity. The
completed assertion condition is displayed, as shown in Figure 1234.
1.
2.
3.
4.
5.
To the right of the Expression field, click the XPath Expression Builder icon.
6.
Create an expression.
7.
12-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1236
8.
Assert Dialog
For more information about setting System MBean Browser properties, see Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
If the condition evaluates to true, no fault is thrown from the assert activity and the
remaining activities in the BPEL process flow are executed normally.
Example 1249 Assertion Condition in a Standalone Assert Activity in BPEL 1.1
<bpelx:assert expression="true()bpws:getLinkStatus()" message="'got assertion
failure on true expression'"
12-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
13
Transaction and Fault Propagation
Semantics in BPEL Processes
13
This chapter describes transaction and fault propagation semantics in Oracle BPEL
Process Manager. It describes how to configure the transaction behavior for BPEL
instances with initiating calls and the execution of one-way invocations.
This chapter includes the following sections:
There is no message loss. Either the invocation message is inserted into the
dehydration store for processing or the consumer is notified through a fault.
In release 10.1.3.x, there were several properties to set on the consuming process (that
is, on the partner link) and the providing process. This enabled you to chain an
execution into a single global transaction. On the consuming side, you set
transaction=participate on the partner link binding in the bpel.xml file. On
the providing side, you set transaction=participate in the
<configurations> section of bpel.xml.
In release 11g, you only must set a new transaction property on the BPEL
component being called (known as the callee process). You add
bpel.config.transaction as follows:
This property configures the transaction behavior for BPEL instances with initiating
calls.
Example 131 provides details.
Example 131
<component name="InternalWarehouseService">
<implementation.bpel src="InternalWarehouseService.bpel"/>
<property name="bpel.config.transaction"
many="false" type="xs:string">required | requiresNew</property>
</component>
There are two possible values: required (the default value) and requiresNew.
Table 131 describes these values and summarizes the behavior of the BPEL instance
based on the settings.
Table 131
With bpel.config.transaction
Set to requiresNew...
For...
Request/response
(initiating) invocations
13-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If The BPELCallee...
Is saved.
Is rolled back.
Is rolled back.
Gets FaultTwo.
Is rolled back.
If The BPELCallee...
Gets the fault and can catch it. The BPELCaller owns
the transaction. Therefore, if it catches it, the
transaction is committed. If the BPELCaller does not
handle it, a global rollback occurs.
Gets FaultTwo.
If you add a fault handler in BPELMaster to catch the fault from BPELChild and throw
a rollback fault, the transaction is globally rolled back.
This feature enables you to control transaction boundaries and model end-to-end
transactional flows (if your sources and targets are also transactional).
For information about specifying the bpelx:rollback extension with a throw
activity, see Section 12.7.3, "How to Roll Back Activities with a bpelx:rollback
Extension in a Throw Activity."
<wsdl:operation name="process">
<wsdl:input message="client:OrderProcessorRequestMessage"/>
</wsdl:operation>
This causes the BPEL process service engine to split the execution into two parts:
For the first part, and always inside the caller transaction, the insertion into the
dlv_message table of the dehydration store occurs (in release 10.1.3.x, it was
inserted into the inv_message table).
For the second part, the transaction and the new thread execute the work items,
and a new instance is created.
This has several advantages in terms of scalability, because the service engines thread
pool (invoker threads) executes when a thread is available. However, the disadvantage
is that there is no guarantee that it executes immediately.
If you require a synchronous-type call based on a one-way operation, then you can use
the onewayDeliveryPolicy property, which is similar to the
deliveryPersistPolicy property of release 10.1.3.x.
Specify bpel.config.oneWayDeliveryPolicy as follows:
13-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
sync: Direct invocation occurs on the same thread. The scheduling of messages in
the invoke queue is bypassed, and the BPEL instance is invoked synchronously. In
some cases this setting can improve database performance.
If...
13-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
14
14
Embed Java code snippets into a BPEL process with the bpelx:exec tag
14.2.2 What You May Need to Know About Wrapping Java Code as a SOAP Service
A Java application wrapped as a SOAP service has the following drawbacks:
There may be reduced performance due to the nature of converting between Java
and SOAP, and back and forth.
Since SOAP inherently has no support for transactions, this method loses atomic
transactionality, that is, the ability to perform several operations in an all-or-none
mode (such as debiting one bank account while crediting another, where either
both transactions must be completed, or neither of them are completed).
14.2.3 How to Embed Java Code Snippets into a BPEL Process with the bpelx:exec Tag
You can embed Java code snippets directly into the BPEL process using the Java BPEL
exec extension bpelx:exec. The benefits of this approach are speed and
transactionality. It is recommended that you incorporate only small segments of code.
BPEL is about separation of business logic from implementation. If you remove a lot of
Java code in your process, you lose that separation. Java embedding is recommended
for short utility-like operations, rather than business code. Place the business logic
elsewhere and call it from BPEL.
The server executes any snippet of Java code contained within a bpelx:exec activity,
within its Java Transaction API (JTA) transaction context.
The BPEL tag bpelx:exec converts Java exceptions into BPEL faults and then adds
them into the BPEL process.
The Java snippet can propagate its JTA transaction to session and entity beans that it
calls.
For example, a SessionBeanSample.bpel file uses the bpelx:exec tag shown in
Example 141 to embed the invokeSessionBean Java bean:
Example 141
bpelx:exec Extension
(Element)getVariableData("input","payload","/ssn");
int rating = ratingService.getRating( ssn.getNodeValue() );
addAuditTrailEntry("Rating is: " + rating);
}
}
}
}
setVariableData("output", "payload",
"/tns:rating", new Integer(rating));
catch (NamingException ne) {
addAuditTrailEntry(ne);
catch (ClassNotFoundException cnfe) {
addAuditTrailEntry(cnfe);
catch (CreateException ce) {
addAuditTrailEntry(ce);
catch (RemoteException re) {
addAuditTrailEntry(re);
}
]]>
</bpelx:exec>
<extensionActivity>
<bpelx:exec language="java">
<![CDATA[
java code
]]>
</bpelx:exec>
</extensionActivity>
When you drag a Java Embedding activity into a BPEL process in Oracle BPEL
Designer, the <extensionActivity> element and bpelx:exec tag are
automatically added.
Example 143 shows the import syntax for BPEL 2.0:
Example 143
The BPEL 2.0 import syntax differs from BPEL 1.1, which uses
the following syntax:
Note:
Example 144 shows a BPEL file with two Java embedding activities for a project that
supports BPEL version 2.0.
Example 144
. . .
. . .
<import location="oracle.xml.parser.v2.XMLElement"
importType="http://schemas.oracle.com/bpel/extension/java"/>
. . .
<sequence>
. . .
<extensionActivity>
<bpelx:exec language="java">
XMLElement elem = (XMLElement) getVariableData("output", "payload");
elem.setTextContent("set by java exec");
</bpelx:exec>
</extensionActivity>
<extensionActivity>
<bpelx:exec language="java">
<![CDATA[XMLElement elem = (XMLElement) getVariableData("output",
"payload");
String t = elem.getTextContent();
elem.setTextContent(t + ", set by java exec 2");]]>
</bpelx:exec>
</extensionActivity>
. . .
</sequence>
</process>
For information about using this activity, see Section 14.4, "Using Java Embedding in a
BPEL Process in Oracle JDeveloper."
14-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 141
Method Name
Description
JNDI access
long getInstanceId( )
void
setCompositeInstanceTitle(String
title)
Access preference
void addAuditTrailEntry(String
message, Object detail)
For example, assume you create a BPEL process service component in a SOA
composite application that invokes a service interface through a SOAP reference
binding component. For this example, the service interface used is an Oracle
Application Development Framework (ADF) Business Component.
Incorporating Java and Java EE Code in a BPEL Process 14-5
Create a SOA application that includes a BPEL process service component. Ensure
that the BPEL process service component is exposed as a composite service. This
automatically connects the BPEL process to an inbound SOAP service binding
component.
3.
Import the Oracle ADF Business Component service WSDL into the SOA
composite application.
4.
Create a web service binding to the Oracle ADF Business Component service
interface.
5.
Create a partner link for the Oracle ADF Business Component service
portType.
b.
Create an assign activity. For this example, this step copies data (for example, a
static XML fragment) into a variable that is passed to the Oracle ADF Business
Component service.
c.
Create an invoke activity and connect to the partner link you created in Step
5a.
6.
Connect (wire) the partner link reference to the composite reference binding
component. This reference uses a web service binding to enable the Oracle ADF
Business Component service to be remotely deployed.
7.
8.
Invoke the SOA application from the Test Web Service page in Oracle Enterprise
Manager Fusion Middleware Control.
For more information on creating Oracle ADF Business Components, see Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
For more information on invoking a SOA composite application, see Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
14-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
At the bottom of the BPEL Service Engine Properties page, click More BPEL
Configuration Properties.
3.
Click BpelcClasspath.
4.
5.
Click Apply.
6.
Click Return.
In addition, ensure that the JARs are loaded by the SOA composite application.
To add custom classes:
Copy the classes to the classes directory.
1.
2.
Run ant.
3.
Note:
3.
Double-click the Java Embedding activity to display the Java Embedding dialog.
4.
5.
In the Code Snippet field, enter (or cut and paste) the Java code. Figure 141
provides details.
Note:
14.4.2 What You May Need to Know About Using thread.sleep() in a Java Embedding
Activity
If you create and deploy a BPEL process that uses thread.sleep() in a Java
Embedding activity, the executing thread is blocked and the transaction associated
with that thread is prevented from committing. This causes BPEL instances to appear
only after the wait is over, which is the expected behavior.
Instead, use a wait activity, which releases the resource upon entering the activity and
enables the ongoing transaction to commit and the BPEL instance data to hydrate into
the data store.
</bpelx:exec>
<bpelx:exec name="ModifyInternalSDO" version="1.5" language="java">
<![CDATA[try{
Object o = getVariableData("VarSDO");
Object out = getVariableData("ExtSDO");
14-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 147 provides an example of the Java classes modifySDO(o) and print(o)
that are embedded in the BPEL file.
Example 147
Java Classes
14.6.1 How to Configure the BPEL Connection Manager Class to Take Precedence
To configure the BPEL Connection Manager class to take precedence:
1. Start Oracle JDeveloper.
2.
3.
4.
5.
6.
Navigate to the location of the custom JAR file, and click Select.
This adds the custom Connection Manager JAR file to the classpath.
7.
Click OK.
8.
14-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
15
15
This chapter describes how to use events and timeouts. It describes how to create a
pick activity to select to continue a process or wait, set timeouts for request-response
operations on receive activities, create wait activities to set an expiration time, create
OnEvent branches in BPEL 2.0 to wait for message arrival, and set timeouts on
synchronous processes.
This chapter includes the following sections:
15-1
An invoke activity initiates a service, in this case, a request for a loan offer from
Star Loan.
2.
onMessage
This condition has code for receiving a reply in the form of a loan offer from
the Star Loan web service. The onMessage code matches the code for receiving
a response from the Star Loan web service before a timeout was added.
onAlarm
This condition has code for a timeout of one minute. This time is defined as
PT1M, which means to wait one minute before timing out. In this timeout
setting:
S is for seconds
H is for hour
D is for day
Y is for year
In the unlikely event that you want a time limit of 1 year, 3 days, and 15
seconds, you enter it as PT1Y3D15S. The remainder of the code sets the loan
variables selected and approved to false, sets the annual percentage rate
(APR) at 0.0, and copies this information into the loanOffer variable.
The time duration format is specified by the BPEL standard. For more detailed
information on the time duration format, see the duration section of the most
current XML Schema Part 2: Datatypes document at:
http://www.w3.org/TR/xmlschema-2/#duration
3.
The pick activity condition that completes first is the one that the BPEL process
service component executes. The other branch is not executed.
15-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Initiate
service
<invoke>
<pick>
WSDL
Wait for
callback
<onMessage>
Time out in
1M
<onAlarm>
Logic Post
Callback
Logic Post
Timeout
Star
Loan
Note:
3.
15-3
4.
5.
Edit its attributes to receive the response from the loan service. Figure 153
provides an example.
6.
7.
15-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Double-click the OnAlarm branch of the pick activity and set its time limit to 1
minute. Figure 155 provides an example.
9.
Click OK.
Pick Activity
<pick>
<!-- receive the result of the remote process -->
<onMessage partnerLink="LoanService"
portType="services:LoanServiceCallback"
operation="onResult" variable="loanOffer">
<assign>
15-5
<copy>
<from variable="loanOffer" part="payload"/>
<to variable="output" part="payload"/>
</copy>
</assign>
</onMessage>
<!-- wait for one minute, then timesout -->
<onAlarm for="PT1M">
<assign>
<copy>
<from>
<loanOffer xmlns="http://www.autoloan.com/ns/autoloan">
<providerName>Expired</providerName>
<selected type="boolean">false</selected>
<approved type="boolean">false</approved>
<APR type="double">0.0</APR>
</loanOffer>
</from>
<to variable="loanOffer" part="payload"/>
</copy>
</assign>
</onAlarm>
</pick>
15.2.3 What You May Need to Know About Simultaneous onMessage Branches in
BPEL 2.0
Oracle BPEL Process Managers implementation of BPEL 2.0 does not support
simultaneous onMessage branches of a pick activity.
When a process has a pick activity with two onMessage branches as its starting
activity (both with initiate set to join in their correlation definitions) and an
invoking process that posts the invocations one after the other, it is assumed that both
invocations reach the same instance of the invoked process. However, in Oracle BPEL
Process Managers implementation of BPEL 2.0, two instances of the invoked process
are created for each invocation.
This is the expected behavior, but it differs from what is described in the BPEL 2.0
specification.
For example, assume you have synchronous BPEL process A, which has a flow activity
with two parallel branches:
The idea is to create one instance of the invoked process and ensure that the second
invocation happens after the first instance is already active and running.
BPEL process B has a pick activity with createInstance set to yes. The pick
activity has two onMessage branches within it:
One branch is for the processMessage1 operation. For this operation, it goes to
sleep for about 10 seconds.
The other branch is for the processMessage2 operation. For this operation, it waits
for five seconds.
15-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Both operations have the same input message type and correlation is defined with
initiate set to join.
The expectation is that the processMessage1 invocation is invoked immediately and
the BPEL process B instance is created, which should sleep for ten seconds. After five
seconds, the invoking process should then post the processMessage2 invocation to
BPEL process B and this invocation should go to the already existing instance instead
of creating a new one (since the correlation ID is the same and initiate is set to
join).
However, for each invocation, a new instance of BPEL process B is created and the
result cannot be predicted.
If the processMessage2 operation branch finishes first, then the subsequent assign
operation fails because the input variable from processMessage1 is assumed to be
null (for that instance).
If the processMessage1 operation branch finishes first, then the process returns
callback data with only partial information (does not include the input from
processMessage2).
In Oracle BPEL Process Managers implementation, either one of the two operations
(processMessage1 or processMessage2) creates a new instance. This is implemented so
that database queries do not need to be made to see if there are already instances
created.
The workaround is to create two processes that are initiated by the two different
operations.
This provides an alternative to using the onMessage and onAlarm branches of a pick
activity to specify a timeout duration for partner callbacks.
Figure 156 shows the Timeout tab of a midprocess receive activity in which you set a
timeout.
15-7
For information about key concepts to understand before setting timeouts for
request-reply and in-only operations in receive activities, see Section 15.3.1,
"Introducing Timeouts for Request-Reply and In-Only Operations."
For information about how to set a timeout in a receive activity in Oracle JDeveloper,
see Section 15.3.2, "How to Set Timeouts in Receive Activities."
Events added to the BPEL instance audit trail during an activity timeout
Timeout Settings Relative from When the Activity is Invoked in BPEL 1.1
<receive | bpelx:for="duration-expr">
standard-elements
</receive>
15-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Timeout Settings Relative from When the Activity is Invoked in BPEL 2.0
<receive | <bpelx:for>duration-expr</bpelx:for>
standard-elements
</receive>
This type uses the bpelx:for attribute to specify a static value or an XPath
expression that must evaluate to an XML schema type duration. Only one of the
bpelx:for or bpelx:until attributes is permitted for an activity.
If the XPath expression evaluates to a negative duration, the timeout is ignored and an
event is logged to the instance audit trail indicating that the duration value is invalid.
Once a valid duration value is retrieved, the expiration date for the activity is set to the
current node time (or cluster time after this is available), plus the duration value. For
example, the duration value bpelx:for="'PT5M'" specifies that the activity expects
an inbound message to arrive no later than five minutes after the activity has started
execution.
The timeout setting attribute does not apply to the onMessage
branch of a pick activity because the same functionality currently
exists with the onMessage and onAlarm branches of that activity.
Note:
A receive activity can only time out after it has been instantiated, which is not the case
with entry receive activities.
<receive bpelx:until="deadline-expr">
standard-elements
</receive>
<receive <bpelx:until>"deadline-expr"</bpelx:until>
</receive>
The expected expiration time for the bpelx:until attribute must be at least two
seconds ahead of the current time. Otherwise, the timer scheduling is ignored and
skipped, just as if the timer was never specified.
The bpelx:until attribute specifies a static value or an XPath expression that must
evaluate to an XML schema type datetime or date. Only one of the bpelx:for or
bpelx:until attributes is permitted for an activity.
15-9
XPath version 1.0 is not XML schema-aware. Therefore, none of the built-in functions
of XPath version 1.0 can create or manipulate dateTime or date values. However, it
is possible to perform one of the following:
Write a constant (literal) that conforms to XML schema definitions and use that as
a deadline value.
Extract a field from a variable (part) of one of these types and use that as a
deadline value.
XPath version 1.0 treats that literal as a string literal, but the result can be interpreted
as a lexical representation of a dateTime or date value.
Once a valid datetime or date value has been retrieved, the expiration date for the
activity is set to the specified date. For example, the datetime value
bpelx:until="'2009-12-24T18:00+01:00'" specifies that the activity expects
an inbound message to arrive no later than Dec 24, 2009 6:00 pm UTC+1 after the
activity has started execution.
The timeout setting attribute does not apply to the onMessage
branch of a pick activity because the same functionality currently
exists with the onMessage and onAlarm branches of the pick activity.
Note:
Midprocess receives
A receive activity can only time out after it has been instantiated, which is not the case
with entry receive activities.
Example 156 shows the syntax for using XPath expressions in BPEL 1.1.
Example 156
BPEL 1.1
<bpelx:for="bpws:getVariableData('input', 'payload',
'/tns:waitValue/tns:for')"/>
<bpelx:until="bpws:getVariableData('input', 'payload',
'/tns:waitValue/tns:until')"/>
15-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
15.3.1.5 Event Added to the BPEL Instance Audit Trail During an Activity Timeout
Once a bpelx:timeout fault is thrown from a timed-out activity, an event is logged
to the instance audit trail indicating that the activity has timed out, as opposed to
having received the expected callback message from its partner.
3.
4.
5.
6.
7.
To specify a timeout setting relative from when the activity is invoked, click
the For button and enter a value or click the Expression button and specify an
XPath expression.
To specify a timeout setting as an absolute deadline for a request-response
operation, click the Until button and enter a value or click the Expression
button and specify an XPath expression.
Static Duration
bpelx:for="'PT5M'"/>
For example, if you specified that the activity expects an inbound message to arrive no
later than January 24, 2010 11:00 AM UTC+1 after the activity has started execution,
the syntax displays as shown in Example 158.
Example 158
datetime Value
bpelx:until="'2010-01-24T11:00:00-08:00'"/>
15-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For example, if you specified an XPath expression to obtain a value for a timeout
relative from when the activity is invoked, syntax similar to that shown in
Example 159 can display.
Example 159
XPath Expression
bpelx:for="bpws:getVariableData('inputVariable','payload','/tns:waitValue/tns:for'
)"/>
Wait times cannot be guaranteed if they are scheduled with other events that
require processing. Due to this additional processing, the actual wait time can be
greater than the wait time specified in the BPEL process.
Wait times of less than two seconds are ignored by the server. Wait times above
two seconds, but less than one minute, may not get executed in the exact, specified
time. However, wait times in minutes do execute in the specified time.
The default value of 2 seconds for wait times is specified with the MinBPELWait
property in the System MBean Browser of Oracle Enterprise Manager Fusion
Middleware Control. You can set this property to any value and the wait delay is
bypassed for any waits less than MinBPELWait.
Quartz version 1.6 is supported for scheduling expiration
events on wait activities.
Note:
From the SOA Infrastructure menu, select SOA Administration > BPEL
Properties.
2.
At the bottom of the BPEL Service Engine Properties page, click More BPEL
Configuration Properties.
3.
Click MinBPELWait.
4.
5.
Click Apply.
6.
Click Return.
Specifying Events to Wait for Message Arrival with an OnEvent Branch in BPEL 2.0
2.
3.
4.
In the For section, enter the amount of time for which to wait.
5.
In the Until section, select the deadline for which to wait, as shown in Figure 158.
Specifying Events to Wait for Message Arrival with an OnEvent Branch in BPEL 2.0
is being processed. You cannot expect these interactions to occur only at specific points
in the business order processing. An event handler such as an onEvent branch enables
the business process to accept requests (such as status request, modification request, or
cancellation request) to arrive in parallel to the primary business logic flow.
The onEvent event handlers are associated with an enclosed scope. The onEvent event
handlers are enabled when their scope is initialized and disabled when their scope
ends. When enabled, any number of events can occur. They are processed in parallel to
the scopes primary activity and in parallel to each other. Message events also
represent service operations exposed by a process and modeled as onEvent elements.
Event handlers cannot create new process instances. Therefore, message events are
always received by a process instance that is already active.
Figure 1510
OnEvent Dialog
3.
In the Partner Link field, click the Search icon to select the partner link that
contains the endpoint reference on which the message is expected to arrive.
The Port Type and Operation fields define the port type and operation invoked by
the partner to cause the event.
4.
Specify a method for receiving the message from the partner through use of a
variable or From Parts element.
5.
6.
15-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
16
16
Stage items at the shipping dock after items for each line are available.
To perform these tasks, create a master process to check and validate each header and
multiple BPEL processes to check and validate each line item.
Potential coordination points are as follows:
The master process must signal the detail processes that header validation is
successful and to continue processing.
Each detail process must signal the master process after line item validation is
complete.
Each detail process must signal the master process after the line item is available in
inventory.
16-1
After all line items are available, the master must signal each detail process to
move its line item to the shipping dock (the dock may become too crowded if
items are simply moved as soon as they are available).
After all lines have been moved, the master process must execute logic to ship the
fulfilled order to the customer.
Figure 161 provides an overview of the header and line item validation coordination
points between one master process and two detail processes.
Figure 161 Master and Detail Coordination Overview (One BPEL Process to Two Detail Processes)
Sales Order 1
Sales Order 2
Header
- Customer Information
- Ship-To Address
Line Items
- Item Names
- Item Number
- Price
- Quantity
Master BPEL
Process
Validates Header
Completes
Header
Validation
and Signals
Detail
Process to
Continue
Completes
Line
Validation
and Signals
Master
Process
Detail BPEL
Process 1
Validates Header
Completes
Header
Validation
and Signals
Detail
Process to
Continue
Completes
Line
Validation
and Signals
Master
Process
Header
- Customer Information
- Ship-To Address
Line Items
- Item Names
- Item Number
- Price
- Quantity
Detail BPEL
Process 2
Validates Line Items
The following BPEL process activities coordinate actions between the master and
detail processes:
Both activities are coordinated with label attributes defined in the BPEL process files.
Labels are declared per master process definition.
Figure 162 provides an overview of the BPEL process flow coordination.
16-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 162 Master and Detail Syntax Overview (One BPEL Process to One Detail
Process)
Master Process
Detail Process
Signal Activity
label=startDetailProcess
to=details
Invoke Activity
partnerlink=DetailProcess
....
....
bpelx:invokeAsDetail=true
Signal Activity
label=CompleteDetailProcess
to=master
As shown in Figure 162, each master and detail process includes a signal and receive
signal activity. Table 161 describes activity responsibilities based on the type of
process in which they are defined.
Table 161
If A...
Contains A...
Then...
Master process
Signal activity
Detail process
Detail process
Signal activity
Master process
If the signal activity executes before the receive signal activity, the state set by the
signal activity is persisted and still effective for a later receive signal activity to read.
<process name="MasterProcess"
. . .
. . .
<partnerLinks>
<partnerLink name="client"
partnerLinkType="tns:MasterProcess"
myRole="MasterProcessProvider"
partnerRole="MasterProcessRequester"/>
<partnerLink name="DetailProcess"
16-3
partnerLinkType="dp:DetailProcess"
myRole="DetailProcessRequester"
partnerRole="DetailProcessProvider"/>
<partnerLink name="DetailProcess1"
partnerLinkType="dp1:DetailProcess1"
myRole="DetailProcess1Requester"
partnerRole="DetailProcess1Provider"/>
<partnerLink name="DetailProcess2"
partnerLinkType="dp2:DetailProcess2"
myRole="DetailProcess2Requester"
partnerRole="DetailProcess2Provider"/>
</partnerLinks>
A signal activity shows the label value and the detail process coordinated with this
master process. The label value (startDetailProcess) matches with the label value
in the receive signal activity of all detail processes. This ensures that the signal is
delivered to the correct process. There is one signal process per receive signal process.
The master process signals all detail processes at runtime. This syntax shows a signal
activity in a BPEL process that supports BPEL version 1.1.
<bpelx:signal name="notifyDetailProcess" label="startDetailProcess" to="details"/>
Note:
<extensionActivity>
<bpelx:signal name="notifyDetailProcess"
label="startDetailProcess" to="details"/>
</extensionActivity>
Assign, invoke, and receive activities describe the interaction between the master and
detail processes. This example shows interaction between the master process and one
of the detail processes (DetailProcess). Similar interaction is defined in this BPEL
file for all detail processes.
In the invoke activity, ensure that the Invoke as Detail checkbox is selected.
Figure 163 provides details.
Figure 163 Invoke As Detail Checkbox
bpelx:invokeAsDetail Attribute
<assign>
<copy>
<from variable="input" part="payload" query="/tns:processInfo/tns:value"/>
<to variable="detail_input" part="payload" query="/dp:input/dp:number"/>
</copy>
</assign
16-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The master BPEL process includes a receive signal activity. This activity indicates that
the master process waits until it receives a signal from all of its detail processes. The
label value (detailProcessComplete) matches with the label value in the signal
activity of each detail process. This ensures that the signal is delivered to the correct
process. Example 163 provides an example. This syntax shows a receive signal
activity in a BPEL process that supports BPEL version 1.1.
Example 163
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess"
label="detailProcessComplete"
from="details"/>
Note:
<extensionActivity>
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess"
label="detailProcessComplete" from="details"/>
</extensionActivity>
The second invoke activity invokes the DetailProcess1 detail process and
associates it with a label of detailProcessComplete1. Example 165 provides an
example.
Example 165
16-5
operation="initiate"
inputVariable="detail_input1"
bpelx:detailLabel="detailProcessComplete1-2"
bpelx:invokeAsDetail="true"/>
The third invoke activity invokes the DetailProcess2 detail process again through
a different port and with a different input variable. It associates the DetailProcess2
detail process with a label of detailProcessComplete1-2, as shown in
Example 166.
Example 166
The receive signal activity of the master process shown in Example 167 waits for a
return signal from detail process DetailProcess0.
Example 167
The second receive signal activity of the master process shown in Example 168 also
waits for a return signal from DetailProcess1 and DetailProcess2.
Example 168
<!-- This is a receiveSignal waiting for 2 child (detail) processes to signal back
-->
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess1-2"
label="detailProcessComplete1-2" from="details"/>
<bpelx:receiveSignal name="waitForNotifyFromMasterProcess"
label="startDetailProcess" from="master"/>
16-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A signal activity indicates that the detail process shown in Example 1610 signals its
associated master process at runtime that processing is complete. The label value
(detailProcessComplete) matches with the label value in the receive signal
activity of each master process.
Example 1610 Signal Activity
<bpelx:signal name="notifyMAsterProcess" label="detailProcessComplete"
to="master"/>
3.
4.
5.
6.
Table 162
Field
Value
Name
Label
To
16-7
7.
Click OK.
8.
9.
Field
Value
Name
Label
To
16-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Drag a Receive Signal activity into your BPEL process service component.
5.
6.
Table 164
Field
Value
Name
Label
To
16-9
7.
Click OK.
8.
9.
Field
Value
Name
Label
To
16-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
5.
Select the DetailProcess BPEL process you created in Step 1 on page 16-9 as the
partner link.
6.
7.
Complete all remaining fields in the Invoke dialog, and click OK.
8.
16-11
c.
Repeat these steps as necessary for additional detail processes, ensuring that
you specify a different label value.
16-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
17
17
This chapter describes how to send notifications from a BPEL process using a variety
of channels. A BPEL process can be designed to send email, voice message, instant
messaging (IM), or short message service (SMS) notifications. A BPEL process can also
be designed to consider an end user's channel preference at runtime for selecting the
notification channel.
This chapter includes the following sections:
Note:
Notification
An asynchronous message sent to a user by a specific channel. The message can be
sent as an email, voice, IM, or SMS message.
Actionable notification
A notification to which the user can respond. For example, workflow sends an
email to a manager to approve or reject a purchase order. The manager approves
or rejects the request by replying to the email with appropriate content.
Sends email notifications directly from a BPEL process or implicitly from the
human task part of a BPEL process. Implicit notifications are modeled from the
Human Task Editor.
For sending email notifications directly from a BPEL process, you must explicitly
specify the user information in the BPEL process and can be inside or outside of a
human task scope.
For sending email notifications implicitly from the human task part of a BPEL
process, you only specify the recipient based on the relationship of the user with
regards to the task (that is, the creator, assignee, and so on).
Implicit notifications are processed through more layers of
code than explicit notifications. If explicit notifications are functioning
correctly, it does not mean that implicit notifications also function
correctly.
Note:
BPEL
Process Service
Component
Email Server
SMS Server
Java Call
Voice Gateway
Java Interface
IM Server
Human
Workflow
Task
17-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Notification Tasks
Task
Description
User Interface
Described In...
Selected and
configured by the
BPEL process designer
in Oracle BPEL
Designer
or
or
Configured by the
administrator in
Oracle Enterprise
Manager Fusion
Middleware Control
Configure the
notification mode and
actionable accounts for
human workflows.
Configured by the
administrator in
Oracle Enterprise
Manager Fusion
Middleware Control
1.
2.
3.
IM
SMS
Voice
See the section in Table 172 based on the notification channel you selected.
Table 172
Notification Channels
If You
Selected...
See...
IM
SMS
Voice
Note:
17-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Table 173
Name
Description
From Account
The name of the account used to send this message. The default
account is named Default and is editable from the Workflow
Notification Properties page in Oracle Enterprise Manager
Fusion Middleware Control. To add additional accounts, you
must use the System MBean Browser in Oracle Enterprise
Manager Fusion Middleware Control.
For information on editing this property in Oracle Enterprise
Manager Fusion Middleware Control, see Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite.
To
Reply To
The email address to use for replies. This can also be a static or
dynamic address, as described for the To address.
Description
Subject
Body
The message body of the email message. This can also be plain
text, HTML, or dynamic text, as described for the Subject
parameter.
2.
Click OK.
The BPEL fragment that invokes the notification service to send the email message
is created.
3.
See Table 171 of Section 17.2, "Introduction to Notification Channel Setup" for
additional configuration procedures to perform.
The WebLogic Fusion Order Demo application uses an email activity in the Scope_
NotifyCustomerofCompletion scope. The Oracle User Messaging Service sends
the email to a customer when an order is fulfilled. The following details are
specified in the Email dialog:
17-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Click the Add icon to add as many attachments as you require. The number of
attachments does not need to include the body part.
5.
In the Name field, change the name or accept the default value of
Attachmentnumber.
6.
In the Mime Type field, click the Browse icon to invoke the Expression Builder
dialog for adding MIME type contents.
7.
8.
In the Value field, click the Browse icon to invoke the Expression Builder dialog
for adding the contents of the attachment.
9.
For more information about sending attachments using email, see the following
documentation:
17-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<copy>
<from
expression="ora:processXSLT('TransformPositionSummary7.xslt',bpws:
getVariableData('ClientPositionSummary'))"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns9:Content/ns9:ContentBody"/>
</copy>
17.3.1.3 Using Dynamic HTML for Message Content Requires a CDATA Function
If the HTML for the message content of an email activity is generated dynamically, (as
with XSLT, file read, and so on), it must be wrapped in a CDATA function. This
prevents conflicts between the XML/HTML content of the message body and BPEL's
internal XML data structures.
For example, assume you use the append operation shown in Example 172 for the
message content inside the email activity:
Example 172
<bpelx:append>
<bpelx:from
expression="ora:processXSLT('xsl/email.xslt',bpws:getVariableData('Variable_1'
))"/>
<bpelx:to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[1]
/ns1:ContentBody"/>
</bpelx:append>
For this to work correctly, you must pass the output of the processXSLT() function
to the CDATA() function, as shown in Example 173.
Example 173
CDATA() Function
<%ora:toCDATA(xdk:processXSLT('xsl/email.xslt',
bpws:getVariableData('inputVariable','payload','/client:process/client:input')
))%>
IM Notification Parameters
Name
Description
To
Body
2.
Click OK.
The BPEL fragment that invokes the notification service for IM notification is
created.
3.
See Table 171 of Section 17.2, "Introduction to Notification Channel Setup" for
additional configuration procedures to perform.
17-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Name
Description
From Number
Telephone Number
Subject
Body
The SMS message body. This must be plain text. This can be
plain text or dynamic text as described for the Subject
parameter.
2.
Click OK.
The BPEL fragment that invokes the notification service for SMS notification is
created.
3.
See Table 171 of Section 17.2, "Introduction to Notification Channel Setup" for
additional configuration procedures to perform.
Name
Description
Telephone Number
2.
The message body. This can be plain text, XML, or dynamic text.
The XPath Expression Builder can set dynamic text based on
data from process variables that you specify.
Click OK.
The BPEL fragment that invokes the notification service for voice notification is
created.
3.
See Table 171 of Section 17.2, "Introduction to Notification Channel Setup" for
additional configuration procedures to perform.
To get the email address or telephone number directly from the payload, use the
following XPath expression:
bpws:getVariableData('<variable name>', '<part>','input_xpath_to_get_an_
address')
For example, to get the email address from variable inputVariable and part
payload based on XPath /client/BPELProcessRequest/client/mail:
<%bpws:getVariableData('inputVariable','payload','/client:BPELProcessRequest/
client:email')%>
You can use the XPath Expression Builder to select the function and enter the
XPath expression to get an address from the input variable.
To get the email address or telephone number dynamically from the underlying
identity store (LDAP) use the following XPath expression:
ids:getUserProperty(userName, attributeName[, realmName])
The first argument evaluates to the user ID. The second argument is the property
name. The third argument is the realm name. Table 177 lists the property names
that can be used with this XPath function.
Table 177
Property Name
Description
telephoneNumber
mobile
homephone
The following example gets the email address of the user identified by the variable
inputVariable, part payload, and queries
/client:BPELProcessRequest/client:userID:
ids:getUserProperty(bpws:getVariableData(inputVariable,
payload,/client:BPELProcessRequest/client:userid), mail)
If realmName is not specified, then the default realm name is used. For example, if
the default realm name is jazn.com, the following XPath expression searches for
the user in the jazn.com realm:
ids:getUserProperty('jcooper', 'mail');
The following XPath expression provides the same functionality as the one above.
In this case, however, the realm name of jazn.com is explicitly specified:
ids:getUserProperty('jcooper', 'mail', 'jazn.com');
For more information about using the Identity Lookup dialog, see Chapter 34,
"Introduction to Human Workflow Services."
If an expense report amount is less than $153, they receive an email notification.
If an expense report amount is between $153 and $3678, they receive an SMS
notification.
If an expense report amount is more than $3678, they receive a voice notification.
You can also set user preferences for sending notifications in
human workflows in the Human Task Editor. Set these preferences in
the Notification Filters part of the Notification Settings section.
These preferences are used to evaluate rules in the task. For more
information, see Section 29.8.8, "How to Send Task Attachments with
Email Notifications."
Note:
For more information about the User Messaging Preferences user interface, see
Chapter 67, "User Messaging Preferences."
For information about configuring Oracle User Messaging Service in Oracle Enterprise
Manager Fusion Middleware Control, see Oracle Fusion Middleware Administrator's
Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
3.
From the Component Palette, drag the User Notification activity into the designer.
Figure 179 shows the required user notification parameters.
17-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Table 178
Name
Description
To
Notification Message
5.
Click Apply.
Oracle BPEL Designer specifies the users named jcooper and jstein in the
General tab.
Oracle BPEL Designer creates the following header and name information in the
Advanced tab:
Amount = payload->salary
Application = HR-Application
The administrator deploys the process and configures various channel drivers in
Oracle Enterprise Manager Fusion Middleware Control.
The end user jcooper creates the following preference rules in the User
Messaging Preferences user interface:
Email if Amount < 30000" and "SMS if Amount is between 30000 and 100000 and
"Voice if Amount > 100000"
The end user jstein creates the following preference rule in the User Messaging
Preferences user interface:
If "Application == HR-Application" and Amount > 2000000" send Voice
1.
If you want to create and send header and name information to an end user for
creating their own preference rules, click Advanced.
Figure 1710 shows the Advanced tab of the User Notification dialog.
2.
Click the Add icon to add a row to the Header and Name columns.
3.
In the Header column, click the field to display a list for selecting a value.
Otherwise, manually enter a value.
4.
5.
Click OK.
17-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
18
18
Section 18.3, "Viewing Sensors and Sensor Action Definitions in Oracle Enterprise
Manager Fusion Middleware Control"
For more information about Oracle BPEL Process Manager sensors, see the following
sections:
Section 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action" for how
to create sensor actions in Oracle BPEL Process Manager to publish sensor data as
data objects in an Oracle Business Activity Monitoring (BAM) Server
Appendix D, "Understanding Sensor Public Views and the Sensor Actions XSD"
For information about composite sensors, see Chapter 50, "Defining Composite
Sensors."
The activity name and type that modified the BPEL variable
The data format for sensor values is normalized and well-defined using XML schema.
Activity sensors
Activity sensors monitor the execution of activities within a BPEL process. For
example, they can monitor the execution time of an invoke activity or how long it
takes to complete a scope. Along with the activity sensor, you can also monitor
variables of the activity.
Variable sensors
Variable sensors are used to monitor variables (or parts of a variable) of a BPEL
process. For example, variable sensors can monitor the input and output data of a
BPEL process.
Fault sensors
Fault sensors are used to monitor BPEL faults.
You typically add or edit sensors as part of the BPEL modeling of activities, faults, and
variables.
These sensors are exposed through the following public SQL views:
BPEL_ACTIVITY_SENSOR_VALUES
BPEL_FAULT_SENSOR_VALUES
BPEL_VARIABLE_SENSOR_VALUES
These views can be joined with the BPEL_PROCESS_INSTANCES view to associate the
sensor value with the BPEL process instance that created the sensor values. For more
information, see Appendix D, "Understanding Sensor Public Views and the Sensor
Actions XSD."
When you model sensors in Oracle JDeveloper, two new files are created as part of the
BPEL process archive:
bpel_process_name_sensor.xml
Contains the sensor definitions of a BPEL process
bpel_process_name_sensorAction.xml
Contains the sensor action definitions of a BPEL process
For information about how these files are created, see Section 18.2.2, "How to
Configure Activity, Variable, and Fault Sensors" and Section 18.2.3, "How to Configure
Sensor Actions."
After you define sensors for a BPEL process, you must configure sensor actions to
publish the sensor data to a specified destination. If no sensor action is defined for a
sensor, then nothing happens at runtime.
The following information is required for a sensor action:
Name
Publish type
18-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The publish type specifies the destination in which the sensor data must be
presented. You can publish sensor data to the following destination types.
Database
Publishes the sensor data to the reports schema in the database. The sensor
data can then be queried using SQL.
JMS queue
Publishes the sensor data to a JMS queue. The XML data is posted in
accordance with the Sensor.xsd file. This file is included with Oracle
JDeveloper in the JDEV_
HOME\jdeveloper\integration\seed\soa\shared\bpel directory.
JMS topic
Publishes the sensor data to a JMS topic. The XML data is posted in
accordance with the same Sensor.xsd file used with JMS queues.
Custom
Publishes the data to a custom Java class.
JMS Adapter
Uses the JMS adapter to publish to remote queues or topics and a variety of
different JMS providers. The JMS queue and JMS topic publish types only
publish to local JMS destinations.
List of sensors
The sensors for a sensor action.
Oracle BAM sensors publish information and events from Oracle BPEL Process
Manager to Oracle BAM. Oracle BAM can display the data in rich real-time
dashboards for end-to-end monitoring of an application. For more information, see
Section 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action."
Figure 182 shows the sensor actions and sensors in the Structure window.
You typically add or edit sensors as part of the BPEL modeling of activities, faults,
and variables.
2.
Add sensor actions by right-clicking the Sensor Actions folder and selecting
Create > Sensor Action.
3.
4.
a.
b.
c.
Click Create.
The following sections describe how to configure sensors and sensor actions.
When it is completed
18-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The solution is to create an activity sensor for the GetCreditRating scope in Oracle
BPEL Designer, as shown in Figure 184.
1.
2.
3.
4.
To the right of the Activity Name field, click the Browse icon to select the activity
for which to create the sensor. This is a required field.
Activities that have sensors associated with them are identified with a magnifying
glass in Oracle BPEL Designer.
The Evaluation Time list shown in Figure 184 controls the point at which the
sensor is fired.
5.
All:
The sensor monitors during the activation, completion, fault, compensation,
and retry phases.
Activation
The sensor is fired just before the activity is executed.
Completion
The sensor is fired just after the activity is executed.
Fault
The sensor is fired if a fault occurs during the execution of the activity. Select
this value only for sensors that monitor simple activities.
Using Oracle BPEL Process Manager Sensors 18-5
Compensation
The sensor is fired when the associated scope activity is compensated. Select
this value only for sensors that monitor scopes.
Retry
The sensor is fired when the associated invoke activity is retried.
If you want to create a variable sensor on the activity, then in the Activity Variable
Sensors section, click the Add icon. This is an optional field.
7.
If you want to add a sensor action on the activity, then in the Sensor Actions
section, click the Add icon. For more information, see Section 18.2.3, "How to
Configure Sensor Actions."
8.
Click OK.
2.
3.
4.
Click the Edit icon to the right of the Target field to create a variable sensor for a
variable (for this example, named input), as shown in Figure 185.
18-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Based on your selection for the Target field, the Output Namespace and Output
Datatype fields are automatically filled in.
A new entry is created in the bpel_process_name_sensor.xml file:
<sensor sensorName="LoanApplicationSensor"
classname="oracle.tip.pc.services.reports.dca.agents.BpelVariableSensorAgent"
kind="variable"
target="$input/payload">
<variableConfig outputNamespace="http://www.autoloan.com/ns/autoloan"
outputDataType="loanApplication"/>
</sensor>
2.
3.
4.
Click the Browse icon above the Namespace field to select to create a fault sensor,
as shown in Figure 186.
Based on your selection, the Namespace and Local Parts fields are automatically
filled in.
5.
If you want to add a sensor action on the fault, then in the Sensor Actions section,
click the Add icon. For more information, see Section 18.2.3, "How to Configure
Sensor Actions."
6.
Click OK.
3.
4.
Table 181
Field
Description
Name
18-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Publish Type
Publish Target
Filter
Enable
You cannot specify a < (less than) sign in the Filter field of the
Sensor Action dialog. If you do, Oracle JDeveloper translates the <
sign to < in the bpel_process_name_sensorAction.xml file.
In addition, you cannot specify a < sign by directly editing the
filename_sensorAction.xml file. This action causes an error.
Note:
5.
The data of one sensor can be published to multiple endpoints. In the two
preceding code samples, the data of LoanApplicationSensor was published to a
JMS queue and to the reports schema in the database.
6.
If you want to monitor loan requests for which the loan amount is greater than
$100,000, create a sensor action with a filter, as shown in Figure 189. There is no
design-time validation of the filter query. You must ensure the query is correct.
18-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Notes:
7.
You must specify all the namespaces that are required to configure
an action filter in the bpel_process_name_
sensorAction.xml configuration file. For example, assume you
have a customer XML-schema element with namespace
"http://myCustomer" and you want to create a filter on the
customer age element. Therefore, you must manually declare
the namespace for "http:/myCustomer" in the file before you
can use it in your filter. Otherwise, it is not possible to create a
valid query. Add xmlns:ns1="http://myCustomer" in the
attribute declaration part of the file. You can then use
..../ns1:customer/ns1:age/... in your query.
You must specify the filter as a boolean XPath expression.
If you have special requirements for a sensor action that cannot be accomplished
by using the built-in publish types (database, JMS queue, JMS topic, and JMS
Adapter), then you can create a sensor action with the custom publish type, as
shown in Figure 1810. The name in the Publish Target field denotes a fully
qualified Java class name that must be implemented. For more information, see
Section 18.2.5, "How to Create a Custom Data Publisher."
Figure 1810
In addition to enabling you to publish sensor data to remote topics and queues, the
JMS adapter supports a variety of different JMS providers, including:
Third-party JMS providers such as Tibco JMS, IBM WebSphere MQ JMS, and
SonicMQ
Oracle Enterprise Messaging Service (OEMS) providers such as memory/file and
database
If you select the JMS Adapter publish type, you must create an entry in the
weblogic-ra.xml file, which is updated through editing in the Oracle WebLogic
Server Administration Console. Each JMS connection factory (pool) entry created in
this console corresponds to one JNDI entry in weblogic-ra.xml. Update the Sensor
Actions dialog with the chosen JNDI name selected during the creation of the JMS
connection factory (pool).
For more information about the JMS adapter, see Oracle Fusion Middleware User's Guide
for Technology Adapters.
3.
18-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1812
4.
5.
6.
7.
composite.xml File
18-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Viewing Sensors and Sensor Action Definitions in Oracle Enterprise Manager Fusion Middleware Control
port="http://xmlns.oracle.com/JMSQueueFilter#wsdl.endpoint(client/
JMSQueueFilter_pt)"/>
</service>
<component name="JMSQueueFilter">
<implementation.bpel src="JMSQueueFilter.bpel"/>
<property name="configuration.sensorLocation" type="xs:string"
many="false">JMSQueueFilter_sensor.xml</property>
<property name="configuration.sensorActionLocation" type="xs:string"
many="false">JMSQueueFilter_sensorAction.xml</property>
</component>
<wire>
<source.uri>client</source.uri>
<target.uri>JMSQueueFilter/client</target.uri>
</wire>
</composite>
You can specify additional properties with <property name= ...>, as shown in
Example 181.
For this release, Oracle BAM sensor actions are not shown in
Oracle Enterprise Manager Fusion Middleware Control.
Only sensors with an associated database sensor action are
displayed in Oracle Enterprise Manager Fusion Middleware
Control. Sensors associated with a JMS queue, JMS topic, remote
JMS, or custom sensor action are not displayed.
Viewing Sensors and Sensor Action Definitions in Oracle Enterprise Manager Fusion Middleware Control
18-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part III
Part III
This part describes the components that comprise the Oracle Mediator service
component.
This part contains the following chapters:
19
Getting Started with Oracle Mediator
19
Mediator Functionality
Mediator Functionality
For more information about transformations, see Section 20.3.2.9, "How to Create
Transformations."
For more information about Mediator echo support, see "To echo a service:" of
Section 20.3.2.1, "How to Specify Mediator Services or Events."
Note:
Each section of the view shown in Figure 191 lets you perform specific design and
deployment tasks. The sections in this view include the following:
Application Navigator
19-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Application Navigator, shown in the upper left section of Figure 191,
displays the Mediator file structure. These files appear under the SOA Content
folder of the project where you created a Mediator. For more information about the
Application Navigator and the composite files, see Table 23, " SOA Composite
Editor".
Mediator Editor
The Mediator Editor, shown in the middle of Figure 191, provides a visual view
of the Mediator. This view appears when you perform one of the following
actions:
Source View
The Source view displays the source code of a Mediator. Click Source at the
bottom of the Mediator Editor to view the source code. The code in Source view is
immediately updated to reflect any changes to an a Mediator.
Example 191 shows sample Mediator source code:
Example 191
History Window
The History window displays history information about the Mediator file,
including a revision history and side-by-side comparisons of read-only and
editable versions of a file. Click History at the bottom of the Design window
shown in Figure 191 to open the History window. Figure 192 shows the History
view for a Mediator file.
Property Inspector
Creating a Mediator
The Property Inspector, shown at the bottom of Figure 191, displays details about
Mediator properties.
Structure Window
The Structure Window, shown in the lower left section of Figure 191, displays a
structural view of the data of a Mediator.
Log Window
The Log Window displays messages about the validation and compilation status.
When you create a Mediator, the Create Mediator dialog appears so you can name the
Mediator and select a template for the interface.
To create a composite application with a Mediator:
Create and Name the SOA application and project using the Create SOA
Application wizard.
1.
2.
When you reach the Configure SOA Settings page, select Composite with
Mediator in the Composite Template list, as shown in Figure 193.
19-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Mediator
Figure 193 Composite with Mediator Selection in Create SOA Project Wizard
3.
Click Finish.
The Create Mediator dialog appears.
4.
5.
Define routing rules for the Mediator, as described in Chapter 20, "Creating Oracle
Mediator Routing Rules."
Drag and drop a Mediator from the Component Palette (shown in Figure 194) to
the Components section of the editor.
Tip: The Component Palette is to the right of the SOA Composite
Editor.
Creating a Mediator
4.
Define routing rules for the Mediator, as described in Chapter 20, "Creating Oracle
Mediator Routing Rules."
Create and name a new SOA project in the SOA Tier category.
3.
On the Configure SOA Settings page of the New Gallery dialog, select Composite
With Mediator from the Composite Template list, shown in Figure 195.
19-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Mediator
Figure 195 Create SOA Project Wizard with Composite With Mediator Template Shown
4.
Click Finish.
The Create Mediator dialog appears.
5.
3.
Under Categories, select Service Components, and then select Mediator from the
Items list, as shown in Figure 196.
4.
Click OK.
The Create Mediator dialog appears.
5.
6.
Define routing rules for the Mediator, as described in Chapter 20, "Creating Oracle
Mediator Routing Rules."
19-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In the Name field, enter a name for the Mediator service component.
3.
Select one of the following from the Template list. Refer to the descriptions at the
beginning of this section for more information on each.
One-Way Interface
Synchronous Interface
Asynchronous Interface
Subscribe to Events
Figure 197 and Figure 198 illustrate how the properties change on the Create
Mediator dialog for different interface types.
Figure 197 Synchronous Interface Template Selection on the Create Mediator Dialog
Figure 198 Interface Definition from WSDL Template Selection on the Create Mediator
Dialog
4.
For any interface type except Subscribe to Events, configure the appropriate
properties. For information about the displayed properties for each type, see
Table 191 following these instructions.
5.
Click Add on the Create Mediator dialog. Figure 199 provides details.
19-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
c.
d.
Select one or more events in the Event field, as shown in Figure 1910, and
click OK.
Figure 1910
e.
f.
In the Run as publisher field, select whether to run the event subscription
under the security of the event publisher.
By default, event subscriptions run under the security of the event publisher.
g.
To filter the event, double-click the Filter column of the selected event, or
select the event and then click the filter icon (first icon).
The Expression Builder dialog appears.
h.
The expression you created appears in the Filter column of the Create
Mediator dialog.
i.
Click OK.
6.
7.
If you chose to create a Mediator without an interface, you must create the
interface at a later time as described in Section 19.6.1, "How to Define an Interface
for a Mediator."
Table 191 lists and describes the properties you can configure to define an interface.
The available properties change depending on the interface type you select, so not all
of the listed properties apply to all interface types.
19-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 191
Property
Description
WSDL URL
Enter the location of the WSDL file to use when creating the
interface from a WSDL file. Do one of the following:
Enter the port type name from the WSDL file. The available port
types are parsed from the WSDL file that you specify in the
WSDL URL field.
Enter the port type name to which the response message is sent
in an asynchronous communication. The available port types are
parsed from the WSDL file that you specify in the WSDL URL
field.
Input
Enter the schema element for the input message. Click Search to
the right of the field to select the element. By default, the
singleString schema element is selected for the input message.
For a sample schema, see Example 192.
Output
Example 192
Enter the schema element for the output message. Click Search
to the right of the field to select the element. By default, the
singleString schema element is selected for the input message.
One-Way Interface Sample Scheme
You can use any XSD schema to specify the format of the input document that
Mediator processes. Here is a sample schema:
<xsd:schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://samples.otn.com/helloworld"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://samples.otn.com/helloworld">
<include namespace="http://samples.otn.com/helloworld"
schemaLocation="helloworld.xsd" />
<xsd:element name="name1" type="xsd:string" />
<xsd:element name="result1" type="xsd:string"/>
</xsd:schema>
19-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1914
When you double-click the Mediator, the Mediator Editor appears, as shown in
Figure 1918.
19-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1918
Connect the Mediator to a service through a wire in the SOA Composite Editor.
2.
3.
Click Add.
The Event Chooser dialog appears.
4.
Follow the instructions under Section 19.5, "Configuring the Mediator Interface
Definition" beginning with Step 5b.
5.
Click OK.
For more information about wires and how to wire a service component to a
service, see Section 2.5.1, "How to Wire a Service and a Service Component."
Note:
When you define a service using a wire, the service for the Mediator is
automatically defined using the WSDL file from the wire source. For example, if
you connect the ReadFile service shown in Figure 1919 to the
CustomerDataRouter Mediator, the CustomerDataRouter Mediator automatically
inherits the service definition of the ReadFile service.
Figure 1919 Connecting Mediator to a Service
For information about how wiring two Mediator service components can cause an
infinite loop, see Section 2.5.3, "What You May Need to Know About Adding and
Deleting Wires."
To define services for a Mediator in the Mediator Editor:
1.
2.
19-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1920
3.
To use an existing WSDL file, click Find existing WSDLs to the right of the
WSDL URL field.
To create a WSDL file, click Generate WSDL from schema(s) to the right of
the WSDL URL field.
For information about how to generate a WSDL file, see Section 19.7, "Generating
a WSDL File."
4.
5.
From the Callback Port Type list, select a port for the response message in an
asynchronous interaction.
6.
Click OK.
When you are creating a Mediator and you select the Interface Definition from
WSDL template in the Create Mediator dialog, selecting Generate WSDL from
Schema(s) next to the WSDL URL field opens the Create WSDL dialog.
When you have a Mediator with no interface defined and you click Define Service
next to the WSDL URL field in the Mediator Editor, selecting Generate WSDL
from Schema(s) next to the WSDL URL field opens the Create WSDL dialog.
The Create WSDL dialog populates standard fields, such as the file name, directory,
and namespace; and the dialog changes depending on the interface type you select.
You can specify the same or different schema files for the message inputs.
In the Create WSDL dialog, accept the default values or enter the information for
the WSDL file shown in Table 192.
Table 192
WSDL Properties
Property
Description
File Name
Directory
The directory where you want to store the WSDL file. By default,
it is stored in the same location as the Mediator file. This must be
the current project directory or one of its subdirectories. If the
specified directory does not exist, Oracle JDeveloper creates it.
Namespace
Port Type
The name of the port type in the WSDL file that contains the
operation to use.
Operation
Note:
2.
19-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
To the upper right of the Input field, click Add a new message part.
The Add Message Part dialog appears, as shown in Figure 1922.
Figure 1922
4.
In the Part Name field, enter a name for the message part.
5.
To the right of the URL field, click the browse for schema file icon to browse for
the URL.
The Type Chooser dialog appears and contains a list of the schema files (XSD
files), as shown in Figure 1923.
Figure 1923
6.
Expand the Type Explorer tree to locate and select the schema element to use.
If the schema you want to use is not located in the project in which you are
working, you can import a schema XSD file or WSDL file into the project using the
Import Schema File or Import WSDL icon in the upper right corner of the dialog.
If you want to use a schema XSD file that resides on your local
file system, ensure that the XSD file and any XSD files that it imports
all reside in the Oracle JDeveloper project directory. This ensures that
the schema is deployed with the project and is made available at
runtime.
Note:
After you specify a file, Oracle JDeveloper parses it to determine the defined
schema elements and displays them in a list from which you select.
7.
Select the root element of the XSD file and click OK.
The Add Message Part dialog reappears with the URL and Schema Element fields
populated from the Type Chooser dialog. If you selected an XSD simple type,
these fields are replaced by a Simple Type field.
8.
9.
Note:
On the Create WSDL dialog, enter the information for the properties listed in
Table 192, " WSDL Properties".
2.
3.
To the upper right of the Input field, click Add a new message part.
The Add Message Part dialog appears, as shown in Figure 1925.
19-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1925
4.
In the Part Name field, enter a name for the message part.
5.
To the right of the URL field, click the browse for schema file icon to browse for
the URL.
The Type Chooser dialog appears and contains a list of the schema files (XSD
files), as shown in Figure 1926.
Figure 1926
6.
Expand the Type Explorer tree to locate and select the schema element to use.
If the schema you want to use is not located in the project in which you are
working, you can import a schema XSD file or WSDL file into the project using the
Import Schema File or Import WSDL icon in the upper right corner of the dialog.
If you want to use a schema XSD file that resides on your local
file system, ensure that the XSD file and any XSD files that it imports
all reside in the Oracle JDeveloper project directory. This ensures that
the schema is deployed with the project and is made available at
runtime.
Note:
After you specify a file, Oracle JDeveloper parses it to determine the defined
schema elements and displays them in a list from which you can make a selection.
7.
Select the root element of the XSD file and click OK.
The Add Message Part dialog reappears with the URL and Schema Element fields
populated from the Type Chooser dialog. If you selected an XSD simple type,
these fields are replaced by a Simple Type element.
8.
The input information appears in the Input field of the Create WSDL dialog.
9.
Repeat the above steps to define message parts for the Output and Fault fields.
The output represents the response message and is required in synchronous
transactions. Faults are optional.
Note:
On the Create WSDL dialog, enter the information for the properties listed in
Table 192, " WSDL Properties".
2.
3.
To the upper right of the first Input field, click Add a new message part.
The Add Message Part dialog appears, as shown in Figure 1928.
19-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 1928
4.
In the Part Name field, enter a name for the message part.
5.
To the right of the URL field, click the browse for schema file icon to browse for
the URL.
The Type Chooser dialog appears and contains a list of the schema files (XSD
files), as shown in Figure 1929.
Figure 1929
6.
Expand the Type Explorer tree to locate and select the schema element to use.
If the schema you want to use is not located in the project in which you are
working, you can import a schema XSD file or WSDL file into the project using the
Import Schema File or Import WSDL icon in the upper right corner of the dialog.
If you want to use a schema XSD file that resides on your local
file system, ensure that the XSD file and any XSD files that it imports
all reside in the Oracle JDeveloper project directory. This ensures that
the schema is deployed with the project and is made available at
runtime.
Note:
After you specify a file, Oracle JDeveloper parses it to determine the defined
schema elements and displays them in a list from which you can make a selection.
7.
Select the root element of the XSD file and click OK.
The Add Message Part dialog reappears with the URL and Schema Element fields
populated from the Type Chooser dialog. If you selected an XSD simple type,
these fields are replaced by a Simple Type element.
8.
The input information appears in the Input field of the Create WSDL dialog.
9.
Repeat the above steps to define the input message parts for the Callback section.
The callback input represents the response message and is
required in asynchronous transactions.
Note:
10. In the Callback section, specify the following information for the response
message:
Port Type: The name of the port type in the WSDL file that contains the
operation to use.
Operation: The name of the action to perform; for example,
executeResponse.
Spaces and special characters are not allowed in an operation
name or port type. Only alphabetic and numeric characters are
supported, and the first character cannot be a number. Both of these
fields are required.
Note:
Note:
19-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
To specify a different WSDL file, click Find existing WSDLs to the right of the
WSDL URL field to use an existing WSDL file or Generate WSDL From
schema(s) to create a WSDL file.
The Refresh WSDL dialog is updated based on the operations defined in the
specified WSDL file.
3.
Click OK.
4.
2.
3.
Click OK.
4.
19-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
20
Creating Oracle Mediator Routing Rules
20
This chapter describes Oracle Mediator routing rules and how to specify routing rules
for a Mediator service component. Routing rules include transformation, filtering,
validation, mapping, and routing logic.
This chapter includes the following sections:
The following chapter provide additional information about defining routing rules for
specific scenarios:
For more information about creating routing rules, see Section 20.3.2, "How to Create
Static Routing Rules" and Section 20.3.3, "How to Create Dynamic Routing Rules." For
information about standard message exchange patterns and how they are handled by
Mediator, see Chapter 24, "Understanding Message Exchange Patterns of an Oracle
Mediator."
Target Service
Mediator sends messages to the target service you specify. This service can either
be defined as a WSDL interface or a Java interface. For information about invoking
a target service, see Section 20.3.2.1, "How to Specify Mediator Services or Events".
Execution Type
Mediator executes routing rules either sequentially (that is, running in the same
thread) or in parallel (running on different threads). For information about
specifying an execution type, see Section 20.3.2.3, "How to Specify Sequential or
Parallel Execution".
For synchronous service invocations, the routing rule should
always be sequential.
Note:
Filter Expression
You can define a filter expression that is applied to the message content (payload
or headers). When you define a filter, the contents are analyzed before any service
is invoked. For example, you might apply a filter expression that specifies that a
service be invoked only if the message includes a customer ID, or if the value for
that customer ID matches a certain pattern. For information about specifying filter
expressions, see Section 20.3.2.8, "How to Specify an Expression for Filtering
Messages".
Transformations
Mediator can transform message data before forwarding the message to a service.
You can define transformations to set a value on the target payload by mapping
data or by assigning values.
The XSLT Mapper lets you define transformations that apply to the whole message
body to convert messages from one XML schema to another. The Assign Values
function works on individual fields. Using this dialog, you can assign values from
20-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
the message (for example, payload and headers), from a constant, or from various
system properties, such as the properties of an adapter present in the data path.
For information about defining transformations, see Section 20.3.2.9, "How to
Create Transformations" and Section 20.3.2.10, "How to Assign Values".
Schematron-Based Validations
You can specify the Schematron files that Mediator should use to validate different
parts of an inbound message. For information about performing
Schematron-based validations, see Section 20.3.2.13, "How to Use Semantic
Validation".
Java Callouts
Custom Java class callouts let you use regular expressions with Java code, when
regular expressions alone do not suffice. For information about using Java callouts,
see Section 20.3.2.15, "How to Use Java Callouts".
matrix determines the type of Level-2 service to be chosen for each routing. The factors
that affect the decision on the type of Level-2 service are channel, customer type, and
so on. The solution allows this decision matrix to be modified externally by business
analysts without changing the routing. The decision matrix must be evaluated to
determine the outbound service.
Dynamic routing rules are described in more detail in Section 20.3.3, "How to Create
Dynamic Routing Rules."
Note:
20-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can set the Priority field in the Mediator Editor to indicate the priority of a
Mediator service component. Priorities can range from zero to nine, with nine
being the highest priority. The default priority is four.
Note: The Priority property is applicable only to parallel routing
rules.
Mediator initiates a new transaction for processing each parallel rule. The initiated
transaction ends with an enqueue to the Mediator parallel message dehydration
store.
For example, if a Mediator service component has one parallel routing rule, one
message is enqueued on the Mediator parallel message dehydration store. The
parallel message dispatcher to the store then initiates a transaction, reads the
message from the database store, and invokes the target component or service of
this routing rule. The transaction initiated by the listener thread is a completely
new transaction and is propagated to the target components.
Dehydrating of messages means storing the incoming
messages in a database for parallel routing rules so they can be
processed later by worker threads.
Note:
a.
Double-click the icon that represents the Mediator for which you want to
specify the routing rules.
b.
If the Routing Rules section is not visible, click the Plus (+) icon next to
Routing Rules.
In the Application Navigator, expand the SOA project and then expand the
SOA Content folder.
b.
In the SOA Content folder, double-click the name of the Mediator file in
which you want to specify the routing rules.
The Mediator file has an MPLAN extension.
c.
If the Routing Rules section is not visible, click the Plus (+) icon next to
Routing Rules.
Figure 201 shows the Routing Rules section of the Mediator Editor.
Figure 201 Mediator Editor- Routing Rules Section
Figure 202 lists and describes the icons in the Routing Rules section.
20-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The following topics provide information and instructions for defining static
routing rules for Mediator, including specifying the services and events, defining
handlers, transformations, expressions, filters, and so on.
insert
update
updateid
delete
To do this action, you must create four routing rules, one for each operation. Later,
when you specify a filter expression for each rule, you can specify which target and
operation is applied to each message instance based on the message payload, as
shown in Figure 203.
Figure 203 Multiple Routings for an Inbound Operation
To invoke a service:
To perform this step, the target service must be defined in a WSDL document or a Java
interface.
1.
In the Routing Rules section, click Add next to the operation for which you are
defining routing rules, and then select static routing rule.
The Target Type dialog appears, as shown in Figure 204.
2.
Click Service.
20-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
In the Target Services dialog, navigate to and then select an operation provided by
a service.
You can select a service defined by a WSDL file or a Java
interface. A service can consist of multiple operations, as shown in
Figure 205.
Note:
4.
Click OK.
5.
If you selected a target service defined by a Java interface, the Interface Required
dialog appears. Click Yes to create the required WSDL file, and then click OK on
the confirmation dialog.
A new Static Routing section appears where you can define the routing rule.
6.
Configure the routing rule as described the remaining sections of this chapter.
To trigger an event:
1.
In the Routing Rules section, click Add next to the operation for which you are
defining routing rules, and then select static routing rule.
The Target Type dialog appears, as shown in Figure 204.
2.
Click Event.
The Event Chooser dialog appears.
3.
Note:
5.
Select an event.
6.
Click OK.
A new Static Routing section appears where you can define the routing rule.
7.
Configure the routing rule as described the remaining sections of this chapter.
To echo a service:
1.
In the Routing Rules section, click Add next to the operation for which you are
defining routing rules, and then select static routing rule.
The Target Type dialog is displayed, as shown in Figure 207.
2.
Click Echo.
The Echo button only appears on the Target Type dialog if the
interface is synchronous or asynchronous.
Note:
20-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 208 shows a routing rule with a synchronous echo. An asynchronous echo
has an icon with a dotted line on the return.
Figure 208 Sample Mediator Supporting Echo Operation
Echoing a service is supported only with Mediator interfaces having the following
types of WSDL files:
Request/reply
Request/reply/fault
Request/callback
The echo option is not available for Mediator interfaces having
request/reply/fault/callback WSDL files or for one-way WSDL files.
Note:
The echo option is available for synchronous operations like request/reply and
request/reply/fault.
Note: The echo option is only available for synchronous operations
when the routing rule is sequential because parallel routing rules are
not supported for Mediators with synchronous operations.
For synchronous operations with a conditional filter, the echo option does not
return a response to the caller when the filter condition is set to false. Instead, it
returns a null response.
The echo option is available for asynchronous operations only if the Mediator
interface has a callback operation. In this case, the echo is run on a separate thread.
The asynchronous echo option is available only when the
routing rule is parallel. If you use the echo option, then sequential
routing rules are not supported for Mediators with asynchronous
operations.
Note:
20-11
The following steps are performed in the Routing Rules section of the Mediator Editor.
1.
Next to the <<Target Operation>> field by the Timeout in field in the Callback
section, click the Browse for target service operation icon.
The Target Type dialog appears.
2.
3.
4.
Click OK
20-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
In the Timeout in field, enter the number of units for the timeout period, and then
select the unit of time from the dropdown list.
The timeout response is forwarded to the specified service or event.
If the number of routing rules is larger and the time taken to
execute the routing rules exceeds the transaction timeout, you must
set the transaction timeout to a value that is greater than the time
taken to execute all the routing rules.
Note:
20-13
The following steps are performed in the Routing Rules section of the Mediator Editor.
1.
In the Faults section, click the Add another fault routing button shown in
Figure 2010.
20-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2010
Configure the target service, transformations, and assign values for the new fault.
Figure 2011 shows a second fault being routed to a file adapter service.
Figure 2011
20-15
You can route the same fault to multiple targets using different
transformations.
Note:
The following steps are performed in the Routing Rules section of the Mediator Editor.
Highlight the fault routing you want to remove by clicking in the target service
field, and then click Delete the selected fault routing, as shown in Figure 2012.
20-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Two examples of filter expression message properties are shown in Example 201.
Example 201
$in.property.custom.Priority = '1'
$in.property.tracking.ecid = '2'
Two examples of filter expression message headers are shown in Example 202.
Example 202
$in.header.wsse_Security/wsse:Security/Priority = '234'
$in.header.wsse_Security/wsse:Security/Priority = '234'
For the preceding filter expression message headers to work, you must add the
attribute shown in Example 203 to the root element of the .mplan file.
Example 203
Attribute to Add
wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuritysecext-1.0.xsd"
You can use the Expression Builder to graphically create a filter expression. The
Expression Builder dialog contains the components and controls that assist you in
designing a filter expression.
1.
To the right of the Filter Expression field in the Routing Rules section, click the
Invoke Expression Builder icon.
The Expression Builder dialog appears, as shown in Figure 2013.
20-17
2.
Double-click a value in the Variables field or the Functions palette to add the
value to the Expression field. Using a combination of variable elements, functions,
and manually entered text, you can build an expression by which you want
message payloads to be filtered for a given routing rule.
Table 201 describes each of the fields in the Expression Builder dialog:
Table 201
Field
Description
Expression
Variables
Functions Palette
20-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Content Preview
This field indicates how a value selected from the Variables field
or Functions palette appears when it is inserted into the
Expression field.
Description
This field describes the value selected from the Variables field or
Functions Palette.
To the right of the Filter Expression field in the Routing Rules section, click the
Invoke Expression Builder icon.
The Expression Builder dialog is displayed.
2.
In the Variables field, expand the message definition and select the message
element on which you want to base the expression.
For example, the CustomerId element is shown selected in Figure 2014.
Figure 2014
3.
20-19
4.
From the Functions list, select the function to apply to the message payload. For
example, equals.
Functions are grouped in categories that are listed when you click the down arrow
in the Functions list. For example, if you click the down arrow and select Logical
Functions, the list appears as shown in Figure 2015.
5.
6.
20-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2016
7.
If there are any errors, you can edit the expression manually, or use the expression
editing icons, which are summarized in Figure 2017.
Figure 2017
8.
Click OK.
The expression is added to the Routing Rules section.
To modify or delete a filter expression, double-click the Add Filter Expression icon,
and then modify or delete the expression in the Expression field of the Expression
Builder.
In the Routing Rules section, click the Select an existing mapper file or create a
new one icon to the right of the Transform Using field.
Creating Oracle Mediator Routing Rules
20-21
The Request Transformation Map dialog appears. You can select an existing XSL
file or create a new XSL file with the XSLT Mapper to perform the required
transformation.
2.
3.
If the mapping file exists, select Use Existing Mapper File and then click
Browse to find and select the mapper file to use.
To create a mapper file, select Create New Mapper File, and then enter the
input information.
Repeat the above steps for any synchronous reply, callback, response, or fault
messages.
In case of synchronous reply or fault message, the Reply Transformation Map
dialog or the Fault Transformation Map dialog contains an Include Request in the
Reply Payload option, as shown in Figure 2018.
4.
Note:
20-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For information about the XSLT Mapper, see Chapter 40, "Creating Transformations
with the XSLT Mapper."
To add user-defined extension functions:
You can use the Expression Builder to include user-defined extension functions.
1.
2.
Register the Jaxen XPath function with a Mediator service component in the
xpath-function.xml file on the server.
3.
4.
5.
6.
Copy the JAR file containing the user-defined extension functions to the
$BEAHOME/user_
projects/domains/soainfra/autodeploy/soa-infra/APP-INF/lib
directory.
7.
Add the function namespace you defined for the extension functions under
the Mediator element.
Add the function names under the Expression element.
8.
20-23
2.
In the From section, select any of the following options from the Type list:
20-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
the Expression field, the Expression Builder dialog similar to the one shown in
Figure 2013 is displayed.
For more information about the Expression Builder dialog, see Section 20.3.2.8,
"How to Specify an Expression for Filtering Messages."
3.
Constant: Select this option to assign a constant value to the target message.
Property: Select this option to copy the value to a message property. The
Variable field of the Expression Builder dialog contains an $out variable that
contains the output message. You can use $out.property to access properties of
an output message.
Expression: Select this option to copy the value to an expression. When you
click the Invoke Expression Builder icon to the right of the Expression field,
the Expression Builder dialog is displayed. The Variable field of the
Expression Builder dialog contains an $out variable that contains the output
message. You can use $out.partname to access a complete output message or
part of an output message.
Figure 2023 shows a sample Assign Value dialog in which a constant value is
specified as an expression.
Figure 2023
4.
5.
Click OK. The expression is added to Assign Values field of the Routing Rules
section.
20-25
Notes:
Table 202 through Table 204 list the various possibilities of assignment on constants
and properties, payloads, and headers of a message from source to target.
Table 202
Source
Target
Example
Property
Property
<copy
expression="$in.property.jca.file.FileName"
target="$out.property.jca.file.FileName"/>
Constant
Property
<copy value="ConstantNameAssigned.xml"
target="$out.property.jca.file.FileName"/>
Table 203
Possibilities on Payload
Source
Target
Example
XPath
Expression
Property
<copy
expression="concat('ExprPropMed','-',oraext
:generate-guid())"
target="$out.property.jca.file.FileName"
xmlns:oraext="http://www.oracle.com/XSL/Tra
nsform/java/oracle.tip.pc.services.function
s.ExtFunc"/>
XPath
Expression
(below part
level)
Property
<copy
expression="$in.body/imp1:request/ProductRe
q/Make"
target="$out.property.jca.file.FileName"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
Property
XPath
Expression
(below part
level)
<copy
value="$in.property.jca.file.FileName"
target="$out.request/inp1:request/ProductRe
q/Model"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
Constant
XPath
Expression
(below part
level)
<copy value="ConstantModel"
target="$out.request/inp1:request/ProductRe
q/Model"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
XPath
Expression
XPath
Expression
<copy expression="$in.body"
target="$out.request"/>
20-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Target
Example
XPath
Expression
(below part
level)
XPath
Expression
(below part
level)
<copy
expression="$in.body/imp1:request/ProductRe
q/Make"
target="$out.request/imp1:request/ProductRe
q/Model"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
Table 204
Possibilities on Header
Source
Target
Example
XPath
Expression
(below part
level)
Property
<copy expression="$in.header.inp1_
header/inp1:header/Name"
target="$out.property.jca.file.FileName"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
Property
XPath
Expression
(below part
level)
<copy
value="$in.property.jca.file.FileName"
target="$out.header.inp1_
header/inp1:header/Name"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
Constant
XPath
Expression
(below part
level)
<copy value="NewID.xml"
target="$out.header.inp1_
header/inp1:header/Id"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
Constant
XPath
Expression
(below part
level)
<copy value="sampleusername"
xmlns:wsse1="http://docs.oasis-open.org/wss
/2004/01/oasis-200401-wss-wssecurity-secext
-1.0.xsd" target="$out.header.wsse1_
Security/wsse1:Security/wsse1:UsernameToken
/wsse1:Username"/>
XPath
Expression
XPath
Expression
<copy target="$out.header.inp1_header"
expression="$in.header.inp1_header"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
XPath
Expression
(below part
level)
XPath
Expression
(below part
level)
<copy target="$out.header.inp1_
header/inp1:header/Name"
expression="$in.header.inp1_
header/inp1:header/Id"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
20.3.2.11 What You May Need to Know About the Assign Activity
Note the following issues about the assign activity.
The assign activity is executed in the order that is present in the Mediator <copy>
element.
A source XPath expression should always refer to a leaf node while the source is
assigned to a target property. Otherwise, all the values of the child nodes in the
source get concatenated and are assigned to the target property. Example 204
provides details.
Example 204
<copy target="$out.property.jca.file.FileName"
expression="$in.body/imp1:request/ProductReq/Make"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
20-27
Note:
Example 205
Example 206
If one of the child nodes in the target payload has to be modified, then there are
the following two use cases:
Example 207
<copy value="ConstantModel"
target="$out.request/inp1:request/ProductReq/Model"
xmlns:inp1="http://xmlns.oracle.com/psft"/>
If a transformation is not available, then there are two steps involved. First,
assign the source part to the target part, and then assign the source expression
to a target XPath expression that is pointing to the child node in the target.
Example 208 provides details.
Example 208
When only one of the child nodes of the source has to be propagated into a target,
then first ensure that there is no transformation invoked. Then, assign the source
XPath expression to point to the required child node. Example 209 provides
details.
20-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 209
<copy target="$out.request/imp1:ProductReq"
expression="$in.body/imp1:request/ProductReq"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
If there are multiple assign activities in a Mediator and each source XPath
expression points to a different child node, then there are the following two use
cases:
The part level assign activity overwrites the target header part.
The below part level node assign activity updates the corresponding node in
the target.
If multiple source nodes (below part level) are assigned to the same target node
(below part level), then the target node contains the value of the last copy element
in the assign activity. Example 2011 provides details.
Example 2011 Multiple Source Nodes Assigned to the Same Target Node
<copy target="$out.request/imp1:request/ProductReq/Make"
expression="$in.body/imp1:request/ProductReq/Model"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
<copy target="$out.request/imp1:request/ProductReq/Make"
expression="$in.body/imp1:request/Description"
xmlns:imp1="http://xmlns.oracle.com/psft"/>
In Example 2011, the first copy element does not have any effect because the
second copy element overwrites it.
If the XPath expression results in a list (multiple occurrences), then there are the
following two use cases:
If the list contains a single element, then the XPath expression is propagated.
If the list contains multiple elements, then the XPath expression is not
supported.
20-29
The following activities happen while assigning a source child node to a target
child node:
1.
The source child node name and namespace are overwritten by the target
node name and namespace, respectively.
2.
The target child node is replaced by the source child node in the parent node
of the target node.
Assume the namespace prefixes wsse and ns1 are already defined in the WSDL file or
the .mplan file. You can then write an XPath expression as follows:
$in.header.wsse_Security/wsse:Security/ns1:Foo/Priority
Assume you want to use a schema that does not have a namespace predefined in the
WSDL file. The Expression Builder is then enhanced to allow you to enter {full_
namespace} instead of a prefix. The Expression Builder then generates a unique
prefix and the prefix definition is added to the .mplan file.
For example, enter the expression in the Expression Builder shown in Example 2012:
Example 2012 Expression
$in.header.{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd}_Security/
{"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xs
d"}:
Security/{"http://www.globalcompany.com/ns/OrderBooking"}:Foo/Priority
20-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2024
By default, SOAP headers are not passed through by Mediator. You must add the
passThroughHeader endpoint property to the corresponding Mediator routing
service:
<property name="passThroughHeader">true</property>
For example, to add this property, you can modify the composite.xml file, as shown
in Example 2014.
Example 2014 passThroughHeader Property
<component name="Mediator1">
<implementation.mediator src="Mediator1.mplan"/>
<property name="passThroughHeader">true</property>
</component>
For the headers to pass through, the source and the target must have the same QName
(name and namespace). If the source and the target have different QNames, then either
a transformation or part-level assignment must be performed.
It is important to note that, with a passthrough Mediator (without a transformation
or assign), if the source and target part QNames are not identical, then Mediator
passes through the message payloads to the target service without any error. However,
this can result in an error in the target service because the message payloads are not
reconstructed according to the message structure of the target service.
Notes:
The user interface supports both SOAP 1.1 and SOAP 1.2.
For automatic header detection, a concrete WSDL file must be
used when creating the Mediator service component.
Assignments execute after filters. Therefore, if you are assigning a
value in a custom header, then the particular assignment is not
visible to the filter.
20-31
20.3.2.12.1 Manual Expression Building for Accessing Headers for Filters and Assignments
There are use cases in which the header schemas cannot be determined from the
WSDL files. For example, security headers that are appended to a message, or the
headers for a Mediator that are created using an abstract WSDL file. To access these
headers, you must manually enter the XPath expression into the Expression Builder.
The syntax for header expressions is shown in Example 2015.
Example 2015 Header Expressions Syntax
$in.header.<header root element namespace prefix>_<header root element
name>/<xpath>
For the preceding expressions to work, you must add the attribute shown in
Example 2018 to the root element of the .mplan file.
Example 2018 Addition of Attribute to .mplan File
wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuritysecext-1.0.xsd"
20.3.2.12.2 Manual Expression Building for Accessing Properties for Filters and Assignments
An example of a filter expression is as follows.
$in.property.tracking.ecid = '2'
value="$in.property.tracking.ecid"/>
To the right of the Validate Semantic field, click the Select Validation File icon.
20-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Click Add.
The Add Validation dialog is displayed.
3.
4.
5.
6.
Click OK.
The Validation dialog is updated, as shown in Figure 2026.
Figure 2026
7.
Validation Dialog
Click Add to specify a Schematron file for another message part or click OK.
20-33
For more information about building a Schematron schema, see the resources
available at
http://www.schematron.com
In semantic validation, if you check for the length of each
element name, then the element name may change for a different set
of inputs. This happens when there are white spaces between nodes
because the parser treats the white spaces as test nodes.
Note:
20-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You must ensure that the Java callout class is available on the server. You can use any
of the following methods for this:
Copy the JAR file containing the Java class to the SCA-INF/lib folder.
Copy the JAR file containing the Java class to the $DOMAIN_HOME/lib folder.
If you want to make the Java callout class available to multiple Mediators, copy the
JAR file containing the Java class to the $DOMAIN_HOME/lib folder.
To enter the Java class for the callout:
You can either manually enter the Java class or select a class from the Class Browser.
To manually enter the name of the Java callout class, start typing the class name in
the Callout To field, as shown in Figure 2028. The auto-completion feature of
Oracle JDeveloper completes the address and the classes in the current project.
Figure 2028
Callout To Field
To select from a list of available classes, click the Select Java Callout Class icon.
The standard Oracle JDeveloper class browser appears, as shown in Figure 2029.
Figure 2029
The class browser is filtered so it only displays classes that implement the
oracle.tip.mediator.common.api.IjavaCallout interface.
To set the payload root element (when using a filter expression):
Creating Oracle Mediator Routing Rules
20-35
If you have a Java callout in Mediator and use a filter expression in the same Mediator,
you must set the root element for the payload, as shown in Example 2019.
Example 2019 Setting the Root Element for the Payload
changexmldoc = XmlUtils.getXmlDocument(ChangedDoc);
String mykey = "request";
message.addPayload(mykey,changexmldoc.getDocumentElement());
To use domain value map functions or cross reference functions in a Java callout, you
must add the soa-xpath-exts.jar file to the project and import the necessary Java
classes into your code.
1.
In the Oracle JDeveloper Projects Explorer, right-click the name of the project
containing the Java callout.
2.
3.
In the left panel, select Libraries and Classpath, as shown in Figure 2030.
4.
20-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2031
5.
6.
Click OK.
Notes: When using domain value map functions, import the
following into your Java class:
oracle.tip.dvm.LookupValue
oracle.tip.dvm.exception.DVMException
When using cross reference (xref) functions, import the following into
your Java class:
oracle.tip.xref.xpath.XRefXPathFunctions
oracle.tip.xref.exception.XRefException
Method
Description
initialize
20-37
Description
preRouting
preRoutingRule
preCallbackRouting
postRouting
postRoutingRule
postCallbackRouting
<assign>
<copy target="$out.property.jca.file.FileName"
expression="$in.property.jca.file.FileName"/>
</assign>
Method
Description
addPayload
addProperty
addHeader
getProperty
getProperties
getId
20-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
getPayload
getHeaders
getComponentDN
Notes:
The
oracle.tip.mediator.common.api.AbstractJavaCallou
tImpl class is a dummy implementation of the IJavaCallout
interface. This class defines all the methods present in the
IJavaCallout interface. Therefore, you can extend this class to
override only a few specific methods of the IJavaCallout
interface.
Dummy implementation of an interface means that the
implementation class provides definitions for all the methods
declared in the particular interface, but one or more defined
methods may have an empty method body. Extending a dummy
implementation class is much easier because you can choose to
override only a subset of the methods, unlike implementing an
interface and defining all the methods.
Details of the processing occurring within the Java callout are not
displayed in the Mediator audit trail screen.
package qa.as11tests.javacallout;
import com.collaxa.cube.persistence.dto.XmlDocument;
import com.oracle.bpel.client.NormalizedMessage;
import java.util.logging.Logger;
import java.util.Map;
import java.util.Iterator;
import
import
import
import
import
import
oracle.tip.mediator.common.api.CalloutMediatorMessage;
oracle.tip.mediator.common.api.ExternalMediatorMessage;
oracle.tip.mediator.common.api.IJavaCallout;
oracle.tip.mediator.common.api.MediatorCalloutException;
oracle.tip.mediator.metadata.CaseType;
oracle.tip.mediator.utils.XmlUtils;
import oracle.tip.pc.services.functions.ExtFunc;
import oracle.xml.parser.v2.XMLDocument;
import org.w3c.dom.Document;
20-39
import org.w3c.dom.Element;
import org.w3c.dom.Node;
public class JavaCalloutSanity implements IJavaCallout {
Logger logger = Logger.getLogger("Callout");
public JavaCalloutSanity() {
}
public void initialize(Logger logger) throws MediatorCalloutException {
this.logger = logger;
this.logger.info("Initializing...");
}
public boolean preRouting(CalloutMediatorMessage calloutMediatorMessage) {
System.out.println("Pre routing...");
String sPayload = "null";
String sPayload_org = "null";
for (Iterator msgIt =
calloutMediatorMessage.getPayload().entrySet().iterator();
msgIt.hasNext(); ) {
Map.Entry msgEntry = (Map.Entry)msgIt.next();
Object msgKey = msgEntry.getKey();
Object msgValue = msgEntry.getValue();
if (msgKey.equals("request"))
sPayload = XmlUtils.convertDomNodeToString((Node)msgValue);
}
sPayload_org = sPayload;
String tobeReplaced = "CHANGE_THIS";
String replaceWith = "JAVA_CALLOUT_||_PRE_ROUTING";
int start = sPayload.indexOf(tobeReplaced);
StringBuffer sb = new StringBuffer();
sb.append(sPayload.substring(0, start));
sb.append(replaceWith);
sb.append(sPayload.substring(start + tobeReplaced.length()));
String changedPayload = sb.toString();
String uid;
try {
uid = ExtFunc.generateGuid();
} catch (Exception e) {
}
XMLDocument changedoc;
try {
changedoc = XmlUtils.getXmlDocument(changedPayload);
String mykey = "request";
calloutMediatorMessage.addPayload(mykey,
changedoc.getDocumentElement());
//calloutMediatorMessage.getPayload().put(mykey, changedoc);
} catch (Exception e) {
}
System.out.println("Changed from : \n"+sPayload_
org+"\nTo\n"+changedPayload);
System.out.println("End Pre routing...\n\n");
return false;
}
public boolean postRouting(CalloutMediatorMessage calloutMediatorMessage,
CalloutMediatorMessage calloutMediatorMessage1,
Throwable throwable) throws
MediatorCalloutException {
System.out.println("Start Post routing...");
String sPayload = "null";
String sPayload_org = "null";
for (Iterator msgIt =
20-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
calloutMediatorMessage1.getPayload().entrySet().iterator();
msgIt.hasNext(); ) {
Map.Entry msgEntry = (Map.Entry)msgIt.next();
Object msgKey = msgEntry.getKey();
Object msgValue = msgEntry.getValue();
if(msgKey.equals("reply"))
sPayload = XmlUtils.convertDomNodeToString((Node)msgValue);
}
sPayload_org = sPayload;
String tobeReplaced = "POST_ROUTING_RULE_REQUEST_REPLY";
String replaceWith = "POST_ROUTING_RULE_REQUEST_REPLY_||_POSTROUTING_||_
JAVA_CALLOUT_WORKING";
int start = sPayload.indexOf(tobeReplaced);
StringBuffer sb = new StringBuffer();
sb.append(sPayload.substring(0, start));
sb.append(replaceWith);
sb.append(sPayload.substring(start + tobeReplaced.length()));
String changedPayload = sb.toString();
XMLDocument changedoc;
try {
changedoc = XmlUtils.getXmlDocument(changedPayload);
String mykey = "reply";
calloutMediatorMessage1.addPayload(mykey,changedoc.getDocumentElement());
// calloutMediatorMessage1.getPayload().put(mykey,
changedoc.getDocumentElement());
} catch (Exception f) {
}
System.out.println("Changed from : \n"+sPayload_org+"\nTo\n"+
changedPayload);
System.out.println("End Post routing...\n\n");
return false;
}
public boolean preRoutingRule(CaseType caseType,
CalloutMediatorMessage calloutMediatorMessage) {
System.out.println("\nStart PreRoutingRule.\n");
String sPayload = "null";
String sPayload_org = "null";
for (Iterator msgIt =
calloutMediatorMessage.getPayload().entrySet().iterator();
msgIt.hasNext(); ) {
Map.Entry msgEntry = (Map.Entry)msgIt.next();
Object msgKey = msgEntry.getKey();
Object msgValue = msgEntry.getValue();
if(msgKey.equals("request"))
sPayload = XmlUtils.convertDomNodeToString((Node)msgValue);
}
sPayload_org = sPayload;
String tobeReplaced = "PRE_ROUTING";
String replaceWith = "PRE_ROUTING_||_PRE_ROUTING_RULE";
int start = sPayload.indexOf(tobeReplaced);
StringBuffer sb = new StringBuffer();
sb.append(sPayload.substring(0, start));
sb.append(replaceWith);
sb.append(sPayload.substring(start + tobeReplaced.length()));
String changedPayload = sb.toString();
XMLDocument changedoc;
try {
20-41
changedoc = XmlUtils.getXmlDocument(changedPayload);
String mykey = "request";
calloutMediatorMessage.addPayload(mykey,
changedoc.getDocumentElement());
// calloutMediatorMessage.getPayload().put(mykey, changedoc);
} catch (Exception e) {
}
System.out.println("Changed from : \n"+sPayload_
org+"\nTo\n"+changedPayload);
System.out.println("End PreRoutingRule.\n\n");
return true;
}
public boolean postRoutingRule(CaseType caseType,
CalloutMediatorMessage calloutMediatorMessage,
CalloutMediatorMessage calloutMediatorMessage1,
Throwable throwable) {
System.out.println("Start PostRoutingRule.");
String req_sPayload = "null";
String req_sPayload_org = "null";
String rep_sPayload = "null";
String rep_sPayload_org = "null";
for (Iterator msgIt =
calloutMediatorMessage.getPayload().entrySet().iterator();
msgIt.hasNext(); ) {
Map.Entry msgEntry = (Map.Entry)msgIt.next();
Object msgKey = msgEntry.getKey();
Object msgValue = msgEntry.getValue();
if(msgKey.equals("request"))
req_sPayload = XmlUtils.convertDomNodeToString((Node)msgValue);
}
req_sPayload_org = req_sPayload;
String tobeReplaced = "PRE_ROUTING_RULE";
String replaceWith = "PRE_ROUTING_RULE_||_POST_ROUTING_RULE_REQUEST";
int start = req_sPayload.indexOf(tobeReplaced);
StringBuffer sb = new StringBuffer();
sb.append(req_sPayload.substring(0, start));
sb.append(replaceWith);
sb.append(req_sPayload.substring(start + tobeReplaced.length()));
String changedPayload = sb.toString();
XMLDocument changedoc;
try {
changedoc = XmlUtils.getXmlDocument(changedPayload);
String mykey = "request";
calloutMediatorMessage.addPayload(mykey,
changedoc.getDocumentElement());
// calloutMediatorMessage.getPayload().put(mykey, changedoc);
} catch (Exception e) {
}
for (Iterator msgIt =
calloutMediatorMessage1.getPayload().entrySet().iterator();
msgIt.hasNext(); ) {
Map.Entry msgEntry = (Map.Entry)msgIt.next();
Object msgKey = msgEntry.getKey();
Object msgValue = msgEntry.getValue();
if(msgKey.equals("reply"))
rep_sPayload = XmlUtils.convertDomNodeToString((Node)msgValue);
}
rep_sPayload_org = rep_sPayload;
tobeReplaced = "PRE_ROUTING_RULE";
replaceWith = "PRE_ROUTING_RULE_||_POST_ROUTING_RULE_REQUEST_REPLY";
20-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
start = rep_sPayload.indexOf(tobeReplaced);
sb = new StringBuffer();
sb.append(rep_sPayload.substring(0, start));
sb.append(replaceWith);
sb.append(rep_sPayload.substring(start + tobeReplaced.length()));
changedPayload = sb.toString();
try {
changedoc = XmlUtils.getXmlDocument(changedPayload);
String mykey = "reply";
calloutMediatorMessage1.addPayload(mykey,changedoc.getDocumentElement());
// calloutMediatorMessage1.getPayload().put(mykey,
changedoc.getDocumentElement());
} catch (Exception e) {
}
System.out.println("Changed from : \n"+req_sPayload_
org+"\nTo\n"+changedPayload);
System.out.println("End postRoutingRule\n\n");
return true;
}
}
1.
Figure 2032
This creates a new business rule service component that is wired to the Mediator
service component within the SOA composite of the Mediator service component.
The wire links between the business rule service component and the Mediator
service component are considered implementation details and are shown as dotted
lines in the SOA Composite Editor, as shown in Figure 2033.
20-43
Figure 2033 SOA Composite Editor with Wire Links Between the Business Rule and
Mediator Service Components
The business rule service component includes a rule dictionary. The rule
dictionary is a metadata container for the rule engine artifacts, such as fact types,
rulesets, rules, decision tables and so on. As part of creating the business rule
service component, the rule dictionary is preinitialized with the following data.
Ruleset
A ruleset is a container of rules used as a kind of grouping mechanism for
rules. A ruleset can be exposed as a service. As part of creating the business
rule service component, one ruleset is created within the rule dictionary.
Decision Service
As part of creating the business rule service component, a decision service is
created to expose the ruleset as a service of the business rule service
component. The service interface is used by the Mediator service component
to evaluate the decision table.
After all the required artifacts of the phase activity are created, the wizard starts
modeling the phase decision matrix (PDM). The wizard launches the Business
Rules Designer of Oracle JDeveloper and enables you to edit the phase decision
matrix. Figure 2034 shows a sample decision table within the Business Rules
Designer.
20-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Once the dynamic routing is created, you can modify the associated decision
matrix by clicking Edit Dynamic Rules. This launches the Business Rules
Designer and enables modification of the associated decision table of the business
rule service component. After you create dynamic routing for the Mediator service
component, you cannot return to static routing without deleting the dynamic
routing. Currently, there is no option for mixing these two types of routing.
The Mediator Editor looks as shown in Figure 2035 after the dynamic routing
option is chosen.
Figure 2035
The switch element contains the decision service reference and operation details
to enable the Mediator service component to invoke the decision service in
runtime for obtaining the dynamic routing decisions. Dynamic decisions are
returned by the business rule service engine user configuration at runtime.
20-45
20.3.4 What You May Need to Know About Using Dynamic Routing Rules
Note the following limitations on using dynamic routing rules with Mediator:
As of now, only SOAP bindings are supported. There is a dummy SOAP binding
in the composite.xml file. This endpoint is overridden by Mediator in runtime
through an NM property. Therefore, outbound services can be called only over
SOAP.
Payload manipulation is limited for dynamic routing rules. No assignment,
transformation, or validation can be performed.
The reference WSDL file (layer 2 or called references) should have the same
abstract WSDL file as the phase reference that gets automatically created.
Dynamic routing is not possible for Mediators with a synchronous or one-way
interface.
20-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Message Evaluation of xpath condition " No Filter (DEFAULT CASE) " resulted
true
You can define all routing rules, including default routing rules, as either sequential or
parallel routing rules, so the expected behavior of routing rules varies. The following
sections discuss each combination and the expected behavior:
Sequential Default Routing Rule
You can have the following possible scenarios with a sequential default routing rule:
All the other routing rules of the Mediator are sequential: This is the simplest
case in which all the routing rules, including the default routing rule, are of a
sequential type. Runtime evaluates the filter conditions of all routing rules and, if
none of the filter conditions are matched, then the default sequential routing rule
is executed. Default sequential routing rule execution happens in the same
transaction as the incoming message. After the default rule is executed, a post Java
callout occurs.
At Least One of the Routing Rules of the Mediator are parallel: This is a complex
case in which the default routing rule is sequential and at least one of the other
routing rules is parallel. The default behavior at runtime is to execute all
sequential routing rules first and then execute parallel routing rules. Therefore,
this is a tricky situation because a default rule should be executed only after all
other routing rules are evaluated to be false.
In this case, the server first evaluates the filter condition of parallel rules before
evaluating the default routing rule filter condition. If none of the other filter
conditions are matched, then the default sequential routing rule is executed.
You can have the following possible scenarios with a parallel default routing rule:
All the other routing rules of the Mediator are parallel: This is a straightforward
case. The default routing rule is not executed if any of the filter conditions
specified in the other routing rules are matched. If none of the filter conditions are
matched, then the default routing rule is executed asynchronously.
Other Routing Rules of the Mediator are sequential or parallel: This is a complex
but common use case in which there are other sequential or parallel routing rules
available, and the default routing rule is parallel. The default routing rule is not
executed if any of the other sequential or parallel routing rule criteria is matched.
If none of the conditions are matched, then the default routing rule is executed
asynchronously.
The fact that the default routing rule is executed automatically
implies that the default routing rule is the only case that was executed
for the given Mediator service component. Similarly, if a Mediator
service component has one routing rule without any filter condition
and also has a default routing rule, then the default routing rule is
never executed.
Note:
20-47
forwarded or returned to the original caller. If the target service returns a fault, then
the fault is handled in the same way as it is handled in any other routing rule.
If exceptions occur while evaluating or executing other routing
rules, then the default routing rule is not executed.
Note:
Note:
20-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2036
20-49
20-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
21
Working with Multiple Part Messages in
Oracle Mediator
21
This chapter describes how to define routing rules for multiple part (multipart)
messages for an Oracle Mediator service component, including defining filters,
transformations, and validations.
This chapter includes the following sections:
For more information on routing rules, see Chapter 20, "Creating Oracle Mediator
Routing Rules."
21-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 214
21.2.5 How to Work with Multipart Reply, Fault, and Callback Source Messages
The method to create transformations and assign values to multipart reply, fault, and
callback source messages is the same as working with request source messages.
You cannot specify filter expressions or add validations for
reply, fault, and callback messages.
Note:
21-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
22
Using Oracle Mediator Error Handling
22
This chapter describes the error handling capabilities of Oracle Mediator and provides
instructions for defining error handling for both business faults and system faults.
This chapter includes the following sections:
Fault policies
Fault bindings
Error groups
Due to the single threading of sequential routing rules, only three actions (Abort,
Rethrow, and Java) are supported for handling errors, and the specified actions
are executed immediately in the callers thread.
Mediator messages are not persisted in sequential routing.
Asynchronous and one-way Mediator components cannot handle system faults
thrown from other SOA Suite components, such as a BPEL business process.
For more information about available error handling actions, see Section 22.1.1.2,
"Actions."
A sample fault policy file is shown in Example 221:
Example 221
The two components of the fault policy (conditions and actions) are described in the
following sections.
22.1.1.1 Conditions
Conditions allow you to identify error or fault conditions and then specify the actions
to be taken when a particular error or fault condition occurs. For example, for a
particular error occurring because of a service not being available, you can perform an
action such as a retry. Similarly, for another error occurring because of the failure of
Schematron validation, you can perform the action of human intervention. This fault
can be recovered manually by editing the payload and then resubmitting it through
Oracle Enterprise Manager Fusion Middleware Control.
Conditions are defined in the fault-policies.xml file, as shown in Example 222:
Example 222
Conditions
<Conditions>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
22-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
name="medns:mediatorFault">
<condition>
<test>contains($fault.mediatorErrorCode,"TYPE_DATA_
TRANSFORMATION")</test>
<action ref="ora-java"/>
</condition>
</faultName>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:mediatorFault">
<condition>
<test>contains($fault.mediatorErrorCode, "TYPE_FATAL_MESH")</test>
<action ref="ora-retry"/>
</condition>
</faultName>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:mediatorFault">
<condition>
<test>contains($fault.mediatorErrorCode,"TYPE_DATA_ASSIGN")</test>
<action ref="ora-retry-crm-endpoint"/>
</condition>
</faultName>
</Conditions>
You can categorize the faults that can be captured using conditions into the following
types:
Mediator-specific faults
For all Mediator-specific faults, the Mediator service engine throws only one fault,
namely
{http://schemas.oracle.com/mediator/faults}mediatorFault.
Every Mediator fault is wrapped into this fault. The errors or faults generated by a
Mediator can be captured by using the format shown in Example 223:
Example 223
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:mediatorFault">
<!-- mediatorFault is a bucket for all the mediator faults -->
<condition>
<test>
contains($fault.mediatorErrorCode, "TYPE_FATAL_MESH")
</test>
<!-- Captures TYPE_FATAL_MESH errors -->
<action ref="ora-retry"/>
</condition>
</faultName>
Example 224
<faultName xmlns:ns1="http://xmlns.oracle.com/Customer"
name="ns1:InvalidCustomer"> <!-- Qname of Business/SOAP fault -->
<condition>
<test>
contains($fault.<PART_NAME>/custid, 1011)
</test>
<!-- xpath condition based on fault payload -->
<action ref="ora-retry"/>
</condition>
</faultName>
When a reference service returns a business fault, the fault can be handled in the
Mediator service component. The returned fault can be forwarded to another
component, redirected to an adapter service such as a file adapter, or an event can
be raised. However, if both a fault policy and fault handler are defined for a
business fault, then the fault policy takes precedence over the fault handler. In
such a case, the fault handlers in the Mediator service component are ignored, if
the fault policy is successfully executed.
Adapter-specific fault
The errors or faults generated by an adapter can be captured by using the format
shown in Example 225:
Example 225
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:mediatorFault">
<condition>
<test>$fault.faultCode = "1"</test> <!-- unique constraint violation in DB
adapter-->
<action ref="ora-retry"/>
</condition>
</faultName>
22.1.1.2 Actions
Actions specify the tasks to perform when an error occurs. Mediator supports retry,
human intervention, abort, and Java code actions for parallel routing rules. For
sequential routing rules, fault policies can contain these actions: abort, rethrow, and
Java code.
If retry or human intervention action is chosen with sequential routing rules, the fault
goes back to the caller directly, and the policy is not applied. The fact that an
incompatible action was chosen is recorded in the log. This is consistent with BPEL
fault policy behavior. It is the responsibility of the caller to handle the fault. If the
caller is an adapter, you can define rejection handlers on the inbound adapter to take
care of the messages that error out (that is, the rejected messages). For more
information about rejection handlers, see Oracle Fusion Middleware User's Guide for
Technology Adapters.
Fault policy actions are described in the following sections.
22.1.1.2.1
Retry Action
Retry actions such as enqueueing a message to a JMS queue that is stopped, inserting a
record with a unique key constraint error, and so on, enable you to retry a task that
caused the error. A new thread is started with every retry action. Therefore, with every
retry action, a new transaction starts. Table 221 describes the options available with
the retry action. Retry actions are applicable to parallel routing rules only.
22-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 221
Option
Description
Retry Count
Retry N times.
Retry Interval
Exponential Backoff
Note:
Retry Action
<Action id="ora-retry">
<retry>
<retryCount>3</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff/>
<retryFailureAction ref="ora-java"/>
<retrySuccessAction ref="ora-java"/>
</retry>
</Action>
If you set the retry interval in the fault policy to a duration of less than 30 seconds,
then the retry may not happen within the specified intervals. This is because the
default value of the org.quartz.scheduler.idleWaitTime property is 30
seconds, and the scheduler waits for 30 seconds before retrying for available triggers,
when the scheduler is otherwise idle. If the retry interval is set to a value of less than
30 seconds, then latency is expected.
If you want the system to use a retry interval that is less than 30 seconds, add the
following property under the section <property name="quartzProperties"> in
the fabric-config-core.xml file:
org.quartz.scheduler.idleWaitTime=<value>
22.1.1.2.2
Rethrow Action
Rethrow executes the fault policy in the callers thread and returns the original
exception to the user.
An example of a rethrow action is shown below:
<Action id="ora-rethrow-fault"><rethrowFault/></Action>
22.1.1.2.3
The human intervention action allows you to manually recover the fault by correcting
the error (for example, altering the payload) and then manually retrying the message.
This action is applicable to parallel routing rules only.
An example of a human intervention action is shown below:
<Action id="ora-human-intervention"><humanIntervention/></Action>
22.1.1.2.4
Abort Action
The abort action enables you to terminate the message flow. This action is applicable
to both parallel and sequential routing rules.
When the abort action is executed for a sequential routing rule, the exception
FabricInvocationException is thrown back to the caller, and the mediator
component state changes to terminated. The fault policy is executed in the callers
thread.
An example of an abort action is shown below:
<Action id="ora-terminate"><abort/></Action>
22.1.1.2.5
The Java code action lets you call a customized Java class that implements the
oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass
interface. This action is applicable to both parallel and sequential routing rules.
Example 227 shows how Java code actions can be implemented.
Notes: The implemented Java class must implement a method that
returns a string. The policy can be chained to a new action based on
the returned string.
The Java code action first looks for the implemented class in the
domain class library. If the class is not found there, the action looks in
the Composite Applications class library.
Example 227
<Action id="ora-java">
<javaAction className="mypackage.myClass" defaultAction="ora-terminate">
<returnValue value="ABORT" ref="ora-terminate"/>
<returnValue value="RETRY" ref="ora-retry"/>
<returnValue value="MANUAL" ref="ora-human-intervention"/>
</javaAction>
</Action>
oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass Interface
oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass {
22-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
oracle.integration.platform.faultpolicy.IFaultRecoveryContext Interface
Example 2210 shows the Oracle Mediator service engine implementation of the
IFaultRecoveryContext interface.
Example 2210 IFaultRecoveryContext Interface Implementation
package oracle.tip.mediator.common.error.recovery;
public class MediatorRecoveryContext implements IFaultRecoveryContext{
...
}
You can use the methods shown in Example 2211 to retrieve additional
Mediator-specific data available with the MediatorRecoveryContext class:
Example 2211 Methods for Retrieving Data
public Fault getFault()
public CalloutMediatorMessage getMediatorMessage()
22-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
/**
* Adding header to the mediator message
* @return
* @throws MediatorCalloutException
*/
public void addHeader(Object header) throws MediatorCalloutException;
Composite: You can define one fault policy for all Mediator components in a
composite. You can specify this level in the following way:
<composite faultPolicy="ConnectionFaults"/>
Component: You can define a fault policy exclusively for a Mediator service
component. A component-level fault policy overrides the composite-level fault
policy. You can specify this level as shown in Example 2213.
Reference: You can define a fault policy for the references of a Mediator
component. You can specify this level as shown in Example 2214.
Note:
22-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Note:
For more information about how fault policies are processed, see Section 22.1.1.2,
"Actions."
22-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<xs:element ref="tns:replayScope"/>
<xs:element name="fileAction" type="tns:FileActionType"/>
<xs:element name="invokeWS" type="tns:InvokeWSType"/>
<xs:element name="enqueue" type="tns:EnqueueType"/>
<xs:element name="javaAction" type="tns:JavaActionType">
<xs:key name="UniqueReturnValue">
<xs:selector xpath="tns:returnValue"/>
<xs:field xpath="@value"/>
</xs:key>
</xs:element>
</xs:choice>
<xs:attribute name="id" type="tns:idType" use="required"/>
</xs:complexType>
<xs:element name="Actions">
<xs:annotation>
<xs:documentation>Fault Recvorey Actions</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="Action" type="tns:ActionType"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="JavaActionType">
<xs:annotation>
<xs:documentation>This action invokes java code
provided</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="returnValue" type="tns:ReturnValueType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="className" type="tns:idType" use="required"/>
<xs:attribute name="defaultAction" type="tns:idType" use="required"/>
<xs:attribute name="propertySet" type="tns:idType"/>
</xs:complexType>
<xs:complexType name="RetryType">
<xs:annotation>
<xs:documentation>This action attempts retry of activity
execution</xs:documentation>
</xs:annotation>
<xs:all>
<xs:element ref="tns:retryCount"/>
<xs:element ref="tns:retryInterval"/>
<xs:element ref="tns:exponentialBackoff" minOccurs="0"/>
<xs:element name="retryFailureAction"
type="tns:retryFailureActionType" minOccurs="0"/>
<xs:element name="retrySuccessAction"
type="tns:retrySuccessActionType" minOccurs="0"/>
</xs:all>
</xs:complexType>
<xs:complexType name="FileActionType">
<xs:annotation>
<xs:documentation>This action stores the rejected message on the file
system.</xs:documentation>
</xs:annotation>
<xs:all>
<xs:element ref="tns:location"/>
<xs:element ref="tns:fileName"/>
</xs:all>
</xs:complexType>
<xs:element name="location" type="xs:string">
<xs:annotation>
<xs:documentation>This value indicates the location of directory which
will be used to store the rejected messages.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="fileName" type="xs:string">
<xs:annotation>
<xs:documentation>This value indicates the filename or the pattern for
the filenames which will be used to store the rejected
messages.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:simpleType name="idType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="InvokeWSType">
<xs:annotation>
<xs:documentation>The Webservice to handle the rejcted
messages.</xs:documentation>
</xs:annotation>
<xs:attribute name="uri" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="EnqueueType">
<xs:annotation>
<xs:documentation>Rejected message will be enqueued to a queue as a
JMS message with the proper context and payload.</xs:documentation>
</xs:annotation>
<xs:attribute name="uri" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="ReturnValueType">
<xs:annotation>
<xs:documentation>Return value from java code can chain another action
using return values</xs:documentation>
</xs:annotation>
<xs:attribute name="value" type="tns:idType" use="required"/>
<xs:attribute name="ref" type="xs:string" use="required"/>
</xs:complexType>
<xs:element name="exponentialBackoff">
<xs:annotation>
<xs:documentation>Setting this will cause retry attempts to use
exponentialBackoff algorithm</xs:documentation>
</xs:annotation>
<xs:complexType/>
</xs:element>
<xs:element name="humanIntervention">
<xs:annotation>
<xs:documentation>This action causes the activity to
freeze</xs:documentation>
</xs:annotation>
<xs:complexType/>
</xs:element>
<xs:element name="replayScope">
<xs:annotation>
<xs:documentation>This action will replay the immidiate enclosing
scope</xs:documentation>
22-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</xs:annotation>
<xs:complexType/>
</xs:element>
<xs:element name="rethrowFault">
<xs:annotation>
<xs:documentation>This action will rethrow the
fault</xs:documentation>
</xs:annotation>
<xs:complexType/>
</xs:element>
<xs:element name="retryCount" type="xs:positiveInteger">
<xs:annotation>
<xs:documentation>This value is used to identify number of
retries</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="retryFailureActionType">
<xs:annotation>
<xs:documentation>This is the action to be chained if retry attempts
fail</xs:documentation>
</xs:annotation>
<xs:attribute name="ref" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="retrySuccessActionType">
<xs:annotation>
<xs:documentation>This is the action to be chained if retry attempts
is successful</xs:documentation>
</xs:annotation>
<xs:attribute name="ref" type="xs:string" use="required"/>
</xs:complexType>
<xs:element name="retryInterval" type="xs:unsignedLong">
<xs:annotation>
<xs:documentation>This is the delay in milliseconds of retry
attempts</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="abort">
<xs:annotation>
<xs:documentation>This action terminates the
process</xs:documentation>
</xs:annotation>
<xs:complexType/>
</xs:element>
<xs:element name="Properties">
<xs:annotation>
<xs:documentation>Properties that can be passes to a custom java
class</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="propertySet" type="tns:PropertySetType"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="PropertySetType">
<xs:sequence>
<xs:element name="property" type="tns:PropertyValueType"
maxOccurs="unbounded"/>
</xs:sequence>
22-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<xs:selector xpath="tns:Actions/tns:Action/tns:javaAction"/>
<xs:field xpath="@defaultAction"/>
</xs:keyref>
<xs:keyref name="JavaPropertySetRef" refer="tns:UniquePropertySetId">
<xs:selector xpath="tns:Actions/tns:Action/tns:javaAction"/>
<xs:field xpath="@property_set"/>
</xs:keyref>
</xs:element>
</xs:schema>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="referenceType">
<xs:annotation>
<xs:documentation>Bindings for a partner link. Overrides composite
level binding.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:annotation>
<xs:documentation>Specification at partner link name overrides
specification for a port type</xs:documentation>
</xs:annotation>
<xs:element name="name" type="tns:nameType" minOccurs="0"
maxOccurs="unbounded"/>
<xs:element name="portType" type="xs:QName" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="faultPolicy" type="tns:nameType" use="required"/>
</xs:complexType>
<xs:complexType name="componentType">
<xs:annotation>
<xs:documentation>Binding for a component </xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="name" type="tns:nameType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="faultPolicy" type="tns:nameType" use="required"/>
</xs:complexType>
<xs:complexType name="compositeType">
<xs:annotation>
<xs:documentation>Binding for the entire composite</xs:documentation>
</xs:annotation>
<xs:attribute name="faultPolicy" type="tns:nameType" use="required"/>
</xs:complexType>
</xs:schema>
22-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
23
Resequencing in Oracle Mediator
23
Group c
Group b
Group a
msg6(c), msg3(c)
Resequencing Order
All the groups are processed independently of each other and any error occurring in
ones group does not affect the processing of other groups.
Standard Resequencer
FIFO Resequencer
23-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Resequencing Order
Incremental
Start SequenceID Delta
Group1
Group2
...
Groupn
1,2,3,4,5,...
1,2,3,4,5,...
...
1,2,3,4,5,...n
1,5,10,15,...
1,5,10,15,...
...
1,5,10,15,...
Notes:
Resequencing Order
Incoming Messages
Sequenced Messages
msg03(2,c)
msg12(4,c),msg10(3,c),msg06(1,c),msg03(2,c)
msg06(1,c)
msg07(5,a)
msg10(3,a)
msg10(3,c)
msg02(7,a)
msg05(9,a)
msg12(4,c)
As shown in Table 233, the messages are sequenced based on their time of arrival and
the sequenceID is not used for sequencing.
When using the FIFO resequencer, use a single-threaded
inbound adapter to avoid unpredictable results. For example, when
you use the file/FTP adapter, the database adapter, or the AQ adapter
in front of a Mediator service component that is configured as a FIFO
resequencer, configure the adapter for single-threaded processing.
Otherwise, unpredictable results occur because the arrival time of
each message is calculated when the message arrives to the Mediator
service component instead when it arrives to the adapter service.
Note:
23-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Resequencing Order
When the best effort resequencer is configured to use a maximum number of rows, it
performs the following steps whenever new messages are available in the resequencer
database:
1.
2.
The resequencer locks and selects the number of messages equal to the value of
the maxRowsRetrieved parameter from the ordered messages above.
3.
The resequencer processes the selected messages one after another in its own
transaction in sequence.
Time Window
When the best effort resequencer is configured to use a time window instead of a
maximum number rows, the messages to select and process at one time are based on a
period you specify plus an optional buffer time. Each message belongs to a specific
time window, and messages that are part of one time window are processed
separately from messages belonging to a different time window.
In addition to the time window, you can specify a buffer time, which is an overlap
between two sequential time windows that allows messages that arrive a little late to
be associated with the first time window. By default, the buffer time is 10% of the time
window you specify.
When the best effort resequencer is configured to use a time window, groups are
processed in an iterative manner and messages are processed in the following steps:
1.
Resequencing Order
2.
The buffer is added to the time window, and processing begins after the buffer
time.
3.
The resequencer retrieves the messages that arrived within the time window, and
identifies the maximum sequence ID (typically a date and time stamp) from all the
messages.
4.
The resequencer retrieves any messages that arrive within the buffer time and that
have a sequence ID that is less than the maximum sequence ID identified above.
5.
The resequencer sorts all messages retrieved in the above steps in ascending order
of the sequence IDs and processes the messages.
Group C
Sequenced Messages
msg03(1,c)
msg12(4,c),msg10(3,c),msg06(2,c),msg03(1,c)
msg06(2,c)
msg10(3,c)
msg12(4,c)
23-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Group C
Message/Time
Sequenced Messages
msg01(04)/2:00:00
msg02(05)/2:00:20
msg03(01)/2:00:30
msg04(03)/2:00:50
msg05(07)/2:04:20
msg06(02)/2:04:45
msg07(13)/2:05:10
msg08(08)/2:05:40
msg09(06)/2:08:40
msg10(12)/2:09:20
msg11(10)/2:10:30
msg12(09)/2:10:40
msg13(14)/2:10:50
msg14(11)/2:13:00
Note:
If you choose component, the Resequence field under each operation no longer
appears and the Resequence Mode field appears under the Resequence Level
field so you can set the resequencing mode for the service component. By default,
the resequencing mode is set to off.
When you select a resequencing mode, the Resequence Options box appears
under the service component or operation, as shown in Figure 233. If the
Resequence Mode field for an operation is set to off, the Resequence Options box
disappears.
Figure 233 Mediator Editor with Resequence Options Section
23-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
The Resequence Options box appears and includes the options for the standard
resequencer, as shown in Figure 234.
Figure 234 Oracle Mediator with Resequence Mode set to Standard
3.
Note: You can either enter the XPath expressions directly in the
Group and ID fields or you can click Invoke Expression Builder to the
right of each field. This launches the Expression Builder, which
provides graphical assistance in creating field expressions and adding
functions.
Table 236
Field Name
Description
Group
component_
N
name-operation
ID
N/A
Timeout
Start
Increment
This default value means that the timeout never happens for a group by default.
On the Mediator Editor under either the Oracle Mediator component or the
operation you want to configure, select FIFO from the Resequence Mode
dropdown list.
The Resequence Options box appears and includes the option for the standard
resequencer, as shown in Figure 235.
3.
In the Group field, enter the XPath expression pointing to the field in the incoming
message on which grouping is performed.
Notes: If you are modifying the MPLAN file directly, the name of the
XML element is groupIDExpression. There is no default value, and
the field is not mandatory.
On the Mediator Editor under either the Mediator component or the operation you
want to configure, select Best Effort from the Resequence Mode dropdown list.
The Resequence Options box appears and includes the option for the standard
resequencer, as shown in Figure 236.
Figure 236 Oracle Mediator with Resequence Mode set to Best Effort
3.
Fill in the fields listed in Table 237 to configure the best effort resequencer.
Tip: You can specify either a maximum number of rows to process at
one time or a time window for the messages. You cannot specify both.
4.
If needed, you can change the percent of the time window that is added as a
buffer. You configure the buffer using the Oracle Enterprise Manager Fusion
Middleware Control.
For instructions, see Configuring Resequenced Messages in the Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
23-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 237
Field Name
Description
Group
component_
N
name-operation
ID
N/A
Datatype
Numeric
The data type of the sequence ID. The
ordering process is based on the data type.
Supported values are datetime and
numeric. If you are editing the MPLAN file
directly, the corresponding element is
named sequenceIDDataType.
Time Window
Max Rows
23-11
23-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
24
Understanding Message Exchange Patterns
of an Oracle Mediator
24
Notes:
Response
Request
No response.
Request Response
Request Callback
One-Way Mediator
Invoke
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Asynchronous
Request-Callback
Target reference or
Component
Client
Invoke Response/
Fault Fwd
Request-ResponseFault Target
Reference or
Component
24-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 242
one.way.returns.fault Property
If one.way.returns.fault Is...
Then...
Set to true:
. . .
<service name="Mediator1_2"
ui:wsdlLocation="ReadFile.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file
/LocalSandbox/Project1/ReadFile%2F#wsdl.interface(Read_
ptt)"/>
<binding.ws
port="http://xmlns.oracle.com/pcbpel/adapter/file
/LocalSandbox/Project1/ReadFile%2F#wsdl.endpoint
(Mediator1/Read_pt)">
<property name="one.way.returns.fault" type="xs:string"
many="false"
override="may">true</property>
</binding.ws>
</service>
. . .
Set to false:
. . .
<service name="Mediator1_2"
ui:wsdlLocation="ReadFile.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/
Local Sandbox/Project1/ReadFile%2F#wsdl.interface(Read_
ptt)"/>
<binding.ws
port="http://xmlns.oracle.com/pcbpel/adapter/file/LocalSan
dbox/Project1/ReadFile%2F#wsdl.endpoint(Mediator1/Read_
pt)">
<property name="one.way.returns.fault"
type="xs:string" many="false"
override="may">false</property>
</binding.ws>
</service>
. . .
Not set (the default case)
Go to the Property Inspector section in the lower right part of the editor.
3.
4.
5.
6.
Click OK.
Response
Request
Request Response
Request Callback
The response is sent back to the caller. The callback and fault are
forwarded to another target or event.
Request Response
Mediator
Invoke
Null Response
Invoke Reply to
Client
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Client
Invoke Callback Fwd
Null Response
Invoke Response/
Fault Fwd
Asynchronous
Request-Callback
Target reference or
Component
Request-ResponseFault Target
Reference or
Component
24-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Response
Request
Request Response
The response and fault are sent back to the caller. Any exception
in Mediator message processing may result in a fault.
Request Callback
The response and fault are sent back to the caller. Any exception
in Mediator message processing may result in a fault.
Request-Response
Fault Mediator
Invoke
Null Response
Exception as Fault
Client
Invoke Reply to
Client
Exception as Fault
Invoke Callback Fwd
Null Response
Exception as Fault
Invoke Response/
Fault to Client
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Asynchronous
Request-Callback
Target reference or
Component
Request-ResponseFault Target
Reference or
Component
Table 245
Request Response
Request Callback
The callback is sent back to the caller. The response and fault are
forwarded to another target or event.
Request-Callback
Mediator
Invoke
No Callback
Invoke Response to
Client as Callback
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Client
Invoke Callback to
Client
Invoke Response to
Client as Callback
Fault Fwd
Asynchronous
Request-Callback
Target reference or
Component
Request-ResponseFault Target
Reference or
Component
24-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 246
Response
Request
Request Response
Request Callback
The response and callback are sent back to the caller. The fault is
forwarded to another target or event.
Request-ReplyCallback Mediator
Invoke
Null Response
No Callback
Invoke
Reply to Client
No Callback
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Client
Invoke
Null
Reply Callback to
Client
Invoke
Reply and Callback
to Client Fault Fwd
Asynchronous
Request-Callback
Target reference or
Component
Request-ResponseFault Target
Reference or
Component
Table 247
Request Response
Request Callback
The response and callback are sent back to the caller. Any
exception in Mediator message processing may result in a fault.
The response, fault, and callback are sent back to the caller.
Request-Reply-Fault
Callback Mediator
Invoke
Null Reply
No Callback
Exception as Fault
Client
Invoke
Reply to Client
Exception as Fault
No Callback
Invoke
Null Reply
Callback to Client
Exception as Fault
Invoke
Reply, Fault
Callback to Client
One-Way Target
Reference or
Component
Request-Response
Target Reference or
Component
Asynchronous
Request-Callback
Target reference or
Component
Request-ResponseFault Target
Reference or
Component
24-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part IV
Part IV
This part describes how to use the business rules service component.
This part contains the following chapters:
25
25
Section 25.7, "Using Business Rules with Oracle ADF Business Components Fact
Types"
For more examples of using Oracle Business Rules, see Oracle Fusion Middleware User's
Guide for Oracle Business Rules.
A decision component can be used within a SOA composite and wired to a BPEL
component.
A decision component can be used within a SOA composite and used directly to
run business rules.
A decision component can be used with the dynamic routing capability of
Mediator.
For more information, see Chapter 20, "Creating Oracle Mediator Routing Rules."
A decision component can be used with the Advanced Routing Rules in Human
Workflow.
For more information, see Section 28.4, "Associating Human Tasks with BPEL
Processes."
25-1
Dynamic processing
Rules can perform intelligent routing within the business process based on service
level agreements or other guidelines. For example, if the customer requires a
response within one day, send a loan application to the QuickLoan loan agency
only. If the customer can wait longer, then route the request to three different loan
agencies.
Load balancing of tasks among users. When a task is assigned to a set of users
or a role, each user in that role acquires a set of tasks and acts on them in a
specified time. For new incoming tasks, policies may be applied to set
priorities on the task and put them in specific user queues. For example, a
specific loan agent is assigned a maximum of 10 loans at any time.
For more information about creating business rules in the Human Task editor of a
human task component, see Section 29.5.2, "How to Specify Advanced Task Routing
Using Business Rules."
25-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
25-3
Table 251 describes where you can find information about working with a dictionary
with Rules Designer.
Table 251
Rules Designer
Navigation Tab
Description
Facts
Functions
Globals
Bucketsets
Links
Decision Functions
Translations
For more information about the Rules Designer navigation areas and its descriptions,
see Oracle Fusion Middleware User's Guide for Oracle Business Rules.
25-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
To Start...
On Windows...
Oracle JDeveloper
Click JDev_Oracle_
$ORACLE_HOME/jdev/bin/jdev
Home\JDev\bin\jdev.exe or create a
shortcut
2.
On UNIX...
Create a Business Rule service component through one of the following methods:
As a service component in an existing SOA composite application:
a.
From the Component Palette, drag a Business Rule service component into
the SOA Composite Editor.
In a new application:
a.
From the Application Navigator, select File > New > Applications > SOA
Application.
Getting Started with Oracle Business Rules
25-5
In the Name your application page, enter an application name in the Name
field.
c.
In the Directory field, enter a directory path in which to create the SOA
composite application and project.
d.
Click Next.
e.
In the Name your project page, enter a unique project name in the Project
Name field. The project name must be unique across SOA composite
applications. This is because the uniqueness of a composite is determined by
its project name. For example, do not perform the actions described in
Table 253.
Table 253
Application1
Project1
Application2
Project1
Click Next.
g.
In the Configure SOA settings page, select Composite with Business Rule.
h.
Click Finish.
Each method causes the Create Business Rules dialog shown in Figure 254 to
appear.
Figure 254 Create Business Rules Dialog
25-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Provide the required details. For more information on providing Inputs and
Outputs and on using the Import Dictionary option with this dialog, see Oracle
Fusion Middleware User's Guide for Oracle Business Rules.
4.
Click OK.
1.
2.
Expand the BPEL process by double-clicking the process item. For example,
expand the BPEL process to view receiveInput and callbackClient as
shown in Figure 255.
25-7
3.
Select Business Rule from the SOA Components section of the Component Palette
and drag-and-drop a Business Rule into the position where the business rules are
needed. For example, drag-and-drop a Business Rule between receiveInput
and callbackClient, as shown in Figure 256.
4.
Oracle JDeveloper displays the business rule in the diagram. Double-click the
business rule component to display the Rule dialog box. The Rule dialog box
provides tabs, such as General, Dictionary, Correlation Sets, and so on, where you
can select an existing Oracle Business Rules dictionary or enter the name of a new
dictionary to create. Under the General tab, in the Name field enter a name for the
business rule. For example, enter GetCreditRating, as shown in Figure 257. If
25-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
you previously created a dictionary, under the Dictionary tab, in the Dictionary
field, select an existing dictionary.
Figure 257 Business Rule Added to Auto Loan BPEL Process
5.
In the Business Rule area for the Business Rule Dictionary, click the Create
Dictionary icon to display the Create Business Rules dialog.
6.
Specify a name for the Oracle Business Rules dictionary and a package name.
Specify the input and output data elements for the business rule. For example,
for a sample decision component named GetCreditRating, the input is a
rating request document. The output is generated when you run the business
rules, and for this example is a rating document. For example, in BPEL you
can create two new variables, RatingRequest and Rating that carry the
input and output data for the GetCreditRating rules.
Enter a name for the Oracle Business Rules dictionary. For example, enter
GetCreditRating, as shown in Figure 258.
25-9
In the Add Input Variable dialog box, expand the Process folder and select the
Variables folder immediately inside the Process.
3.
Right-click the Variables folder, and from the list select Create Variable... as
shown in Figure 259.
25-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In the Create Variable dialog box, in the Name field enter a value. For example,
enter RatingRequest as shown in Figure 2510.
Figure 2510
5.
In the Create Variable Type area click the Browse Elements icon. Use the
navigator to locate the schema element type for the input variable. For example,
select the ratingrequest type. Add any needed types using the Type Chooser.
6.
Click the Import Schema File icon to import the schema. For example, import
CreditRatingTypes.xsd. Also import any other required schema for your
application.
7.
8.
25-11
9.
In the Add Output Variable dialog select the scope by selecting the Variables
folder under Process.
3.
Right-click and from the dropdown list select Create Variable.... This displays the
Create Variable dialog.
4.
In the Create Variable dialog, in the Name field enter the output variable name.
For example enter Rating.
5.
In the Create Variable dialog, in the Type area select the Browse elements icon and
use the Type Chooser dialog to enter the type for the output variable. For example,
expand the CreditRatingTypes.xsd and select the element type rating.
6.
7.
8.
Figure 2511 Create Business Rules Dialog with Input and Output Variables
Set options and create decision service and business rules dictionary:
1. If you do not want to use the default service name, then select the Advanced tab
and in the Service Name field enter the service name. For example enter the
service name CreditRatingService.
25-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
In the Create Business Rules dialog, click OK. Oracle JDeveloper creates the
decision component and the dictionary and displays Rules Designer, as shown in
Figure 2512.
Figure 2512 Rules Designer Canvas Where You Work with Business Rules
For information on Rules Designer, see Oracle Fusion Middleware User's Guide for Oracle
Business Rules.
25.4.2 What Happens When You Add Business Rules to a BPEL Process
When you add business rules to a BPEL process, Oracle JDeveloper creates a decision
component to control and run the business rules using the Business Rule Service
Engine.
A decision component consists of the following:
Rules or Decision Tables that are evaluated using the Rules Engine. These are
defined using Rules Designer and stored in a business rules dictionary.
A description of the facts required for specific rules to be evaluated and the
decision function to call. Each ruleset that contains rules or Decision Tables is
exposed as a service with facts that are input and output, and the name of an
Oracle Business Rules decision function. The facts are exposed through XSD
definitions when you define the inputs and outputs for the business rule. A
decision function is stored in an Oracle Business Rules dictionary. For more
information, see Oracle Fusion Middleware User's Guide for Oracle Business Rules.
25-13
A web service wraps the input, output, and the call to the underlying Business
Rule service engine.
This web service lets business processes assert and retract facts as part of the
process. In some cases, all facts can be asserted from the business process as one
unit. In other cases, the business process can incrementally assert facts and
eventually consult the rule engine for inferences. Therefore, the service supports
both stateless and stateful interactions.
You can create a variety of such decision components.
For more information, see Oracle Fusion Middleware User's Guide for Oracle Business
Rules.
XML fact type model based on the input and output information of the Business
Rule.
A Ruleset that must be completed by adding rules or Decision Tables. With an
existing dictionary, you use the import option to specify a dictionary that may
already contain the rules or Decision Tables.
A service component with the input and output contract of the decision
component.
A decision component for the rule dictionary and wires to the BPEL process.
When you create inputs and outputs for a business rule, the
XML fact type that is created in the associated dictionary is named
based on the schema types for the inputs and outputs that you supply
in the Create Business Rules dialog. When you specify schema type
for the input and the output, Rules Designer defines fact types and
aliases associated with your type selections for input and output. If
you only use a single type for both the input and the output, then the
decision component creates a single fact that is shown in the Rules
Designer Facts tab. This fact represents the fact type you specified and
uses an alias name that is a concatenation of both the input variable
name and the output variable name. In Rules Designer you can
rename this alias if you do not like the default naming scheme for the
fact type.
Note:
25.4.4 What You May Need to Know About Invoking Business Rules in a BPEL Process
When you add business rules to a BPEL process Oracle JDeveloper creates a decision
Service that supports calling Oracle Business Rules with the inputs you supply, and
returning the outputs with results. The decision service provides access to Oracle
Business Rules Engine at runtime as a web service. For more information, see Oracle
Fusion Middleware User's Guide for Oracle Business Rules.
25-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
25.4.5 What You May Need to Know About Decision Component Stateful Operation
A decision component running in a business rules service engine supports either
stateful or stateless operation. The Reset Session checkbox in the Create Business
Rules dialog provides support for these two modes of operation.
By default the Reset Session checkbox is selected which indicates stateless operation.
Stateless operation means that, at runtime, the rule session is released after the
decision component invocation.
When Reset Session is unselected, the underlying Oracle Business Rules object is kept
in the memory of the business rules service engine at a separate location (so that it is
not given back to the Rule Session Pool when the operation is finished). A subsequent
use of the decision component re-uses the cached RuleSession object, with all its state
information from the callFunctionStateful invocation, and then releases it back
to the Rule Session pool after the callFunctionStateless operation is finished.
Thus, when Reset Session is unselected the rule session is saved for a subsequent
request and a sequence of decision service invocations from the same BPEL process
should always end with a stateless invocation.
In the Application Navigator, if the SOA composite editor is not showing, then in
your project expand SOA Content folder and double-click composite.xml to
launch the SOA composite editor.
25-15
3.
From the Component Palette, drag-and-drop a Business Rule from the Service
Components area of the SOA menu to the Components lane of the SOA composite
editor, as shown in Figure 2513.
4.
When you drag-and-drop a Business Rule, Oracle JDeveloper displays the Create
Business Rules dialog as shown in Figure 2514.
Figure 2514 Adding Business Rules to a SOA Composite and Creating a Dictionary
25-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
In the Type Chooser dialog, add inputs. If the schema is available in the Project
Schema Files, skip to step 9 to select the appropriate schema.
3.
Click the Import Schema File... icon. This brings up the Import Schema File
dialog.
4.
In the Import Schema File dialog click Browse Resources to choose the XML
schema elements for the input. This displays the SOA Resource Browser dialog.
5.
In the SOA Resource Browser dialog, navigate to find the schema for your
business rules input. For example, select the order.xsd schema file, and click
OK.
6.
In the Import Schema File dialog select Copy to Project, as shown in Figure 2515.
Figure 2515
7.
8.
9.
Use the Type Chooser dialog navigator to locate and select the input from the
schema and click OK. For example, select the CustomerOrder element as the
input.
In the Type Chooser dialog, in a manner similar to adding an input add the
output. For example, add OrderApproval from the order.xsd and click OK.
3.
This displays the Create Business Rules dialog, as shown in Figure 2516.
25-17
Figure 2516 Create Business Rules Dialog with Input and Output
Set options and create decision service and business rules dictionary:
1. In the Create Business Rules dialog, select Expose as Composite Service.
2.
If you do not want to use the default service name, then select the Advanced tab
and in the Service Name field enter the service name.
3.
In the Create Business Rules dialog, click OK. This creates the Business Rule
component, also called a decision component, and Oracle JDeveloper shows the
Business Rule component in the canvas workspace as shown in Figure 2517.
25-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Figure 2518
For information on Rules Designer, see Oracle Fusion Middleware User's Guide for Oracle
Business Rules.
25.5.2 How to Select and Modify a Decision Function in a Business Rule Component
You can specify one or more decision functions as inputs for calling Oracle Business
Rules as a component in a composite application. For example, you can specify a
particular decision function as the input when multiple decision functions are
available in an Oracle Business Rules dictionary.
To specify a decision function in a composite application:
1. Add a decision function to the Oracle Business Rules dictionary. For more
information, see Oracle Fusion Middleware User's Guide for Oracle Business Rules.
2.
3.
25-19
4.
Select the decision function port of interest. For example, select the port for DF_2
as shown in Figure 2520.
5.
When you select the port, Oracle JDeveloper shows the port information in the
Property Inspector.
6.
When you double-click the port, Oracle JDeveloper displays the Update Interface
dialog for the port as shown in Figure 2521.
25-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2521 Update Interface Dialog for a Decision Function in a Business Rule Decision Port
25.6.1 What You May Need to Know About Testing a Standalone Decision Service
Component
To test a standalone decision service component by using Oracle Enterprise Manager
Fusion Middleware Control, you must provide the name of the decision service as the
value of the payload name field in the Test Web Service page as shown in Figure 2522.
25-21
'name' in payload should be the decision service name as can be seen in the sample
.decs file in Figure 2523.
Figure 2523 Sample .decs File
Without the decision service name, it would not be possible to invoke the standalone
decision service with just the payload and endpoint details.
25-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using Business Rules with Oracle ADF Business Components Fact Types
25.7 Using Business Rules with Oracle ADF Business Components Fact
Types
You can use Oracle ADF Business Components Fact Types and ActionTypes from
the Business Rules Service Engine. Typically, a decision component can be used within
a SOA composite and wired to a BPEL component and the Oracle Business Rules rules
act on XML types. The Business Rules Service Engine is called as a web service with a
payload containing instances of the XML schema types, and the service engine returns
a response similarly.
It is also possible to use Oracle ADF Business Components Fact Types from a decision
component. Instead of loading the Oracle ADF Business Components Fact Type
instances and passing them to the Business Rules Service Engine, you call the Business
Rules Service Engine with configuration information describing how the Oracle ADF
Business Components view object rows can be loaded. Special Oracle Business Rules
decision functions in the DecisionPointDictionary and classes in the Oracle
Business Rules SDK Decision Point API then load the rows and assert Oracle ADF
Business Components fact type instances. When working with Oracle ADF Business
Components Fact Types, you write rules that use user-defined Java classes which
inherit from ActionType to affect action, such as modifying the Oracle ADF Business
Components fact type instances such that they update their underlying database rows.
A decision component requires an XML document as input. The Oracle Business Rules
Decision Point dictionary provides an XML Fact Type called
SimpleDecisionPointInput that serves as this input. The primary key(s) of Oracle
ADF Business Components are passed to the business rule service component. The
business rule service component invokes a user-defined decision function which it
invokes to load the Oracle ADF Business Components view object instances, asserts
them in the rules engine, and then marshals the results in the following order:
1.
2.
User-defined rulesets: The user ruleset matches these facts and should assert facts
that extend ActionType to update the business component.
3.
For specific instructions on how to use Oracle ADF Business Components Fact Types
and ActionTypes from the Business Rules Service Engine, see the source code for
Oracle Business Rules-specific samples available with the Oracle SOA Suite samples.
25-23
Using Business Rules with Oracle ADF Business Components Fact Types
25-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
26
Using Declarative Components and Task
Flows
26
This chapter describes how to use different Oracle Business Rules declarative
components and task flows to develop high-performance, interactive, and multitiered
applications that are also easy to maintain. It describes how to use the Oracle Business
Rules Editor declarative component and the Oracle Business Rules Dictionary Editor
declarative component and task flow. It also describes how to localize the ADF-based
web application.
This chapter includes the following sections:
Section 26.2, "Using the Oracle Business Rules Editor Declarative Component"
Section 26.3, "Using the Oracle Business Rules Dictionary Editor Declarative
Component"
Section 26.4, "Using the Oracle Business Rules Dictionary Editor Task Flow"
call another task flow without invoking any particular page. This facilitates reuse
because business logic can be invoked independently of the page being displayed.
Using the Rules Editor, you can edit rules and decision tables that are part of a single
ruleset. You are required to specify a RuleSetModel object, which is a wrapper
around the Rules SDK ruleset object, as a parameter to the Rules Editor component. If
multiple rulesets are required to be modified, multiple Rules Editor components must
be instantiated, one for each ruleset.
The Rules Editor component performs the following functions:
26-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Provides a Condition Browser pop-up to display the left or right value options, as
shown in Figure 265.
Provides a Date Browser for selecting date types, as shown in Figure 266.
Provides the Properties browser for editing properties of a rule action, as shown in
Figure 269.
26-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2610
Provides Advanced Mode features for working with patterns and advanced
actions, as shown in Figure 2611.
Once all the edits are done, the component user is responsible
for saving the ruleset.
Note:
26.2.2 How to Create and Run a Sample Application by Using the Rules Editor
Component
This section lists the steps for creating and running a sample application by using the
Rules Editor component.
The prerequisite for using the Rules Editor component to create ADF-based web
applications is having a running installation of Oracle SOA Suite and Oracle
JDeveloper on your computer.
To create a sample application by using the Rules Editor:
The first task is to create a sample application.
The steps are:
1.
2.
From the File menu, select New and then Generic Application to create an
application.
26-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Enter a name for the application in the Application Name field, for example,
useRulesDCApp, and click Next as shown in Figure 2613.
Figure 2613
4.
Enter useRulesDC in the Project Name field and ensure that ADF Faces is
selected in the Project Technologies tab, as shown in Figure 2614.
Figure 2614
Creating a Project
5.
6.
b.
Click Add and select ADF Faces Components from the Extension list in the
Choose Tag Libraries dialog box, and click OK as shown in Figure 2615.
c.
Click Libraries and Classpath from the left panel and click the Add Library
button to display the Add Library dialog box.
d.
Click Oracle Rules and Oracle Rules Editor Component from the Extension
list, and then click OK as shown in Figure 2616.
26-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This adds the Rules SDK and the Rules Editor Component tag libraries to the
project.
e.
7.
Select Save All from the Oracle JDeveloper File menu to save the project.
You have to ensure that all the required tag libraries are added:
1.
2.
Click JSP Tag Libraries from the left panel and check if all the tag libraries are
added, as shown in Figure 2617.
Figure 2617
2.
From the File menu, select New to display the New Gallery dialog box.
3.
In the New Gallery dialog box, select Java under General from the Categories
panel.
4.
Ensure that Java Class under Items is selected and click OK to display the Create
Java Class dialog box.
5.
Enter the name of the Java class, for example SomeBean.java, and click OK to
create the Java class in your project, as shown in Figure 2618.
6.
java.io.File;
java.io.FileNotFoundException;
java.io.FileReader;
java.io.FileWriter;
java.io.IOException;
java.io.Reader;
import java.io.Writer;
import java.util.ArrayList;
import java.util.List;
import
import
import
import
import
import
oracle.bpel.rulesdc.model.impl.RuleSetModel;
oracle.rules.sdk2.dictionary.RuleDictionary;
oracle.rules.sdk2.exception.SDKException;
oracle.rules.sdk2.exception.SDKWarning;
oracle.rules.sdk2.ruleset.RuleSet;
oracle.rules.sdk2.ruleset.RuleSetTable;
26-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
try {
reader =
new FileReader(new File(RULES_FILE));
} catch (FileNotFoundException e) {
//LOG.severe(e);
System.err.println(e);
}
RuleDictionary dict = null;
try {
dict = RuleDictionary.readDictionary(reader, null);
} catch (SDKException e) {
System.err.println(e);
} catch (FileNotFoundException e) {
System.err.println(e);
} catch (IOException e) {
System.err.println(e);
}
if (reader != null) {
try {
reader.close();
} catch (IOException ioe) {
}
}
//get the ruleSetTable from the RuleDictionary object
RuleSetTable ruleSetTable = dict.getRuleSetTable();
//get the first ruleSet from the ruleSetTable
RuleSet ruleSet = ruleSetTable.get(0);
//create a RuleSetModel object and pass this to the rulesDC
ruleSetModel = new RuleSetModel(ruleSet) ;
return ruleSetModel;
}
//refer to Rules SDK documentation for saving a dictionary also
//because this code does not take care of saving linked dictionaries
public static boolean saveDictionary(RuleDictionary dict,
String ruleFileName) {
Writer writer = null;
try {
writer = new FileWriter(new File(ruleFileName));
dict.writeDictionary(writer);
} catch (SDKException e) {
System.err.println(e);
return false;
} catch (FileNotFoundException e) {
System.err.println(e);
return false;
} catch (IOException e) {
System.err.println(e);
return false;
} finally {
if (writer != null) {
try {
writer.close();
} catch (IOException ioe) {
26-11
return false;
}
}
}
return true;
}
public static void updateDictionary(RuleDictionary dict) {
if (dict == null)
return;
List<SDKWarning> warnings = new ArrayList<SDKWarning>();
try {
dict.update(warnings);
if (!warnings.isEmpty()) {
for (int i = 0; i < warnings.size(); i++)
System.out.println("warnings: " +
warnings.get(i).getLocalizedMessage());
}
} catch (SDKException sdkEx) {
sdkEx.printStackTrace();
}
}
//You can call this method from your "Save" button
public void saveDictionary() {
RuleDictionary dict = this.getRuleSetModel().getRuleSet().getDictionary();
if (dict != null) {
//update the dictionary before saving it
updateDictionary(dict);
saveDictionary(dict, RULES_FILE);
}
}
//call the validation method on the ruleSetModel to update the Validation Panel
public void validate() {
if (this.ruleSetModel == null)
return;
this.ruleSetModel.validate();
7.
Open the faces-config.xml file in Overview mode and click the + button
under Managed Beans to display the Create Managed Bean dialog box.
8.
26-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2619
2.
From the File menu, select New to display the New Gallery dialog box.
3.
In the New Gallery dialog box, select JSF under Web Tier from the Categories
panel.
4.
Select JSF Page under Items and click OK to display the Create JSF Page dialog
box.
5.
In the Create JSF Page dialog box, enter useRulesDC.jspx as the file name, as
shown in Figure 2620.
Figure 2620
26-13
This is because you have added the Rules Editor Component tag library when
creating the sample application.
6.
Select RulesCompLib to view the Rulesdc tag. You can drag and drop the
Rulesdc tag into the .jspx file. You can also add the Rulesdc tag in the .jspx
file manually as shown:
<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:rdc="http://xmlns.oracle.com/bpel/rules/editor">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document title="Sample Rules Editor App" id="d1">
<af:form id="f1">
<af:panelStretchLayout id="psl1" inlineStyle="margin:15px;"
partialTriggers="cb1 cb3">
<f:facet name="center">
<rdc:rulesdc rulesetModel="#{someBean.ruleSetModel}"
viewOnly="false" discloseRules="true"
genericAction="true" genericPattern="true"
dtColumnPageSize="6" id="r1" dateStyle="yyyy-MM-dd"
timeStyle="HH-mm-ss"></rdc:rulesdc>
</f:facet>
<f:facet name="top">
<af:panelGroupLayout id="pgl2" layout="horizontal">
<af:commandButton text="Save Dictionary"
action="#{someBean.saveDictionary}" id="cb1"/>
<af:spacer width="10" height="10" id="s5"/>
<af:commandButton text="Validate" id="cb3"
action="#{someBean.validate}"
partialSubmit="true"/>
</af:panelGroupLayout>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>
</jsp:root>
26-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Add the following lines to refer to the oracle.rules shared library as shown in
Figure 2622.
<library-ref>
<library-name>oracle.rules</library-name>
</library-ref>
Figure 2622
3.
In Oracle JDeveloper,
a.
From the File menu, select New to display the New Gallery dialog box.
b.
In the New Gallery dialog box, select Deployment Descriptors under General
from the Categories panel.
c.
d.
e.
f.
26-15
g.
4.
b.
c.
d.
5.
26-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
a.
In the Weblogic console, select Deployments and click Install to display the
Install Application Assistant page.
b.
c.
Figure 2625
2.
Select Run.
This starts the sample application on a web browser, as shown in Figure 2627.
26-17
2.
3.
4.
If this is not displayed, click Install and select the following file:
JDEV_INSTALL/jdeveloper/soa/modules/oracle.soa.rules_editor_dc.webapp_
11.1.1/oracle.soa.rules_editor_dc.webapp.war
5.
6.
Right-click the project name in the Application Navigator and select Project
Properties.
7.
Select Libraries and Classpath from the left panel and click Add Library.
8.
In the Add Library dialog box, select Oracle Rules Editor Component and click
OK, as shown in Figure 2628.
26-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2628
This step enables you to refer to these libraries, but does not deploy these libraries
by default. Therefore, the JARs are not included in your project WAR file.
9.
In the project that has to be deployed (where you create the EAR file):
a.
b.
c.
For more information about creating an EAR file, see "How to Create an EAR File for
Deployment" in Oracle Fusion Middleware Java EE Developer's Guide for Oracle
Application Development Framework.
26.2.4 What You May Need to Know About the Custom Permissions for the Rules Editor
Component
For role-based authorization, Rules DC implements custom JAAS permissions
(extending the
oracle.adf.share.security.authorization.ADFPermission class to
ensure that the permission can be used by ADF security).
If a Rules Editor application supports ADF security, which means there is support for
role-based authentication and authorization, then security is enforced by
implementing custom JAAS permissions (by extending the
oracle.adf.share.security.authorization.ADFPermission class to
ensure that the permission can be used by ADF security). You have to create ADF
security policies by granting the following permissions to the user roles based on your
application requirement:
26-19
For example, to grant the delete rule permission to a role, specify the following code in
the jazn-data.xml file of the application:
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>role2</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.rules.adf.permission.DeleteRulePermission</class>
<name>DeleteRulePermission</name>
<actions>access</actions>
</permission>
</permissions>
</grant>
26.2.5 What You May Need to Know About the Supported Tags of the Rules Editor
Component
This section lists the tags and attributes that are supported by the Rules Editor
component.
Table 261 lists the supported facets.
26-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 261
Name
Description
Comments
patternDisplay
Deprecated for
release
11.1.1.7. Will
be removed in
12c.
actionDisplay
Supports
EL?
Description
Name
Type
dateStyle
java.lang.
String
no
decimalSeparator
java.lang.
Character
no
Based on
locale
yes
disableRuleSetName
java.lang.
Boolean
no
false
yes
discloseRules
java.lang.
Boolean
no
false
yes
26-21
Supports
EL?
Description
displayRuleSetEffDate java.lang.
Boolean
no
true
yes
displayRuleSetName
java.lang.
Boolean
no
true
yes
dtAddActionMenuDDC
java.lang.String no
yes
dtActionNameCustomize oracle.bpel.rulesdc no
r
.model.interfaces.A
ctionNameCustomizer
yes
Name
Type
26-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Supports
EL?
Description
Name
Type
dtActionParamCellDDC
java.lang.String no
yes
dtEditActionDDC
java.lang.String no
yes
dtColumnPageSize
java.lang.
Integer
yes
no
26-23
Supports
EL?
Description
no
16
yes
Number of rows to be
displayed at a time in
the decision table. A
scroll bar is displayed
if the number of rows
increases over the
specified height.
Deprecated for
release 11.1.1.7. Will
be removed in 12c.
oracle.bpel
.rulesdc.mo
del.decisio
ntable.impl
.DecisionTa
blePrefsImp
l
yes
Used to specify
decision table
preferences.
Consumers can
extend the following
default
implementation and
override only the
required preferences:
Name
Type
dtHeight
java.lang.
Integer
dtPreferences
oracle.bpel.rulesdc no
.model.decisiontabl
e.interfaces.Decisi
onTablePrefs
oracle.bpel.rulesdc
.model.decisiontabl
e.impl.DecisionTabl
ePrefsImpl
genericAction
java.lang.
Boolean
no
true
26-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
yes
Type
Default
Required Value
Supports
EL?
Description
genericDTAddActionMen java.lang.Boolea no
u
n
true
yes
genericDTActionParam
java.lang.Boolea no
n
true
yes
If true, generic UI is
displayed in the
action parameter cell
of the decision table.
If false, specify the
action parameter cell
UI using the
dtActionParamCel
lDDC attribute.
Deprecated for
release 11.1.1.7. Will
be removed in 12c.
Use dtPreferences
attribute and override
isGenericDTActio
nParam().
genericDTEditAction
java.lang.Boolea no
n
true
yes
If true, generic
action UI is displayed
in the action editor
browser that shows
up when an action
row is edited in the
decision table. If
false specify the
edit action UI using
the
dtEditActionDDC
attribute. Deprecated
for release 11.1.1.7.
Will be removed in
12c. Use
dtPreferences
attribute and override
isGenericDTEditA
ction().
26-25
Supports
EL?
Description
java.lang.
Boolean
no
true
yes
groupingSeparator
java.lang.
Character
no
Based on
Locale
yes
Specifies the
grouping separators.
This is used in
Number Formatting.
If specified, this
attribute overrides
the grouping
separator based on
locale.
ifThenPreferences
oracle.bpel.rulesdc no
.model.interfaces.I
fThenPreferences
oracle.bpel
.rulesdc.mo
del.impl.If
ThenPrefere
ncesImpl
yes
Used to specify
IF/THEN UI
preferences.
Consumers can
extend the following
default
implementation and
override only the
required preferences:
Name
Type
genericPattern
oracle.bpel.rulesdc
.model.impl.IfThenP
referencesImpl
locale
java.util.
Locale
no
Locale.get yes
Default()
resourceManager
oracle.bpel.rulessh no
areddc.model.interf
aces.ResourceManage
rInterface
yes
26-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Supports
EL?
Description
java.lang.
String
no
yes
rulesetModel
oracle.bpel.
rulesdc.model.
interfaces.
RuleSetInterface
yes
Only EL
rulesPageSize
java.lang.
Integer
no
yes
showDTButtons
java.lang.
Boolean
no
true
yes
showValidationPanel
java.lang.
Boolean
no
true
yes
Displays the
validation panel by
default. You can
choose to hide this by
setting this to false.
Name
Type
ruleModel
oracle.
bpel.rulesd
c.model.
impl.
RuleModel
26-27
Supports
EL?
Description
java.lang.
String
no
oracle.
bpel.rulesd
c.model.
impl.
SimpleTestM
odel
yes
timeStyle
java.lang.
String
no
timezone
java.util.
TimeZone
no
TimeZone.
getDefault
()
yes
viewOnly
java.lang.
Boolean
no
true
yes
If true, in the
viewOnly mode, you
can view the existing
rules in the ruleset. If
false, which is edit
mode, you can add
new rules and edit
existing rules.
vldnPanelCollapsed
java.lang.Boolea no
n
false
yes
Used to specify if
validation panel
should be collapsed
by default.
vldnTabTitle
java.lang.String no
yes
Name
Type
simpleTestModel
Note:
The Rules Dictionary Editor task flow uses the Rules Dictionary Editor Component to
create applications. Typically, you should either use the Rules Dictionary Editor
component or the Rules Dictionary Editor task flow, but not both. For more
information on the Rules Dictionary Editor task flow, see Section 26.4, "Using the
Oracle Business Rules Dictionary Editor Task Flow."
The Rules Dictionary Editor component performs the following:
Edits globals or variables that have the final attribute set to true by using the
Globals Editor, as shown in Figure 2629.
The Globals Editor enables you to create, delete, edit the name, description, value,
change bucketset, change type and make global final. It supports validation of
globals.
26-29
Bucketset Editor enables you to perform CRUD (create, read, update, and delete)
operations on bucketsets and buckets inside a bucketset. It also supports
validation of bucketsets.
The Rules Dictionary Editor enables you to edit only rules inside a selected ruleset.
It does not allow creation or deletion of rulesets.
26-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
26.3.2 How to Create and Run a Sample Application by Using the Rules Dictionary
Editor Component
This section lists the steps for creating and running a sample application by using the
Rules Dictionary Editor component.
The prerequisite for using the Rules Dictionary Editor component to create ADF-based
web applications is having a running installation of Oracle SOA Suite and Oracle
JDeveloper on your computer.
To create a sample application by using the Rules Dictionary Editor:
The first task is to create a sample application.
The steps are:
1.
2.
From the File menu, select New and then Generic Application to create an
application.
3.
Enter a name for the application in the Application Name field, for example,
useRuleDictDCApp, and click Next as shown in Figure 2632.
Figure 2632
4.
Enter useRuleDictDC in the Project Name field and ensure that ADF Faces is
selected in the Project Technologies tab, as shown in Figure 2633.
Click Finish to create the project.
26-31
5.
b.
Click Add and select ADF Faces Components from the Extension list in the
Choose Tag Libraries dialog box, and then click OK as shown in Figure 2634.
c.
Click Libraries and Classpath from the left panel and click the Add Library
button to display the Add Library dialog box.
26-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
d.
Click Oracle Rules and Oracle Rules Dictionary Component from the
Extension list and then click OK as shown in Figure 2635.
Figure 2635
This adds the Rules SDK and the Rules Dictionary Editor tag libraries to the
project.
e.
6.
Select Save All from the Oracle JDeveloper File menu to save the project.
You have to ensure that all the required tag libraries are added:
1.
2.
Click JSP Tag Libraries in the left panel and check if all the tag libraries are added,
as shown in Figure 2636.
26-33
Figure 2636 Checking the Required Tag Libraries for Rules Dictionary Editor
2.
From the File menu, select New to display the New Gallery dialog box.
3.
In the New Gallery dialog box, select Java under General from the Categories
panel.
4.
Ensure that Java Class under Items is selected and click OK to display the Create
Java Class dialog box.
5.
Enter the name of the Java class, for example SomeBean.java, and click OK to
create the Java class in your project, as shown in Figure 2637.
26-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2637
6.
java.io.File;
java.io.FileNotFoundException;
java.io.FileReader;
java.io.FileWriter;
java.io.IOException;
java.io.Reader;
import java.io.Writer;
import java.util.ArrayList;
import java.util.List;
import oracle.bpel.ruledictionarydc.model.impl.RuleDictionaryModel;
import
import
import
import
oracle.rules.sdk2.dictionary.DictionaryFinder;
oracle.rules.sdk2.dictionary.RuleDictionary;
oracle.rules.sdk2.exception.SDKException;
oracle.rules.sdk2.exception.SDKWarning;
26-35
26-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
try {
writer = new FileWriter(new File(ruleFileName));
dict.writeDictionary(writer);
} catch (SDKException e) {
System.err.println(e);
return false;
} catch (FileNotFoundException e) {
System.err.println(e);
return false;
} catch (IOException e) {
System.err.println(e);
return false;
} finally {
if (writer != null) {
try {
writer.close();
} catch (IOException ioe) {
return false;
}
}
}
return true;
}
public static void updateDictionary(RuleDictionary dict) {
if (dict == null)
return;
List<SDKWarning> warnings = new ArrayList<SDKWarning>();
try {
dict.update(warnings);
for (SDKWarning warning : warnings)
System.out.println("warnings: " +
warning.getLocalizedMessage());
} catch (SDKException sdkEx) {
sdkEx.printStackTrace();
}
}
//You can call this method from your "Save" button
public void saveDictionary() {
RuleDictionary dict = this.getRuleDictModel().getRuleDictionary();
if (dict != null) {
if (dict.isModified())
updateDictionary(dict);
if (!dict.isTransactionInProgress())
saveDictionary(dict, RULES_FILE1);
}
}
//call validation method on the ruleDictModel to update Validation Panel
public void validate() {
if (this.ruleDictModel == null)
return;
26-37
this.ruleDictModel.validate();
}
}
7.
Open the faces-config.xml file in Overview mode and click the + button
under Managed Beans to display the Create Managed Bean dialog box.
8.
2.
From the File menu, select New to display the New Gallery dialog box.
3.
In the New Gallery dialog box, select JSF under Web Tier from the Categories
panel.
4.
Select JSF Page under Items and click OK to display the Create JSF Page dialog
box.
5.
In the Create JSF Page dialog box, enter useRuleDictDC.jspx as the file name,
as shown in Figure 2639.
26-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2639
This is because you have added Rules Dictionary Component when creating the
sample application.
6.
26-39
<rddc:ruleDictionaryDC ruleDictModel="#{someBean.ruleDictModel}"
dtColumnPageSize="6" id="rddc1"
viewOnly="false" dateStyle="yyyy-MM-dd"
timeStyle="HH-mm-ss"
discloseRules="true"
showValidationPanel="true"/>
</f:facet>
<f:facet name="top">
<af:panelGroupLayout id="pgl1" layout="horizontal">
<af:commandButton text="Save Dict" id="cb2"
action="#{someBean.saveDictionary}"/>
<af:spacer width="10" height="10" id="s1"/>
<af:commandButton text="Validate" id="cb3"
action="#{someBean.validate}"/>
</af:panelGroupLayout>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>
</jsp:root>
2.
Add the following lines to refer to the oracle.rules shared library, as shown in
Figure 2641.
<library-ref>
<library-name>oracle.rules</library-name>
</library-ref>
26-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2641
3.
In Oracle JDeveloper,
a.
From the File menu, select New to display the New Gallery dialog box.
b.
In the New Gallery dialog box, select Deployment Descriptors under General
from the Categories panel.
c.
d.
e.
Figure 2642
4.
26-41
5.
b.
c.
Select <JDEV_INSTALL>/jdeveloper/soa/modules/oracle.rules_
11.1.1/rules.jar and click Finish.as shown in Figure 2643.
6.
In the Weblogic console, select Deployments and click Install to display the
Install Application Assistant page.
b.
Select <JDEV_INSTALL>/jdeveloper/soa/modules/oracle.soa.rules_dict_
dc.webapp_11.1.1/oracle.soa.rules_dict_dc.webapp.war and click Next.
c.
26-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
26-43
2.
3.
4.
5.
Right-click the project name in the Application Navigator and select Project
Properties.
6.
Select Libraries and Classpath from the left panel and click Add Library.
7.
In the Add Library dialog box, select Oracle Rules Dictionary Component and
click OK as shown in Figure 2647.
This step enables you to refer to these libraries, but does not deploy these libraries
by default. Therefore, the JAR files are not included in your project war file.
8.
In the project that has to be deployed (where you create the EAR file):
a.
b.
26-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<library-ref>
<library-name>oracle.soa.rules_dict_dc.webapp</library-name>
</library-ref>
c.
26.3.4 What You May Need to Know About the Supported Attributes of the Rules
Dictionary Editor Component
This section lists the attributes that are supported by the Rules Dictionary Editor
component.
Table 263 lists the supported attributes.
Table 263
Name
Type
Default
Required Value
Support
s EL?
dateStyle
java.lang.String
no
Gets it from
the locale
yes
decimalSeparator
java.lang.
Character
no
Based on
Locale
yes
yes
Introduced but
deprecated in release
11.1.1.7. Will be
removed in 12C. Use
dfEditorPrefs and
override
getDfActionListen
er().
yes
dfActionListener
dfEditorPrefs
no
oracle.bpel.ruledict no
ionarydc.model.inter
faces.DFEditorPrefer
ences
oracle.bpel
.ruledictio
narydc.mode
l.impl.DFEd
itorPrefere
ncesImpl
Description
oracle.bpel.ruledict
ionarydc.model.impl.
DFEditorPreferencesI
mpl
dfListener
oracle.bpel.decision no
funceditordc.listene
r.DecisionFuncListen
er
yes
Introduced but
deprecated in release
11.1.1.7. Will be
removed in 12C. Use
dfEditorPrefs and
override
getDfListener().
26-45
Type
dfServiceNameCustom
izer
Default
Required Value
Support
s EL?
no
yes
Introduced but
deprecated in 11.1.1.7.
Will be removed in 12C.
Use dfEditorPrefs
and override
getDfServiceNameC
ustomizer().
Description
disableDFName
java.lang.
Boolean
no
false
yes
disableInputOps
java.lang.
Boolean
no
false
yes
disableOutputOps
java.lang.
Boolean
no
false
yes
disableRuleSetName
java.lang.
Boolean
no
false
yes
26-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Support
s EL?
java.lang.
Boolean
no
false
yes
displayAddDF
java.lang.
Boolean
no
true
yes
displayDeleteDF
java.lang.
Boolean
no
true
yes
displayRuleSetName
java.lang.
Boolean
no
true
yes
displayWSCheck
java.lang.
Boolean
no
true
yes
Name
Type
discloseRules
Description
26-47
Support
s EL?
java.lang.
Boolean
no
true
yes
dtColumnPageSize
java.lang.
Integer
no
yes
Number of columns to
be displayed at a time
in the decision table.
This works only when
rules are columnar.
Deprecated for release
11.1.1.7. Will be
removed in 12c.
dtHeight
java.lang.
Integer
no
16
yes
Number of rows to be
displayed at a time in
the decision table. A
scroll bar is displayed if
the number of rows
increases over the
specified height.
Deprecated for release
11.1.1.7. Will be
removed in 12c.
groupingSeparator
java.lang.
Character
no
Based on
Locale
yes
locale
java.util.Locale
no
Locale.
get
Default()
yes
resourceManager
oracle.bpel.rulessha no
reddc.model.interfac
es.ResourceManagerIn
terface
yes
Name
Type
displayWSName
26-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Name
Type
ruleDictModel
oracle.bpel.
yes
ruledictionarydc.
model.interfaces.Rul
eDictionaryInterface
rulesEditorPrefs
oracle.bpel.ruledict no
ionarydc.model.inter
faces.RulesEditorPre
ferences
oracle.bpel
.ruledictio
narydc.mode
l.impl.Rule
sEditorPref
erencesImpl
Support
s EL?
Description
Only EL
yes
rulesPageSize
java.lang.
Integer
no
selectedRulesetIdx
java.lang.String
no
selectedTab
java.lang.String
no
yes
yes
yes
Switches to the
specified tab name
(either GLOBALS,
BUCKETSETS, DESC_
FUNCS, or the ruleset
name).
26-49
Support
s EL?
no
true
yes
java.lang.Boolean no
true
yes
showValidationPanel java.lang.
Boolean
no
true
yes
timeStyle
java.lang.String
no
Gets it from
the locale
yes
timezone
java.util.
TimeZone
no
TimeZone. yes
getDefault
()
viewOnly
java.lang.
Boolean
no
true
yes
If true, in view-only
mode, you can view the
existing dictionary
data, but you cannot
edit the data. If false,
which is edit mode, you
can edit the existing
dictionary data.
vldnPanelCollapsed
java.lang.Boolean no
false
yes
Used to specify if
validation panel should
be collapsed by default.
vldnTabTitle
java.lang.String
Localized
text
yes
Name
Type
showDTButtons
java.lang.
Boolean
showRSButtons
no
Business
Rule
Validation Log
26-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
26.4 Using the Oracle Business Rules Dictionary Editor Task Flow
This section discusses the Oracle Business Rules Dictionary Editor task flow. It also
provides information on how to create and run an application using the Rules
Dictionary Editor task flow, and then deploy the application.
26.4.2 How to Create and Run a Sample Application By Using the Rules Dictionary
Editor Task Flow
This section lists the steps for creating and running a sample application by using the
Oracle Rules Dictionary Editor task flow.
The prerequisites for using the Oracle Rules Dictionary Editor task flow to create
ADF-based web applications is having a running installation of Oracle SOA Suite and
Oracle JDeveloper on your computer.
To create a sample application by using the Oracle Rules Dictionary Editor task
flow:
The first task is to create a sample application.
The steps are:
1.
2.
From the File menu, select New and then Generic Application to create an
application.
3.
Enter a name for the application in the Application Name field, for example,
useRuleDictTaskFlowApp, and click Next as shown in Figure 2648.
Figure 2648
26-51
4.
Enter useRuleDictTaskFlow in the Project Name field and ensure that ADF
Faces is selected in the Project Technologies tab, as shown in Figure 2649.
5.
6.
b.
Click Add and select ADF Faces Components from the Extension list in the
Choose Tag Libraries dialog box, and click OK as shown in Figure 2650.
26-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2650
c.
Select Libraries and Classpath from the left panel and click Add Library to
display the Add Library dialog box.
d.
Select Oracle Rules and then Oracle Rules Dictionary Task Flow in the
Libraries list and click OK as shown in Figure 2651. This adds the Rules SDK
and the Rules Dictionary Task Flow JARs to the project.
Figure 2651
e.
26-53
7.
Click Save All from the Oracle JDeveloper File menu to save the project.
8.
b.
From the File menu, select New to display the New Gallery dialog box.
c.
In the New Gallery dialog box, select Java under General from the Categories
panel. Ensure that Java Class under Items is selected and click OK to display
the Create Java Class dialog box.
d.
e.
Figure 2652 Creating a Java Class That Implements the MetadataDetails Interface
java.io.BufferedReader;
java.io.FileNotFoundException;
java.io.FileOutputStream;
java.io.IOException;
java.io.InputStream;
java.io.InputStreamReader;
java.io.OutputStreamWriter;
java.io.UnsupportedEncodingException;
java.io.Writer;
import java.net.MalformedURLException;
26-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
import java.net.URL;
import oracle.integration.console.metadata.model.share.MetadataDetails;
import oracle.integration.console.metadata.model.share.RelatedMetadataPath;
public class MyMetaDataDetails implements MetadataDetails {
public MyMetaDataDetails() {
super();
}
private static final String RULES_FILE1 =
"file:///<path of Rules file>";
public String getDocument() {
URL url = null;
try {
url = new URL(RULES_FILE1);
return readFile(url);
} catch (IOException e) {
System.err.println(e);
}
return "";
}
public void setDocument(String string) {
URL url = null;
try {
url = new URL(RULES_FILE1);
} catch (MalformedURLException e) {
System.err.println(e);
return;
}
Writer writer = null;
try {
//os = new FileWriter(url.getPath());
writer =
new OutputStreamWriter(new FileOutputStream(url.getPath()),
"UTF-8");
} catch (FileNotFoundException e) {
System.err.println(e);
return;
} catch (IOException e) {
System.err.println(e);
return;
}
try {
writer.write(string);
} catch (IOException e) {
System.err.println(e);
} finally {
if (writer != null) {
try {
writer.close();
} catch (IOException ioe) {
System.err.println(ioe);
}
}
}
}
26-55
26-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
26-57
26-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
under Managed Beans to display the Create Managed Bean dialog box.
12. Point to MyBean.java by entering MyBean in the Bean Name field and selecting
Specifying the Bean Name and Scope in the Task Flow Application
2.
From the File menu, select New to display the New Gallery dialog box.
26-59
3.
In the New Gallery dialog box, select JSF under Web Tier from the Categories
panel.
4.
Select JSF Page under Items and click OK to display the Create JSF Page dialog
box, as shown in Figure 2654.
Figure 2654 Creating the JSF Page File to Include the Rules Dictionary Editor Task
Flow
5.
In the Create JSF Page dialog box, enter useRuleDictTaskFlow.jspx as the file
name, as shown in Figure 2655.
Figure 2655 Specifying the Name of the JSF Page for the Task Flow
26-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2656
This is because you have added the Oracle Rules Dictionary Task Flow shared
library when creating the sample application.
6.
Figure 2657
26-61
<af:menuBar id="mb1">
<af:commandMenuItem text="Toggle Mode" id="cmi1"
action="#{MyBean.toggleMode}"
partialSubmit="true"/>
<af:commandMenuItem text="Save Dict" id="cmi2"
action="#{MyBean.saveDictionary}"
partialSubmit="true"/>
<af:commandMenuItem text="Save Dict No Validate" id="cmi3"
action="#{MyBean.saveNoValidateDictionary}"
partialSubmit="true"/>
<af:commandMenuItem text="Validate" id="cmi4"
action="#{MyBean.validate}"
partialSubmit="true"/>
</af:menuBar>
</f:facet>
<f:facet name="center">
<af:region value="#{bindings.rulesdictflowdefinition1.regionModel}"
id="r2" binding="#{MyBean.regionComp}"
partialTriggers="::cmi1 ::cmi2 ::cmi3 ::cmi4"/>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>
In the preceding sample, you can find code snippets for rendering the following
buttons to the page:
2.
Select Run.
This starts the sample application in a web browser, as shown in Figure 2658.
Figure 2658 Running the Sample Rules Dictionary Editor Task Flow Application
26-63
26.4.3 How to Deploy a Rules Dictionary Editor Task Flow Application to a Standalone
Oracle WebLogic Server
When you are ready to deploy your application EAR file to the standalone Oracle
WebLogic Server, perform the following:
1.
2.
3.
4.
5.
In the project that has to be deployed (where you create the EAR file):
a.
b.
c.
Modify faces-config.xml in the project that uses the Rules Editor component.
The faces-config.xml file must have the following code within the
<application> tag to support the available resource bundles:
<locale-config>
<default-locale>en</default-locale>
<supported-locale>en</supported-locale>
<supported-locale>ar</supported-locale>
<supported-locale>cs</supported-locale>
<supported-locale>da</supported-locale>
<supported-locale>de</supported-locale>
<supported-locale>el</supported-locale>
<supported-locale>es</supported-locale>
<supported-locale>fi</supported-locale>
<supported-locale>fr</supported-locale>
<supported-locale>hu</supported-locale>
<supported-locale>it</supported-locale>
<supported-locale>iw</supported-locale>
<supported-locale>ja</supported-locale>
<supported-locale>ko</supported-locale>
<supported-locale>nl</supported-locale>
<supported-locale>no</supported-locale>
26-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<supported-locale>pl</supported-locale>
<supported-locale>pt-BR</supported-locale>
<supported-locale>pt</supported-locale>
<supported-locale>ro</supported-locale>
<supported-locale>ru</supported-locale>
<supported-locale>sk</supported-locale>
<supported-locale>sv</supported-locale>
<supported-locale>th</supported-locale>
<supported-locale>tr</supported-locale>
<supported-locale>zh-CN</supported-locale>
<supported-locale>zh-TW</supported-locale>
</locale-config>
2.
3.
You can override the locale provided by the browser and display the user interface
in a specific locale. This is done by passing that locale as an attribute to the
component and modifying the f:view tag in the application using the component
as shown:
<f:view locale="#{someBean.locale}">
The locale specified here should be the same as the one passed to the component
using the locale attribute.
26.6.1 Enabling Translations for Consumer of Reusable Rules UI ADF Task Flow
Component
To support translation of aliases, the consumers of reusable Rules UI ADF Task Flow
component will have to provide locale specific resource artifacts as additional
parameters while calling Rules UI ADF Task Flow. However, these additional
parameters are optional and required only if the consumers want to use the enhanced
translation support.
The additional parameters are:
property-name: relatedDetails
property-class:
oracle.integration.console.metadata.model.share.IRelatedMetadataDetails
Example 261
Flow.
<taskFlow id="rulesdictflowdefinition1"
taskFlowId="/WEB-INF/rule-dict-flow-definition.xml#rules-dict-flow-definition"
activation="deferred" Refresh="default"
RefreshCondition="${MyBean.refreshReqd}"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameter id="relatedDetails"
value="#{MyBean.relatedMetadataDetails}"/>
</taskflow>
26-65
26-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
}
}
public void saveDocument(IRelatedMetadataPath path, String document) {
try {
storeResource(path.getValue(), document);
} catch (IOException e) {
e.printStackTrace();
}
}
private static void storeResource(String resourceSuffix,
String document) throws IOException {
FileOutputStream fos = null;
FileChannel fc = null;
try {
URL url = new URL(RESOURCE_PATH + RESOURCE_BASE + resourceSuffix);
fos = new FileOutputStream(url.getFile());
fc = fos.getChannel();
ByteBuffer bb = ByteBuffer.allocateDirect(1024);
bb.clear();
bb.put(Charset.defaultCharset().encode(document));
bb.flip();
while (bb.hasRemaining()) {
fc.write(bb);
}
} finally {
if (fos != null) {
fos.close();
}
if (fc != null) {
fc.close();
}
}
}
public IRelatedMetadataPathFinderFactory getFinderFactory() {
return new RelatedMetadataPathFinderFactory();
}
public List<IRelatedMetadataPath> getExisting(IRelatedMetadataPathFinder finder)
{
List<IRelatedMetadataPath> paths = new ArrayList<IRelatedMetadataPath>();
for (Locale locale : LOCALES) {
paths.add(RelatedResourceMetadataPath.buildFromLocale(locale));
}
return paths;
}
public class RelatedMetadataPathFinderFactory implements
IRelated`MetadataPathFinderFactory {
public IRelatedMetadataPathFinder getResourceFinder() {
return new RelatedMetadataPathFinder();
}
}
public class RelatedMetadataPathFinder implements IRelatedMetadataPathFinder {
26-67
<rddc:ruleDictionaryDC ruleDictModel="#{SomeBean.ruleDictModel1}"
id="rddc1"
resourceManager="#{SomeBean.resourceManager}">
</rddc:ruleDictionaryDC>
26-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The consumer has to load all the saved resource bundles from
the repository and should construct a java.util.Map (resourceMap)
where java.util.Locale of the resource bundle is kept as key and the
content of the resource bundle file as value which is of type
java.lang.String.
Note:
26-69
26-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part V
Part V
This part describes how to use the human workflow service component.
This part contains the following chapters:
27
Getting Started with Human Workflow
27
This chapter describes for developers the human workflow concepts, features, and
architecture. Use cases for human workflow are provided. Instructions for designing
your first workflow from start to finish are also provided.
This chapter includes the following sections:
27-1
A BPEL process invokes a special activity of the human task type when it needs a
human to perform a task.
This creates a task in the human task service component. The process waits for the
task to complete. It is also possible for the process to watch for other callbacks
from the task and react to them.
There is metadata associated with the task that is used by the human task service
component to manage the lifecycle of the task. This includes specification of the
following:
Who performs the task. If multiple people are required to perform the task,
what is the order?
How do users perform the task, what information is presented to them, what
are they expected to provide, and what actions can they take?
The human task service component uses an identity directory, such as LDAP, to
determine peoples roles and privileges.
27-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The human task service component presents tasks to users through a variety of
channels, including the following:
Notifications can be sent by email, phone, SMS, and other channels. Email
notifications can be actionable, enabling users to perform actions on the task
from within the email client without connecting to Oracle BPM Worklist or
Oracle WebLogic Server.
For information about portlets, see Chapter 36, "Configuring Task List Portlets."
Note:
27-3
Single approver
This is the simple case where a participant maps to a user, group, or role.
For example, a vacation request is assigned to a manager. The manager must act
on the request task three days before the vacation starts. If the manager formally
approves or rejects the request, the employee is notified with the decision. If the
manager does not act on the task, the request is treated as rejected. Notification
actions similar to the formal rejection are taken.
Parallel
This participant indicates that a set of people must work in parallel. This pattern is
commonly used for voting.
For example, multiple users in a hiring situation must vote to hire or reject an
applicant. You specify the voting percentage that is needed for the outcome to take
effect, such as a majority vote or a unanimous vote.
Serial
This participant indicates that a set of users must work in sequence. While
working in sequence can be specified in the routing policy by using multiple
participants in sequence, this pattern is useful when the set of people is dynamic.
The most common scenario for this is management chain escalation, which is done
by specifying that the list is based on a management chain within the specification
of this pattern.
27-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This participant also maps to a single user, group, or role, just as in single
approver. However, this pattern indicates that the participant just receives a
notification task and the business process does not wait for the participants
response. FYI participants cannot directly impact the outcome of a task, but in
some cases can provide comments or add attachments.
For example, a regional sales office is notified that a candidate for employment has
been approved for hire by the regional manager and their candidacy is being
passed onto the state wide manager for approval or rejection. FYIs cannot directly
impact the outcome of a task, but in some cases can provide comments or add
attachments.
For more information, see Section 29.4, "Assigning Task Participants."
27.2.1.1.3 Participant Assignment A task is work that must be done by a user. When you
create a task, you assign humans to participate in and act upon the task. Participants
can perform actions upon tasks during runtime from Oracle BPM Worklist, such as
approving a vacation request, rejecting a purchase order, providing feedback on a help
desk request, or some other action. There are three types of participants:
Users
You can assign individual users to act upon tasks. For example, you may assign
users jlondon or jstein to a particular task. Users are defined in an identity
store configured with the SOA Infrastructure. These users can be in the embedded
LDAP of Oracle WebLogic Server, Oracle Internet Directory, or a third party LDAP
directory.
Groups
You can assign groups to act upon tasks. Groups contain individual users who can
claim and act upon a task. For example, users jcooper and fkafka may be
members of the group LoanAgentGroup that you assign to act upon the task.
As with users, groups are defined in the identity store of the SOA Infrastructure.
Application roles
You can assign users who are members of application roles to claim and act upon
tasks.
Application roles consist of users or other roles grouped logically for
application-level authorizations. These roles are application-specific and are
defined in the application Java policy store rather than the identity store. These
roles are used by the application directly and are not necessarily known to a Java
EE container.
Application roles define policy. Java permissions can be granted to application
roles. Therefore, application roles define a set of permissions granted to them
directly or indirectly through other roles (if a role is granted to a role). The policy
can contain grants of application roles to enterprise groups or users. In the
jazn-data.xml file of the file-based policy store, these roles are defined in
<app-role> elements under <policy-store> and written to
system-jazn-data.xml at the farm level during deployment. You can also
define these roles after deployment using Oracle Enterprise Manager Fusion
Middleware Control. You can set a task owner or approver to an application role at
design time if the role has been previously deployed.
For more information about Oracle BPM Worklist, see Section 27.2.1.6, "Task Forms."
27-5
27.2.1.1.4 Ad Hoc Routing In processes dealing with significant variance, you cannot
always determine all participants. Human workflow enables you to specify that a
participant can invite other participants as part of performing the task.
For more information, see Section 29.5.1.1, "Allowing All Participants to Invite Other
Participants."
27.2.1.1.5 Outcome-based Completion of Routing Flow By default, a task goes from starting
to final participant according to the flow defined in the routing policy (as shown in
Figure 272). However, sometimes a certain outcome at a particular step within a
tasks routing flow makes it unnecessary or undesirable to continue presenting the
task to the next participants. For example, if an approval is rejected by the first
manager, it does not need to be routed to the second manager. Human workflow
supports specifying that a task or subtask be completed when a certain outcome
occurs.
For more information, see Section 29.5.1.2, "Stopping Routing of a Task to Further
Participants."
Simply enable participants to claim the task manually. This is the default
behavior. No task-assignment pattern is applied.
27-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
task-assignment pattern selects the user jcooper, and one user from the
group LoanAgent, and one user with the application role Developers.
For example, if the task has a payload message attribute named po within
which the task approvers are stored, you can use the following XPath
expression:
/task:task/task:payload/po:purchaseOrder/po:approvers
ids:getManager('jstein', 'jazn.com')
This returns the manager of jstein.
ids:getReportees('jstein', 2, 'jazn.com')
This returns all reportees of jstein up to two levels.
ids:getUsersInGroup('LoanAgentGroup', false,
'jazn.com')
This returns all direct and indirect users in the group LoanAgentGroup.
You can use both options simultaneouslyfor example, you can use an XPath
expression to dynamically select a group, and then apply a task-assignment
pattern to dynamically select a user from that group.
Owner
This participant has business administration privileges on the task. This
participant can be specified as part of the task definition or from the invoking
process (and for a particular instance). The task owner can act upon tasks they
own and also on behalf of any other participant. The task owner can change both
the outcome of the task and the assignments.
For more information, see Section 29.2.7, "How to Specify a Task Owner" to specify
an owner in the Human Task Editor or Section 28.4.4.2, "Specifying a Task Owner"
to specify an owner in the Advanced tab of the Human Task dialog.
27-7
Initiator
The person who initiates the process (for example, the initiator files an expense
report for approval). This person can review the status of the task using initiated
task filters. Also, a useful concept is for including the initiator as a potential
candidate for request-for-information from other participants.
For more information, see Section 28.4.3.2, "Specifying the Task Initiator and Task
Priority."
Reviewer
This participant can review the status of the task and add comments and
attachments.
Admin
This participant can view all tasks and take certain actions such as reassigning a
test, suspending a task to handle errors, and so on. The task admin cannot change
the outcome of a task.
While the task admin cannot perform the types of actions that a task participant
can, such as approve, reject, and so on, this participant type is the most powerful
because it can perform actions such as reassign, withdraw, and so on.
Error Assignee
When an error occurs, the task is assigned to this participant (for example, the task
is assigned to a nonexistent user). The error assignee can perform task recovery
actions from Oracle BPM Worklist, the task form in which you perform task
actions during runtime.
For more information, see Section 29.5.4, "How to Configure the Error Assignee."
Reminders:
The task can be reminded multiple times based on the time after the assignment or
the time before the expiration.
Escalation:
The task is escalated up the management hierarchy.
Expiration:
The task has expired.
Renewal:
The task is automatically renewed.
For more information, see Section 29.7, "Escalating, Renewing, or Ending the Task."
27.2.1.5 Notifications
You can configure your human task to use notifications. Notifications enable you to
alert interested users to changes in the state of a task during the task lifecycle. For
example, a notification is sent to an assignee when a task has been approved or
withdrawn.
27-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can specify for notifications to be sent to different types of participants for
different actions. For example, you can specify the following:
For the owner of a task to receive a notification message when a task is in error (for
example, been sent to a nonexistent user).
For a task assignee to receive a notification message when a task has been
escalated.
You can specify the contents of the notification message and the notification channel to
use for sending the message.
Email
You can configure email notification messages to be actionable, meaning that a
task assignee can act upon a task from within the email.
Voice message
For example, you may send the message shown in Example 271 by email when a task
assignee requests additional information before they can act upon a task:
Example 271
Email Message
For me to approve this task, more information is required to justify the need
for this business trip
During runtime, you can mark a message sender's address as spam and also display a
list of bad or invalid addresses. These addresses are automatically removed from the
bad address list.
For more information about notifications, see the following:
27-9
Unattended tasks
Analysis of tasks assigned to users' groups or reportees' groups that have not yet
been acquired.
Tasks priority
Analysis of tasks assigned to a user, reportees, or their groups, based on priority.
27-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Tasks productivity
Analysis of assigned tasks and completed tasks in a given time period for a user,
reportees, or their groups.
You can view an audit trail of actions performed by the participants in the task and a
snapshot of the task payload and attachments at various points in the workflow. The
short history for a task lists all versions created by the following tasks:
Initiate task
Reinitiate task
Completion of task
Erring of task
Expiration of task
Withdrawal of task
For more information, see Chapter 32, "Using Oracle BPM Worklist."
Step
Description
You create a task form. This form displays the task Section 28.1.3, "Introduction to
details on which you act at runtime in Oracle BPM Generating the Task Form."
Worklist.
27-11
Assign Task
Workflow Services
Task Complete
OID
BPEL
Process
LDAP
All Approvals
Complete
Various
Routing
Patterns
You can use these types as building blocks to create complex workflows.
another to balance the load between various task assignees. All tasks defined in BPEL
have an associated expiration date. Additionally, you may specify escalation or
renewal policies, as shown in Figure 275. For example, consider a support call, which
is part of a help desk service request process. A high-priority task may be assigned to a
certain user, and if the user does not respond in two days, the task is routed to the
manager for further action.
Figure 275 Escalation and Notification
Workflow Services
Escalate Task
Calendar
Notify Manager
BPEL
Process
Task Resolved
Notification
27-13
The services that perform a variety of operations in the lifecycle of a task, such as
querying tasks for a user, retrieving metadata information related to a task, and so
on.
The two ways to use a human task:
Task Service:
The task service provides task state management and persistence of tasks. In
addition to these services, the task service exposes operations to update a task,
complete a task, escalate and reassign tasks, and so on. The task service is used by
Oracle BPM Worklist to retrieve tasks assigned to users. This service also
determines if notifications are to be sent to users and groups when the state of the
task changes. The task service consists of the following services.
Identity Service
The identity service is a thin web service layer on top of the Oracle Application
Server 11g security infrastructure or any custom user repository. It enables
authentication and authorization of users and the lookup of user properties, roles,
group memberships, and privileges.
Notification Service
The notification service delivers notifications with the specified content to the
specified user through any of the following channels: email, telephone voice
message, IM, and SMS. See Section 34.2, "Notifications from Human Workflow" for
more information.
27-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Evidence service
The evidence service supports storage and nonrepudiation of digitally-signed
workflow tasks.
Workflow Services
BPEL
Process
Service
Component
Workflow
Services
Portal
Task
Metadata
Service
Evidence
Store
Service
User
Metadata
Service
Identity
Service
Task
Service
Task Query
Service
Task
Assignment
Service
Notification
Service
Oracle BPM
Worklist
Metadata
E-Mail Client
Metadata
MDS
.task
.bpel
.wsdl
Users
Identity
Management
- OID
- LDAP
- JAZN
- other user
directories
Database
Notification
Channels
- E-mail
- Voice
- SMS
- IM
Figure 277 shows the interactions between the services and the business process.
27-15
BPEL Process
Service Component
Task Service
Provides task persistence
and exposes operations to
update a task, complete a
task, escalate and
reassign tasks, and so on
Task Assignment
Service
Offers services to route,
escalate, and reassign
tasks
Notification Service
Sends notifications to users
by e-mail, voice message,
instance messaging, or
short message service
Identity Service
user / group / role lookup
user authentication
authorization
organization hierarchy
User Directory
(one of)
Oracle
Internet
Directory
JAZN
XML
LDAP,
Custom
Policy Store
Contains
Information about
application roles
and permissions
27-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can also create the human task as a standalone component only in the SOA
Composite Editor and not associate it with a BPEL process. Standalone human
task service components are useful for environments in which there is no need for
any automated activity in an application. In the standalone case, the client can
create the task themselves.
27-17
27-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
28
28
This chapter describes how to create a human task, save it, and associate it with a
BPEL process. It also describes how to delete a human task and remove its association
with a BPEL process.
This chapter includes the following sections:
Section 28.3, "Exiting the Human Task Editor and Saving Your Changes"
To use the Human Task Editor, you must understand human task design concepts,
including the following:
The task participant types available for modeling a task to which you assign users
For information about human task concepts, see Chapter 27, "Getting Started with
Human Workflow."
For information about troubleshooting human workflow issues, see section "Human
Workflow Troubleshooting" of Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
For information about installing and using the organizational hierarchy of users and
groups known as the demo user community, see Appendix "Installing the Demo User
Community in the Database" of Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
Creating and modeling a human task service component in the SOA Composite
Editor
Associating it with a BPEL process
Generating the task form for displaying the human task during runtime in Oracle
BPM Worklist.
This section provides a brief overview of these modeling tasks and provides references
to specific modeling instructions.
For more information about using the SOA Composite Editor, see Chapter 2,
"Developing SOA Composite Applications with Oracle SOA Suite."
For information about available samples, see Chapter 31, "Human Workflow Tutorial."
By dragging a human task from the Component Palette into a BPEL process in
Oracle BPEL Designer and clicking the Add icon in the Create Human Task dialog
that automatically is displayed. This displays a dialog for creating the human task
service component. When creation is complete, the Human Task Editor is
displayed.
By dragging a human task service component from the Component Palette into
the SOA Composite Editor. This displays a dialog for creating the human task
component. When creation is complete, the Human Task Editor is displayed.
28.1.2 Introduction to Associating the Human Task Definition with a BPEL Process
You can associate the .task file that consists of the human task settings with a BPEL
process in Oracle BPEL Designer. Association is made with a human task that you
drag into your BPEL process flow for configuring, as shown in Figure 281.
28-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You also specify the task definition, task initiator, task priority, and task parameter
mappings that carry the input data to a BPEL variable. You can also define advanced
features, such as the scope and global task variables names (instead of accepting the
default names), task owner, identification key, BPEL callback customizations, and
whether to extend the human task to include other workflow tasks.
When association is complete, a task service partner link is created. The task service
exposes the operations required to act on the task.
You can also create the human task as a standalone component only in the SOA
Composite Editor and not associate it with a BPEL process. Standalone human task
service components are useful for environments in which there is no need for any
automated activity in an application. In the standalone case, the client can create the
task themselves.
For more information, see Section 28.4, "Associating Human Tasks with BPEL
Processes."
whether the component can be associated later with a BPEL process service
component or is a standalone component in the SOA Composite Editor.
28.2.1 How to Create a Human Task Using the SOA Composite Editor
You can create a human task using the SOA Composite Editor. Generally you use this
method to create human tasks to use as standalone components.
To create a human task service component in the SOA Composite Editor:
1. Go to the SOA project in which to create a human task service component in the
SOA Composite Editor.
2.
3.
4.
5.
Note the Create Composite Service with SOAP Bindings checkbox. The selection
of this checkbox determines how the human task service component is created.
a.
To create a human task service component that you later associate with a BPEL
process service component, do not select the Create Composite Service with
SOAP Bindings checkbox. The human task service component is created as a
component that you explicitly associate with a BPEL process service
component. Figure 282 provides details.
b.
This web service provides external customers with an entry point into the
human task service component of the SOA composite application.
6.
Click OK.
28-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about creating a human task service component in the SOA
Composite Editor, see Chapter 2, "Developing SOA Composite Applications with
Oracle SOA Suite."
3.
4.
5.
6.
Click OK.
The Human Task Editor appears.
You can also create a human task that you later associate with a
BPEL process by selecting New from the File main menu, then
selecting SOA Tier > Service Components > Human Task.
Note:
The human task settings specified in the Human Task Editor are saved to a
metadata task configuration file in the metadata service (MDS) repository with a
.task extension. This file appears in the Application Navigator under SOA_
Project_Name > SOA Content. You can re-edit the settings in this file by
double-clicking the following:
The .task file in the Application Navigator in either the SOA Composite
Editor or Oracle BPEL Designer
The human task icon in the SOA Composite Editor or in your BPEL process in
Oracle BPEL Designer.
A Human Tasks folder containing the human task you created appears in the
Structure window of the SOA Composite Editor.
For information about available samples, see Chapter 31, "Human Workflow Tutorial."
28.3 Exiting the Human Task Editor and Saving Your Changes
You can save your human task changes at any time. The task can be re-edited at a later
time by double-clicking the metadata task configuration .task file in the Application
Navigator.
To exit the Human Task Editor and save your changes:
1. From the File main menu, select Save or click the X sign shown in Figure 285 to
close the .task metadata task configuration file.
Figure 285 File Closure
2.
If you click the X sign, select Yes when prompted to save your changes.
28-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If you have created a human task service component in the SOA composite
application, drag a human task activity into the BPEL process in Oracle BPEL
Designer. Then, select the existing human task service component from the Task
Definition list of the Create Human Task dialog. You can then specify the task
title, initiator, parameter values, and other values.
If you have not created a human task service component, drag the human task
activity into the BPEL process in Oracle BPEL Designer Then, click the Add icon to
the right of the Task Definition list in the Create Human Task dialog. This action
enables you to specify the name of the new human task service component, the
parameters, and the outcomes. The Human Task Editor then opens for you to
design the remaining task metadata. After design completion, close the Human
Task Editor.
1.
2.
Double-click the BPEL process service component with which to associate the
.task file of the human task service component.
3.
4.
5.
6.
From the Task Definition list of the General tab, select the human task, as shown
in Figure 286.
The .task file of the human task service component is associated with the BPEL
process.
After you complete association of your human task activity
with a BPEL process and close the Create Human Task dialog, you can
always re-access this dialog by double-clicking the human task
activity in Oracle BPEL Designer.
Note:
28.4.2 What You May Need to Know About Deleting a Wire Between a Human Task and
a BPEL Process
If you delete the wire between a BPEL process and the human task service component
that it invokes, the invoke activity of the human workflow is deleted from the BPEL
process. However, the taskSwitch switch activity for taking action (contains the
approve, reject, and otherwise task outcomes) is still there. This is by design for the
following reasons:
If you then drag and drop a human task service component into the BPEL process to
use the same taskSwitch switch activity, a new taskSwitch switch activity is created.
You then have two switch activities in the BPEL process with the same name. To
determine which one to delete, you must go into the approve, reject, and otherwise
task outcomes of the taskSwitch switch activities to determine which is the older,
modified switch and which is the newer switch.
28.4.3 How to Define the Human Task Activity Title, Initiator, Priority, and Parameter
Variables
Figure 287 shows the General tab that displays after you select the human task.
28-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The General tab of the Human Task activity enables you to perform the tasks shown
in Table 281:
Table 281
See...
Task Title
Initiator
Priority
Task Parameters
You can also combine static text and dynamic expressions in the same title. To
include dynamic text, place your cursor at the appropriate point in the text and
click the icon on the right to invoke the Expression Builder dialog.
From the Priority list, select a priority value between 1 (the highest) and 5. This
field is provided for user reference and does not make this task a higher priority
during runtime. Use the priority to sort tasks in Oracle BPM Worklist. This priority
value overrides the priority value you select in the Priority list of the General
section of the Human Task Editor.
For more information about specifying the priority in the Human Task Editor, see
Section 29.2.2, "How to Specify a Task Title."
28-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Expand the Variables tree shown in Figure 289 and select the appropriate task
variable.
3.
Click OK.
The Human Task dialog shown in Figure 2810 appears as follows.
Figure 2810
28-11
4.
To define advanced features for the human task activity, click the Advanced tab
and go to Section 28.4.4, "How to Define the Human Task Activity Advanced
Features." Otherwise, click OK to close the Human Task dialog.
The Advanced tab of the Human Task activity enables you to perform the tasks shown
in Table 282:
Table 282
See...
Scope Name
Identification Key
Identity Context
Application Context
28-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In the Global Task Variable Name field of the Advanced tab, enter the global task
variable name.
This is the name of the BPEL task variable used for the workflow interaction.
28-13
The participant of the second task may want to see the approval history, comments,
and attachments created when the manager approved the purchase. You can link these
different tasks in the BPEL process by chaining the second task to the first task with
this option.
For chained tasks, the title of the new task cannot be set from the task metadata
(.task file). For example, assume existing Task A is chained with new task Task B,
and Task B has a new title set in the Human Task Editor; this title is not recognized.
Therefore, if the chained task requires a different title, it must be set in the task
instance before calling the task service reinitiate operation. If a BPEL process is
initiating the tasks, set the task title before the workflow service APIs are called. If a
Java program is calling the workflow APIs programatically, then it must set the title.
To include the task history of other tasks:
1. Select the Include task history from checkbox of the Advanced tab to extend a
previous workflow task in the BPEL process. Selecting this checkbox includes the
task history, comments, and attachments from the previous task. This provides
you with a complete end-to-end audit trail.
When a human task is continued with another human task, the following
information is carried over to the new workflow:
Task payload and the changes made to the payload in the previous workflow
Task history
Due date
In the Include task history from list, all existing workflows are listed.
2.
Select a particular human task to extend (continue) the selected human task.
For example, a hiring process is used to hire new employees. Each interviewer
votes to hire or not hire a candidate. If 75% of the votes are to hire, then the
candidate is hired; otherwise, the candidate is rejected. If the candidate is to be
hired, an entry in the HR database is created and the human resources contact
completes the hiring process. The HR contact also must see the interviewers and
the comments they made about the candidate. This process can be modeled using
a parallel participant type for the hiring. If the candidate is hired, a database
adapter is used to create the entry in the HR database. After this action, a simple
workflow can include the task history from the parallel participant type so that the
hiring request, history, and interviewer comments are carried over. This simple
workflow is assigned to the HR contact.
3.
28-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
AssignTaskAttributes
Captures the user-defined attributes of the task
such as title, payload, creator, priority, and so on
AssignSystemTaskAttributes
Captures the system task attributes such as
process id, process version, and so on
InitiateTask
Initiates the task by invoking the task service
ReceiveCompletedTask
Receives the completed task from the task service
Click the Expand icon next to the human task activity in Oracle BPEL Designer to
display its contents, as shown in Figure 2813.
Figure 2813
onTaskCompleted
This callback is invoked when the task is completed, expired, withdrawn, or
errored.
Creating Human Tasks
28-15
onTaskAssigned
This callback is invoked when the task is assigned to a new set of assignees due to
the following actions:
Outcome update
onTaskUpdated
This callback is invoked for any other update to the task that does not fall in the
onTaskComplete or onTaskAssigned callback. This includes updates on tasks
due to a request for information, a submittal of information, an escalation, a
reassign, and so on.
onSubTaskUpdated
This callback is invoked for any update to a subtask.
Figure 2814 shows how a workflow interaction with callbacks is modeled. After this
task is initiated, a while loop is used to receive messages until the task is complete. The
while loop contains a pick with four onMessage branches one for each of the
above-mentioned callback operations. The workflow interaction works fine even if
nothing is changed in the onMessage branches, meaning that customizations in the
onMessage branches are not required.
In this scenario, a workflow context is captured in the BPEL instance. This context can
be used for all interaction with the workflow services. For example, to reassign a task
if it is assigned to a group, then you need the workflow context for the
reassignTask operation on the task service.
It is recommended that any user customizations be performed in the first assign,
AssignTaskAttributes, and that AssignSystemTaskAttributes not be changed.
28-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2814
AssignSystemTaskAttributes
Captures the system task attributes such as
process id, process version, and so on
InitiateTask
Initiates the task by invoking the task service
AssignWorkflowContext
Assigns the workflow context to use for
interactions with the workflow service
Receive
onTaskCompleted
message
Receive
onTaskAssigned
message
Receive
onTaskUpdated
message
Receive
onSubTaskUpdate
message
User
customizations
User
customizations
User
customizations
User
customizations
28.4.6 What You May Need to Know About Changing the Generated Human Task
Activity
If you must change a generated human task activity, note the following details:
Do not modify the assign tasks that are automatically created in a switch activity
when you add a human task to a BPEL process flow. Instead, add a new assign
activity outside the switch activity.
If the parameter passed into a human task is modified (for example, you change
the parameter type in the Edit Task Parameter dialog), you must open the human
task activity in the BPEL process flow and click OK to correct the references to the
payload variable. Not doing so causes the parameter name to change and become
uneditable.
If the task outcomes in the Human Task Editor are modified, you must edit the
human task activity and click OK. The switch case is then updated based on the
changes to the outcomes.
28-17
If you make any changes to the translatable strings of the title or category of a task
in the resource bundle, those changes do not appear in any instances of that task
that are already initiated. However, they do appear in instances of that task that
are initiated after you make the changes.
When you copy comments to a human task, make sure that those comments do
not contain the task ID. The taskId element must be empty.
28.4.7 What You May Need to Know About Deleting a Partner Link Generated by a
Human Task
Deleting a partner link that was generated by a human task (for example, human_
task_name.TaskService in the Partner Links swimlane) causes the human task to
become unusable. If you delete the partner link, you must delete the human task
activity in Oracle BPEL Designer and start over again.
If business logic must be added for each of these other conclusions, then case
statements can be added for each of the preceding conditions. The case statements can
be created as shown in the following BPEL segment. The XPath conditions for the
other conclusions in the case activities for each of the preceding cases are shown in
bold in Example 281.
Example 281
<switch name="taskSwitch">
<case condition="bpws:getVariableData('SequentialWorkflowVar1',
'/task:task/task:state') = 'COMPLETED' and
bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:conclusion') =
28-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
'ACCEPT'">
<bpelx:annotation>
<bpelx:pattern>Task outcome is ACCEPT
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1',
'WITHDRAWN'">
<bpelx:annotation>
<bpelx:pattern>Task is withdrawn
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1',
'EXPIRED'">
<bpelx:annotation>
<bpelx:pattern>Task is expired
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1',
'ERRORED'">
<bpelx:annotation>
<bpelx:pattern>Task is errored
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<otherwise>
<bpelx:annotation>
<bpelx:pattern>Task is EXPIRED, WITHDRAWN
</bpelx:pattern>
</bpelx:annotation>
...
</otherwise>
</switch>
'/task:task/task:state') =
'/task:task/task:state') =
'/task:task/task:state') =
or ERRORED
28-19
Once you have entered this copy rule, you can either save the file and continue
designing the BPEL process or, if you have finished designing, you can deploy the
process.
28-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
29
29
This chapter describes how to configure the different properties of a human task. It
covers basic properties, task payload data structure, participant assignment, routing
policies, localization, escalation, notification preferences, access policies and task
actions, restrictions and Java and business event callbacks.
This chapter includes the following sections:
Section 29.9, "Specifying Access Policies and Task Actions on Task Content"
For information about troubleshooting human workflow issues, see section "Human
Workflow Troubleshooting" of Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
Instructions for using these main sections of the Human Task Editor to create a
workflow task are listed in Table 291.
Table 291
Section
Description
See...
General
Data
Assignment
Presentation
(title, description,
outcomes, category,
priority, owner, and
application context)
Deadlines
Multilingual settings
29-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
Description
See...
Notification
Access
Events
Documents
Section 29.2.1, "How to Specify the Title, Description, Outcome, Priority, Category,
Owner, and Application Context"
29.2.1 How to Specify the Title, Description, Outcome, Priority, Category, Owner, and
Application Context
To specify the title, description, outcome, priority, category, owner, and
application context:
1. Click the General tab.
Figure 292 shows the General section of the Human Task Editor.
This section enables you to specify details such as the task title, description, task
outcomes, task category, task priority, and task owner.
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
Instructions for configuring the following subsections of the General section are
listed in Table 292:
Table 292
See...
Title
Description
Outcomes
Priority
Category
Owner
Application Context
In the Task Title field of the General section, select a method for specifying a task
title:
29-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
The expression is resolved during runtime with the exact order ID value from
the task payload.
If you enter a title in the Task Title field of the General tab of the Create Human
Task dialog described in Section 28.4.3.1, "Specifying the Task Title," the title you
enter here is overridden.
The task outcomes can also have runtime display values that are different from the
actual outcome value specified here. This permits outcomes to be displayed in a
different language in Oracle BPM Worklist. For more information about
internationalization, see Section 29.6.2, "How to Specify Multilingual Settings."
To specify a task outcome:
1. To the right of the Outcomes field in the General section, click the Search icon.
The Outcomes dialog shown in Figure 294 displays the possible outcomes for
tasks. APPROVE and REJECT are selected by default.
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
2.
Table 293
Outcomes Dialog
Field
Description
Add icon
Outcomes Requiring
Comment
Default Outcome
The seeded and custom outcomes selected here display for selection in the
Majority Voted Outcome section of the parallel participant type.
3.
For more information, see Section 29.4.4.1, "Specifying the Voting Outcome."
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
value you select in the General tab of the Create Human Task dialog. You can filter
tasks based on priority and create views on priorities in Oracle BPM Worklist.
To specify a task priority:
1. From the Priority list in the General section, select a priority for the task.
For more information about specifying a priority value in the Create Human Task
dialog, see Section 28.4.3.2, "Specifying the Task Initiator and Task Priority."
Statically through the identity service user directory or the list of application
roles
Dynamically through an XPath expression
For example:
If the task has a payload message attribute named po within which the
owner is stored, you can specify an XPath expression such as:
/task:task/task:payload/po:purchaseOrder/po:owner
ids:getManager('jstein', 'jazn.com')
The manager of jstein is the task owner.
For more information about users, groups, and application roles, see Section 27.2.1.1.3,
"Participant Assignment."
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
29.2.7.1 Specifying a Task Owner Statically Through the User Directory or a List of
Application Roles
Task owners can be selected by browsing the user directory (Oracle Internet Directory,
Java AuthoriZatioN (JAZN)/XML, LDAP, and so on) or a list of application roles
configured for use with Oracle SOA Suite.
To specify a task owner statically through the user directory or a list of
application roles:
1. In the first list to the right of the Owner field in the General section, select User,
Group, or Application Role as the type of task owner. Figure 295 provides
details.
By default, group names in human tasks are case sensitive.
Therefore, if you select Group and enter a name in upper case text (for
example, LOANAGENTGROUP), no task is displayed under the
Administrative Tasks tab in Oracle BPM Worklist. To enable group
names to be case agnostic (case insensitive), you must set the
caseSensitiveGroups property to false in the System MBeans
Browser. For information, see Oracle Fusion Middleware Administrator's
Guide for Oracle SOA Suite and Oracle Business Process Management
Suite.
Note:
Figure 295 Specify a Task Owner By Browsing the User Directory or Application Roles
2.
In the second list to the right of the Owner field in the General section, select
Static.
3.
See the step in Table 294 based on the type of owner you selected.
Table 294
Type of Owner
If You Selected...
See Step...
User or Group
Application Role
4.
If you selected User or Group, the Identity Lookup dialog shown in Figure 296
appears.
29-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
To select a user or group, you must first create an application server connection by
clicking the Add icon. Note the following restrictions:
Select Properties.
a.
b.
Search for the owner by entering a search string such as jcooper, j*, *,
and so on. Clicking the Lookup icon to the right of the User Name field
fetches all the users that match the search criteria. Figure 297 provides
details. One or more users or groups can be highlighted and selected by
clicking Select.
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
c.
View the hierarchy of a user by highlighting the user and clicking Hierarchy.
Similarly, clicking Reportees displays the reportees of a selected user or group.
Figure 298 provides details.
29-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
d.
View the details of a user or group by highlighting the user or group and
clicking Detail. Figure 299 provides details.
e.
f.
g.
5.
If you selected Application Role, the Select an Application Role dialog appears.
a.
In the Application Server list, select the type of application server that
contains the application role or click the Add icon to launch the Create
Application Server Connection wizard to create a connection.
29-11
Specifying the Title, Description, Outcome, Priority, Category, Owner, and Application Context
b.
In the Application list, select the application that contains the application roles
(for example, a custom application or soa-infra for the SOA Infrastructure
application).
c.
In the Available section, select appropriate application roles and click the >
button. To select all, click the >> button. Figure 2910 provides details.
d.
Click OK.
29-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
In the second list to the right of the Owner field in the General section, select
XPath.
3.
Figure 2912
Expression Builder
4.
Browse the available variable schemas and functions to create a task owner.
5.
Click Help for instructions on using the Expression Builder dialog and XPath
Building Assistant
Appendix B, "XPath Extension Functions" for information about workflow
service dynamic assignment functions, identity service functions, and
instructions on using the XPath Building Assistant
In the Application Context field of the General section, enter the name.
29-13
This section enables you to specify the structure (message elements) of the task
payload (the data in the task) defined in the XSD file. You create parameters to
represent the elements in the XSD file. This makes the payload data available to the
workflow task. For example:
You create a parameter for an order ID element for placing an order from a store
front application.
You create parameters for the location, type, problem description, severity, status,
and resolution elements for creating a help desk request.
Task payload data consists of one or more elements or types. Based on your selections,
an XML schema definition is created for the task payload.
Figure 2913 Human Task Editor Parameters Section
String
Integer
Boolean
Other
3.
29-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 295
Field
Description
Parameter Type
Select Type or Element and click the Search icon to display the
Type Chooser dialog for selecting the task parameter.
Parameter Name
Accept the default name or enter a custom name. This field only
displays if Type is the selected parameter type.
Select this checkbox to enable users to edit this part of the task
payload in Oracle BPM Worklist. For example, for a loan
approval task, the APR attribute may need to be updated by the
user reviewing the task, but the SSN field may not be editable.
You can also specify access rules that determine the parts of a
task that participants can view and update. For more
information, see Section 29.9.1, "How to Specify Access Policies
on Task Content."
Note:
4.
Figure 2915
5.
Parameter Type
29-15
6.
To edit your selection, select it and click the Edit icon in the upper right part of the
Data section.
You can easily mix and match participant types to create simple or complex workflow
routing policies. You can also extend the functionality of a previously configured
human task to model more complex workflows.
A participant type is grouped in a block under a stage (for example, named Stage1 in
Figure 2916). A stage is a way of organizing the approval process for blocks of
participant types. You can have one or more stages in sequence or in parallel. Within
each stage, you can have one or more participant type blocks in sequence or in
parallel. The up and down keys enable you to rearrange the order of your participant
type blocks.
For example:
You can create all participant type blocks in a single stage (for example, a purchase
order request in which the entire contents of the order are approved or rejected as
a whole).
You can create more complex approval tasks that may include one or more stages.
For example, you can place one group of participant type blocks in one stage and
another block in a second stage. The list of approvers in the first stage handles line
entry approvals and the list of approvers in the second stage handles header entry
approvals.
Each of the participant types has an associated editor that you use for configuration
tasks. The sequence in which the assignees are added indicates the execution
sequence.
To specify a different stage name or have a business requirement that requires you to
create additional stages, perform the following steps. Creating additional stages is an
advanced requirement that may not be necessary for your environment.
29-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Section 29.4.1, "How to Specify a Stage Name and Add Parallel and Sequential
Blocks"
For more information about participant types, see Section 27.2.1.1, "Task Assignment
and Routing."
29.4.1 How to Specify a Stage Name and Add Parallel and Sequential Blocks
To specify a stage name and add parallel and sequential blocks:
The stage is named Stage1 by default. If you want, you can change the name.
1.
Figure 2917
Edit Dialog
2.
3.
Select the stage and its participant type block, as shown in Figure 2918.
4.
Figure 2918
5.
29-17
A second stage is added in parallel to the first stage, as shown in Figure 2919.
Figure 2919 Parallel Stage
6.
Select the second stage on the right, and click the Add icon. If you do not select the
second stage (for this example, named Stage1 in Figure 2920) and instead select
only the participant type block (for example, named Edit Participant in
Figure 2920), all options under the Add icon are disabled.
7.
Highlight the block below the stage box and click the Edit icon. The first time
you create a task participant, the box is labeled <Edit Participant>.
or
b.
29-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Edit Participant Type dialog appears. This dialog enables you to select a
specific participant type.
2.
From the Type list, select a participant type shown in Figure 2921.
Figure 2921
3.
Table 296
Participant
Type
Single
Parallel
Serial
FYI
Type List
Participant Types
For a Description of this
Participant Type, See...
29-19
Figure 2923 Edit Participant Type Single Type (Expanded Advanced Section)
29-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
See...
Participant List
29-21
request below $5000 is sent to a manager for approval. However, if the purchase
order request exceeds $5000, the request is sent to the manager of the manager for
approval. Two key features of business rules are facts and action types, which are
described in Section 29.5.2, "How to Specify Advanced Task Routing Using
Business Rules."
When you select a participant type, a dialog box enables you to choose an option for
building your list of task participant assignees (users, groups, or application roles), as
shown in Figure 2924. The three selections described above are available: Names and
expressions, Management Chain, and Rule-based.
Figure 2924 Build a List of Participants
After selecting an option, you dynamically assign task participant assignees (users,
groups, or application roles) and a data type, as shown in Figure 2925.
29-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2925
1.
2.
Select Let participants manually claim the task. If you select this option, then
the task is assigned to all participants in the list. An individual user from the
task assignees can then manually claim the task to work on it.
Select Auto-assign to a single list, select User, Group, or Application Role,
then select an assignment pattern.
To find out more about each assignment pattern, and to select and configure it,
click Assignment Pattern. The Assignment Pattern dialog box appears.
Figure 2926 shows an example of an Assignment Pattern dialog box.
29-23
29-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2927
4.
Click the Add icon and select a user, group, or application role as a task
participant.
The Identification Type column of the Participant Names table displays your
selection of user, group, or application role.
5.
6.
In the Data Type column, click your selection to invoke a dropdown list to assign
a value:
By Name: If your identification type is a user or group, click the Browse icon
(the dots) on the right to display a dialog for selecting a user or group
configured through the identity service. The identity service enables the
lookup of user properties, roles, and group memberships. User information is
obtained from an LDAP server such as Oracle Internet Directory. You can use
wild cards (*) to search for IDs.
If your selection is an application role, click the Browse icon to display the
Select an Application Role dialog for selecting an application role. To search
for application roles, you must first create a connection to the application
server. When searching, you must specify the application name to find the
name of the role. The task definition can refer to only one application name.
You cannot use application roles from different applications as assignees or
task owners.
By Expression: For a user, group, or application role, click the Browse icon to
dynamically select a task assignee in the Expression Builder dialog. Use the
bpws:getVariableData(...) expression or the ids:getManager()
XPath function.
To manually enter a value, click the field in the Value column and specify a value.
29.4.3.1.2
29-25
Statically and dynamically assigning task participants, see Section 27.2.1.2, "Static,
Dynamic, and Rule-Based Task Assignment."
Management chains, see Section 29.4.3.1, "Creating a Single Task Participant List."
1.
2.
Select Let participants manually claim the task. If you select this option, then
the task is assigned to all participants in the list. An individual user from the
task assignees can then manually claim the task to work on it.
Select Auto-assign to a single list, select User, then select an assignment
pattern.
To find out more about each assignment pattern, and to select and configure it,
click Assignment Pattern. The Assignment Pattern dialog box appears.
Figure 2926 shows an example of an Assignment Pattern dialog box.
When you specify an application server connection in the Application Server
field, the assignment patterns are loaded into the Assignment Pattern list.
When you select one of the patterns from the Assignment Pattern list, a
description of your selection appears in the text box.
If you want the assignment pattern to consider all types of tasks, then select
Use tasks of all types to evaluate pattern criteria. Otherwise, the pattern
considers only this task type when determining the selected user. For example,
to assign a vacation request task to the least busy user, and you select Use
tasks of all types to evaluate pattern criteria, then all assigned tasks are taken
into consideration when determining the least busy user. If you do not select
Use tasks of all types to evaluate pattern criteria, then only assigned vacation
request tasks are considered when determining the least busy user.
A particular pattern may enable you to specify input parameters that control
how the pattern is evaluated. For example, as shown in Figure 2926, the Most
Productive pattern enables you to specify the Time Period (in days) over
which the productivity is calculated. Input values can be static, or can be
dynamically set by using an XPath expression. Not all patterns accept
parameters.
3.
29-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2928
4.
See Step 4 through Step 7 of Section 29.4.3.1, "Creating a Single Task Participant
List" for instructions on assigning a user, group, or application role to a list in the
Starting Participant table.
5.
In the Top Participant list, select a method for assigning the number of task
participant levels:
6.
By Title: Select the title of the last (highest) approver in the management
chain.
XPath: Select to dynamically enter a top participant through the Expression
Builder dialog.
In the Number of Levels list, select a method for assigning a top participant:
By Number: Enter a value for the number of levels in the management chain
to include in this task. For example, if you enter 2 and the task is initially
assigned to user jcooper, both the user jstein (manager of jcooper) and
the user wfaulk (manager of jstein) are included in the list (apart from
jcooper, the initial assignee).
XPath: Select to dynamically enter a value through the Expression Builder
dialog.
29.4.3.1.3
29-27
A ruleset provides a unit of execution for rules and for decision tables. In addition,
rulesets provide a unit of sharing for rules; rules belong to a ruleset. Multiple rulesets
can be executed in order. This is called rule flow. The ruleset stack determines the
order. The order can be manipulated by rule actions that push and pop rulesets on the
stack. In rulesets, the priority of rules applies to specify the order of firing of rules in
the ruleset. Rulesets also provide an effective date specification that identifies that the
ruleset is always active, or that the ruleset is restricted based on a time and date range,
or a starting or ending time and date.
The method by which you create a ruleset is based on how you access it. This is
described in the following section.
Note:
Rules define parameters of a specific list builder (such as Names and Expressions
or Management Chain). In this case, the task routing pattern is modeled to use a
specific list builder. In the list builder, the parameters are listed as coming from
rules. Rules return the list builder of the same type as the one modeled in Oracle
JDeveloper.
1.
From the Build a list of participants using list, select Names and expressions
or Management Chain.
2.
3.
29-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2929
4.
Rulesets
Select Let participants manually claim the task. If you select this option,
then the task is assigned to all participants in the list. An individual user
from the task assignees can then manually claim the task to work on it.
29-29
criteria, then only assigned vacation request tasks are considered when
determining the least busy user.
A particular pattern may enable you to specify input parameters that control how the pattern is evaluated. For example, as shown in Figure 2926,
the Most Productive pattern enables you to specify the Time Period (in
days) over which the productivity is calculated. Input values can be static,
or can be dynamically set by using an XPath expression. Not all patterns
accept parameters.
5.
Click OK.
Rules define the list builder and the list builder parameters. In this case, the list
itself is built using rules. The rules define the list builder and the parameters.
1.
2.
3.
Select Let participants manually claim the task. If you select this option,
then the task is assigned to all participants in the list. An individual user
from the task assignees can then manually claim the task to work on it.
29-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click OK.
Both options create a rule dictionary, if one is not already created, and preseed several
rule functions and facts for easy specifications of the participant list. In the rule
dictionary, the following rule functions are seeded to create participant lists:
CreateResourceList
CreateManagementChainList
The Task fact is asserted by the task service for basing rule conditions.
After the rule dictionary is created, the Oracle Business Rules Designer is displayed.
1.
Model your rule conditions. In the action part, call one of the above functions to
complete building your lists. Figure 2931 provides details.
The parameters for the rule functions are similar to the ones in Oracle JDeveloper
modeling. In addition to the configurations in Oracle JDeveloper, some additional
options are available in the Oracle Business Rules Designer for the following
attributes:
29-31
If multiple rules are fired, the list builder created by the rule with the highest
priority is selected.
2.
3.
29-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
29-33
Figure 2934 Edit Participant Type Parallel Type (Upper Section of Dialog)
Figure 2935 Edit Participant Type Parallel Type (Lower Section of Dialog)
29-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 298
See...
Vote Outcome
Participant List
From the list in the Voted Outcomes column, select an outcome for the task (for
example, Any, ACCEPT, REJECT, or any other outcome specified in
Section 29.2.4, "How to Specify a Task Outcome").
The Any outcome enables you to determine the outcome dynamically at runtime.
For example, if you select Any and set the outcome percentage to 60, then at
runtime, whichever outcome reaches 60% becomes the final voted outcome. If 60%
of assignees vote to reject the outcome, then it is rejected.
3.
From the list in the Outcome Type column, select a method for determining the
outcome of the final task.
4.
From the list in the Value column, specify a value based on your selection in Step
3.
If you selected By Expression, click the Browse icon to the right of the field to
display the Expression Builder dialog for creating an expression.
If you selected By Percentage, enter a percentage value required for the
outcome of this task to take effect (for example, a majority vote (51) or a
unanimous vote (100)). For example, assume there are two possible outcomes
(ACCEPT and REJECT) and five subtasks. If two subtasks are accepted and
three are rejected, and the required acceptance percentage is 50%, the outcome
of the task is rejected. Figure 2936 provides details.
This functionality is nondeterministic. For example, selecting a percentage of
30% when there are two subtasks does not make sense.
29-35
5.
6.
In the Default Outcome list, select the default outcome or enter an XPath
expression for this task to take effect if the consensus percentage value is not
satisfied. This happens if there is a tie or if all participants do not respond before
the task expires. Seeded and custom outcomes that you entered in the Outcomes
dialog in Section 29.2.4, "How to Specify a Task Outcome" display in this list.
7.
8.
Rule-based links
For information about creating these lists of participants, see section Section 29.4.3.1,
"Creating a Single Task Participant List."
29-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
For more information about setting the global escalation and renewal policies in the
Deadlines section of the Human Task Editor, see Section 29.7, "Escalating, Renewing,
or Ending the Task."
29-37
Figure 2938 Edit Participant Type Serial Type (Expanded Advanced Section)
See...
Participant List
29-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
See...
Rule-based lists
See section Section 29.4.3.1, "Creating a Single Task Participant List" for instructions on
creating these lists of participants.
3.
Note:
For more information about setting the global escalation and renewal policies in
the Deadlines section of the Human Task Editor, see Section 29.7, "Escalating,
Renewing, or Ending the Task."
29-39
29-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2939
Rule-based lists
See section Section 29.4.3.1, "Creating a Single Task Participant List" for instructions on
creating these lists of participants.
29-41
This displays the Configure Assignment dialog shown in Figure 2941 for specifying a
method for routing your task through the workflow.
Figure 2941 Configure Assignment
29-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 2910
Complete task when A participant in a task can accept or reject it, Section 29.5.1.2, "Stopping Routing of a
a participant chooses: thus ending the workflow without the task Task to Further Participants"
being sent to any other participant. For
<outcome>
example, a manager rejects a purchase order,
meaning that purchase order is not sent to
their manager for review.
Enable early
completion in
parallel subtasks
Complete parent
tasks of early
completing subtasks
Assignment tab
A participant is assigned a failed task for the Section 29.5.4, "How to Configure the
purposes of recovery.
Error Assignee"
29-43
Select Route task to all participants, in order specified from the list shown in
Figure 2942.
3.
Select the Allow all participants to invite other participants checkbox for this task
assignee to invite other participants into the workflow before routing it to the next
assignee in this workflow.
Do not add adhoc assignees either above or below a FYI
participant.
Note:
29-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Select Route task to all participants, in order specified from the list.
3.
Outcomes
If outcomes are specified, any time the selected task outcome occurs, the task
completes. If both outcome and routing condition are specified, the workflow
service performs a logical OR operation on the two.
4.
Select appropriate outcomes and click the > button, as shown in Figure 2943. To
select all, click the >> button.
Figure 2943
5.
To the right of the Routing Condition field, click the icon to display the
Expression Builder dialog for dynamically creating a condition under which to
complete this task early. For example, if a user submits a business trip expense
report that is under a specific amount, no approval is required by their manager.
An early completion XPath expression is not evaluated until at least one user has
acted upon the task.
6.
29-45
7.
To enable early completion of parent tasks, click Complete parent tasks of early
completing subtasks. For more information, see Section 29.5.1.4, "Completing
Parent Subtasks of Early Completing Subtasks."
8.
For example, assume there are two parallel subgroups, each in separate stages. One
group acts upon lines of a purchase order. The other group acts upon headers of the
same purchase order. If participant ApproveLines.Participant2 of the first group
rejects a line, all other task participants in the first group stop acting upon tasks.
However, the second parallel group continues to act upon headers in the purchase
order. In this scenario, the entire task does not complete early. Figure 2944 provides
details.
Figure 2944 Early Completion of Parallel Subtasks
For example, assume there are two parallel subgroups, each in separate stages, as
shown in Figure 2944. One group acts upon lines of a purchase order. The other
group acts upon headers of the same purchase order. If participant
29-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ApproveLines.Participant2 of the first group rejects a line, all other task participants
in the first group stop acting upon tasks. In addition, the second parallel group stops
acting upon headers in the purchase order. In this scenario, the entire task completes
early.
After a routing slip task participant sets the outcome of the task
This action enables you to override the standard task routing slip method described in
Section 29.5.1, "How to Route Tasks to All Participants in the Specified Order" and
build complex routing behavior into tasks.
Using Oracle Business Rules, you define a set of rules (called a ruleset) that relies on
business objects, called facts, to determine which action to take.
29.5.2.2 Facts
A fact is an object with certain business data. Each time a routing slip assignee sets the
outcome of a task, instead of automatically routing the task to the next assignee, the
task service performs the following steps:
Rules can test values in the asserted facts and specify the routing behavior by setting
values in a TaskAction fact type.
Table 2911 describes the fact types asserted by the task service.
Table 2911
Fact Type
Description
Task
This fact contains the current state of the workflow task instance. All task
attributes can be tested against it. The task fact also contains the current
task payload. This fact enables you to construct tests against payload
values and task attribute values.
29-47
Table 2911
Fact Type
Description
PreviousOutco
me
This fact describes the previous task outcome and the assignee who set the
outcome. The previous outcome fact contains the following attributes:
This fact is not intended for writing rule tests against it. Instead, it is
updated by the ruleset, and returned to the task service to indicate how
the task should be routed. Rules should not directly update the
TaskAction fact. Instead, they should call one of the RL functions
described in Section 29.5.2.3, "Action Types." These functions handle
updating the TaskAction fact with the appropriate values.
TaskAction
Some fact types can only be used in workflow routing rules, while others can only be
used in workflow participant rules. Table 2912 describes where you can use each
type.
Table 2912
Fact Type
Task
Yes
Yes
PreviousOutcome
Yes
No
TaskAction
Yes
No
Lists
No
Yes
RoutingSlipObjectFact No
ory
Yes
No
Yes
ManagementChainListTy No
pe
Yes
ResourceType
No
Yes
ParameterType
No
Yes
AutoActionType
No
Yes
ResponseType
No
Yes
ResourceListType
29-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
forward, you must add a call GO_FORWARD(TaskAction) to the action part of the
rule.
Each time a state machine routing rule is evaluated, the rule takes one of the actions
shown in Table 2913:
Table 2913
Action
Description
Parameters
GO_FORWARD
None
PUSHBACK
None
COMPLETE
ESCALATE
None
If the total amount of the expense request is less than $100, approval is only
required from one of the participants. Otherwise, it must be approved by all three.
If an expense request is rejected by any of the participants, it must be returned to
the previous participant for re-evaluation. If it is rejected by the first participant,
the expense request is rejected and marked as completed.
This behavior is implemented using the following rules. When a rule dictionary is
generated for advanced routing rules, it is created with a template rule that
implements the default GO_FORWARD behavior. You can edit this rule, and make copies
of the template rule by right-clicking and selecting Copy Rule in the Oracle Business
Rules Designer.
29-49
If the amount is greater than $100 and the previous assignee approved the task, it is
not necessary to provide a rule for routing a task to each of the assignees in turn. This
is the default behavior that is reverted to if none of the rules in the ruleset are
triggered:
29-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Base dictionary
Custom dictionary
For more information about customizations, see Chapter 46, "Customizing SOA
Composite Applications."
3.
To the right of Rules Dictionary, click the Edit icon, as shown in Figure 2948.
Figure 2948
This starts the Oracle Business Rules Designer with a preseeded repository
containing all necessary fact definitions, as shown in Figure 2949. A decision
service component is created for the dictionary, and is associated with the task
service component.
29-51
4.
Define state machine routing rules for your task using Oracle Business Rules.
This automatically creates a fully-wired decision service in the human task and the
associated rule repository and data model.
For more information about business rules, see the following documentation:
Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules
Note:
3.
29-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2950
4.
In the Class Name field, enter the fully qualified class file name (for example, the
org.mycompany.tasks.RoutingService class name). This class must
implement the following interface:
oracle.bpel.services.workflow.task.IAssignmentService
5.
Add name and pair value parameters by name or XPath expression that can be
passed to the external service, as shown in Table 2914.
Table 2914
External Routing
Field
Description
By Name
Enter a name in the Name field and a value in the Value field.
By Expression
29-53
6.
Click the Add icon to add additional name and pair value parameters.
Invalid XPath expressions that are related to assignees and expiration duration
Evaluating dynamic assignment rules. The task is not currently in error, but is still
left as assigned to the current user and is therefore recoverable.
Dynamic assignment cyclic assignment (for example, user A > user B > user A).
The task is not currently in error, but is still left as assigned to the last user in the
chain and is therefore recoverable.
The following errors are not recoverable. In these cases, the task is moved to the
terminating state ERRORED.
Invalid XPath and values for parallel default outcome and percentage values
During modeling of workflow tasks, you can specify error assignees for the workflow.
If error assignees are specified, they are evaluated and the task is assigned to them. If
no error assignee is specified at runtime, an administration user is discovered and is
assigned the alerted task. The error assignee can perform one of the following actions:
Ad hoc route
Route the task to the actual users assigned to the task. Ad hoc routing allows the
task to be routed to users in sequence, parallel, and so on. Note: Do not add adhoc
assignees either above or below a FYI participant.
Reassign
Reassign the task to the actual users assigned to this task
Error task
Indicate that this task cannot be rectified.
If there are any errors in evaluating the error assignees, the task is marked as being in
error.
This dialog enables you to specify the users or groups to whom the task is assigned if
an error in assignment has occurred.
29-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Figure 2952
4.
Click the Add icon and select a user, group, or application role to participate in
this task.
The Identification Type column of the Starting Participant table displays your
selection of user, group, or application role.
5.
See Step 5 through 7 of Section 29.4.3.1, "Creating a Single Task Participant List"
for instructions on selecting a user, group, or application role.
6.
If you are using parallel participant types, you can specify where to store the
subtask payload with the following options.
b.
c.
Click SharePayloadAcrossAllParallelApprovers.
d.
29-55
All task participants share the same payload (better performance and less
storage space)
The payload for the subtasks is stored in their root task. This situation means
that the payload of the root task is shared across all its subtasks. Internally, this
option provides better performance and storage space consumption. Less
storage space is consumed because the payload of the root task is shared
across all its subtasks.
7.
Click OK.
For more information about users, groups, or application roles, see Section 27.2.1.1.3,
"Participant Assignment."
29.6.1 How to Specify WordML and Other Style Sheets for Attachments
To specify WordML style sheets for attachments:
1. In the Stylesheet for Attachments list of the Presentation section, select one of the
following options:
2.
Word ML: This option dynamically creates Microsoft Word documents for
sending as email attachments using a WordML XSLT style sheet. The XSLT
style sheet is applied on the task document.
Other: This option creates email attachments using an XSLT style sheet. The
XSLT style sheet is applied on the task document.
29-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Displaying the value for task outcomes in plain text or with the message(key)
format.
Making email notification messages available in different languages. At runtime,
you specify the hwf:getTaskResourceBundleString(taskId, key,
locale?) XPath extension function to obtain the internationalized string from
the specified resource bundle. The locale of the notification recipient can be
retrieved with the function
hwf:getNotificationProperty(propertyName).
Resource bundles can also simply be property files. For example, a resource bundle
that configures a display name for task outcomes can look as follows:
APPROVE=Approve
REJECT=Reject
2.
In the Resource Name field, enter the name of the resource used in the resource
bundle. This should be a .properties-based resource bundle file.
3.
In the Resource Location field, click the Search icon to select the JAR or ZIP
resource bundle file to use. The resource bundle is part of your system archive
(SAR) file.
If the resource bundle is outside of the composite project, you are prompted to
place a local copy in SCA-INF/lib.
If the resource bundle file is not in the composite class loader (directly under
SCA-INF/classes or in a JAR file in SCA-INF/lib), you must specify its
location. For example, if the resource bundle is accessible from a location outside
of the composite class loader (for example, an HTTP location such as
29-57
29-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If there is no expiration specified at either the participant level or this routing slip
level, then that task has no expiration duration.
If expiration duration is specified at any level of the participants, then for that
participant, the participant expiration duration is used. However, the global expiration
duration is still used for the participants that do not have participant level expiration
duration. The global expiration duration is always decremented by the time elapsed in
the task.
The policy for interpreting the participant level expiration for the participants is
described as follows:
Serial
Each assignment in the management chain gets the same expiration duration as
the one specified in the serial. The duration is not for all the assignments resulting
from this assignment. If the task expires at any of the assignments in the
management chain, the escalation and renewal policy is applied.
Parallel:
The expiration duration that is left on the task if it was specified at the
routing slip level.
Note:
Specify the maximum time period for the task to remain open.
29-59
29-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
the task is escalated to whoever you have defined. When a task has been escalated the
maximum number of times, it stops escalating. An escalated task can remain in a user
inbox even after the task has expired.
To escalate a task policy:
1. In the dropdown list of the Deadlines section, select Escalate after, as shown in
Figure 2959.
2.
Specify the following additional values. When both are set, the escalation policy is
more restrictive.
The escalation policy specifies the number of times the task can be escalated on
expiration and the renewal duration. In Figure 2959, when the task expires, it is
escalated at most three times. It does not matter if the task expired at the
LoanAgentGroup participant or the Supervisor participant.
Figure 2959
This implementation must be available in the class path for the server.
2.
3.
29-61
4.
Right-click soa-infra, and select SOA Administration > Workflow Config > Task
tab.
The Workflow Task Service Properties page appears.
5.
6.
In the Custom Escalation Java Class field of the Deadlines section, enter the
function name as defined in the Workflow Task Service Properties page for the
escalation rule.
For more information, see Section 34.3.3, "Custom Escalation Function."
1.
2.
The due date can be set on both the task (using the Create ToDo Task dialog in
Oracle BPM Worklist) and in the .task file (using the Human Task Editor).
This is to allow to-do tasks without task definitions to set a due date during
initiation of the task. A due date that is set in the task (a runtime object)
overrides a due date that is set in the .task file.
In the task definition, the due date can only be specified at the global level,
and not for each participant.
If the due date is set on the task, the due date in the .task file is ignored.
If the due date is not set on the task, the due date in the .task file is
evaluated and set on the task.
If there is no due date on either the task or in the .task file, there is no due
date on the task.
29-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
For more information, see Section 32.3.4, "How To Create a ToDo Task."
Note:
Figure 2960
See...
Task Status
Recipient
Notification Header
For information about the notification service, see Section 34.2, "Notifications from
Human Workflow."
2.
In the Notification section, click the Advanced tab. Figure 2961 provides details.
29-63
Instructions for configuring the following subsections of the Advanced tab of the
Notification section are listed in Table 2916.
Table 2916
See...
Reminders
Encoding
Show worklist URL in notifications Section 29.8.6, "How to Display the Oracle BPM Worklist
URL in Notifications"
Make notifications actionable
In the Task Status column, click a type to display the complete list of task types:
Alerted
29-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When a task is in an alerted state, you can notify recipients. However, none of
the notification recipients (assignees, approvers, owner, initiator, or reviewer)
can move the task from an alerted state to an error state; they only receive an
FYI notification of the alerted state. The owner can reassign, withdraw, delete,
or purge the task, or ask the error assignee to move the task to an error state if
the error cannot be resolved. Only the error assignee can move a task from an
alerted state to an error state.
You configure the error assignee on the Assignment tab of the Configure
Assignment dialog under the Task will go from starting to final participant
icon in the Assignment section. For more information, see Section 29.5.4,
"How to Configure the Error Assignee."
Assign
When the task is assigned to users or a group. This captures the following
actions:
Task is renewed
Task is delegated
Task is reassigned
Task is escalated
Complete
Error
Expire
Request Info
Resume
Suspend
Update
Task is updated
Update Outcome
Withdraw
3.
Any action not covered in the above task types. This includes acquiring a
task.
29-65
4.
In the Recipient column, click an entry to display a list of possible recipients for
the notification message:
Assignees
The users or groups to whom the task is currently assigned.
Initiator
The user who created the task.
Approvers
The users who have acted on the task up to this point. This applies in a serial
participant type in which multiple users have approved the task and a
notification must be sent to all of them.
Owner
The task owner
Reviewer
The user who can add comments and attachments to a task.
For more information, see Section 34.2.5, "How to Configure the Notification
Channel Preferences."
In the Notification Header column, click the Edit icon to modify the default
notification message.
The Edit Notification Message dialog shown in Figure 2962 appears.
This message applies to all the supported notification channels: email, voice,
instant messaging, and SMS. Email messages can also include the worklist task
detail defined in this message. The channel by which the message is delivered is
based upon the notification preferences you specify.
29-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
For more information about notification preference details, see Section 34.2,
"Notifications from Human Workflow."
3.
If you selected to remind the assignee one, two, or three times, select the interval
between reminders, and whether to send the reminder before or after the
assignment.
3.
29-67
2.
Select the Show worklist URL in notifications checkbox to display the Oracle
BPM Worklist URL in email notification messages. If this checkbox is not selected,
the URL is not displayed.
Select Make notification actionable. This action enables you to perform task
actions through email.
FYI tasks are not actionable and cannot be acknowledged from
email messages.
Note:
For more information about additional configuration details, see Section 34.2.7,
"How to Send Actionable Messages."
For more information about configuring outbound and inbound emails, see Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
From the Group notification configuration list, select one of the following
options.
When selected, this sends individual emails with a separate task form
based on the language locale.
When not selected, this sends individual emails and reuses (shares) the
task form.
29-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Since all (or a subset of) users receive the same email, the users in
the group or application role are expected to have the same
privilege. This ensures that the user does not see task details to
which they are not entitled.
When sending one email to all users, the maximum number of
characters allowed in the address field is 2000. If the limit is
exceeded, email is sent to only those user addresses contained
within the maximum limit.
3.
29-69
Note: Task content access rules and task actions access rules exist
independently of one another.
Any attribute configured with access rules declines any permissions for roles not
configured against it. For example, assume you configure the payload to be read
by assignees. This action enables only assignees and nobody else to have read
permissions. No one, including assignees, has write permissions.
Any attribute not configured with access rules has all permissions.
If any payload message attribute is configured with access rules, any
configurations for the payload itself are ignored due to potential conflicts. In this
case, the returned map by the API does not contain any entry for the payload.
Write permissions automatically provide read permissions.
If only a subset of message attributes is configured with access rules, all message
attributes not involved have all permissions.
Only comments and attachments have add permissions.
Write permissions on certain attributes are meaningless. For example, write
permissions on history do not grant or decline any privileges on history.
The following date attributes are configured as one in the Human Task Editor. The
map returned by TaskMetadataService.getVisibilityRules() contains
one key for each. Similarly, if the participant does not have read permissions on
DATES, the task does not contain any of the following task attributes:
START_DATE
END_DATE
ASSIGNED_DATE
SYSTEM_END_DATE
CREATED_DATE
EXPIRATION_DATE
ALL_UPDATED_DATE
The following assignee attributes are configured as one in the Human Task Editor.
The map returned by TaskMetadataService.getVisibilityRules()
contains one key for each of the following. Similarly, if the participant does not
have read permissions on ASSIGNEES, the task does not contain any of the
following task attributes:
ASSIGNEES
ASSIGNEE_USERS
ASSIGNEE_GROUPS
ACQUIRED_BY
29-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ITaskMetadataService.TASK_VISIBILITY_ATTRIBUTE_PAYLOAD_
MESSAGE_ATTR_PREFIX (PAYLOAD).
An application can also create pages to display or not display task attributes based on
the access rules. This can be achieved by retrieving a participants access rules by
calling the API on
oracle.bpel.services.workflow.metadata.ITaskMetadataService.
Example 291 provides details.
Example 291
API Call
For more information about this method, see Oracle Fusion Middleware Workflow
Services Java API Reference for Oracle SOA Suite.
3.
Select the task content for which to specify access privileges, as shown in
Figure 2963.
Figure 2963
4.
Assign privileges (read, write, or no access) to users to act upon task content. A
user cannot be assigned a privilege above their highest level. For example, an
ADMIN user cannot be assigned write access on the PAYLOAD task content.
Table 2917 shows the maximum privilege each user has on task content.
29-71
Table 2917
Task Content
Assignees
--
Attachments
Admin, Approvers
Comments
Admin, Approvers
Dates
--
Flexfields
History
--
Payload
Reviewers
--
Payload elements
For example, if you accept the default setting of ASSIGNEES, CREATOR, and
OWNER with write access, ADMIN, APPROVERS, and REVIEWERS with read
access, and PUBLIC with no access to the PAYLOAD task content, the dialog
appears as shown in Figure 2963.
5.
Select the method for displaying task content in this dialog. Choosing the
currently unselected option causes all settings to reset to their default values.
Fine grained
Displays the content as individual elements (for example, displays all
payloads (such as p1, p2, and p3) and all reviewers assigned to this task (such
as jstein, wfaulk, and cdickens).
Access rules are always applied on top of what the system
permits, depending on who is performing the action and the current
state of the task.
Note:
3.
Select the task action for which to specify users, as shown in Figure 2964.
29-72 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2964
4.
5.
Select the method for displaying task actions in this dialog. Choosing the currently
unselected option causes all settings to reset to their default values.
Fine grained
Displays the content actions as individual elements. (for example, displays all
approvals or rejections).
Note:
From the Signature Policy list, select Configure Policy, as shown in Figure 2965.
29-73
3.
No signature required
Participants can send and act upon tasks without providing a signature. This
is the default policy.
Password required
Participants specify a signature before sending tasks to the next participant.
Participants must reenter their password while acting on a task. The password
is used to generate the digital signature. A digital signature authenticates the
identity of the message sender or document signer. This ensures that the
original content of the sent message is unchanged.
Your name
A serial number
Expiration dates
A copy of the certificate holder's public key (used for encrypting messages
and digital signatures)
The CA names and CA CRL and URLs of the issuing authorities must be
configured separately.
4.
Click OK.
For more information, see Section 34.1.10, "Evidence Store Service and Digital
Signatures."
29-74 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Click AddTrustedCA.
5.
In the Value fields for CaName and CaURL, specify appropriate values.
6.
Click Invoke.
7.
Click Return.
You must validate these values before using them.
Note:
29-75
3.
Click the Add icon to add name and value pairs for the property map passed to
invoke the callback.
4.
Click OK.
1.
OnAssigned
Select if the callback class must be called on any assignment change, including
standard routing, reassignment, delegation, escalation, and so on. If a callback
is required when a task has an outcome update (that is, one of the approvers
in a chain approves or rejects the task), this option must be selected.
OnUpdated
Select if the callback class must be called on any update (including payload,
comments, attachments, priority, and so on).
OnCompleted
Select if the callback class must finally be called when the task is completed
and control is about to be passed to the initiator (such as the BPEL process
initiating the task).
OnStageCompleted
Select if the callback class must be called to enable business event callbacks in
a human workflow task. When the event is raised, it contains the name of the
completed stage, the outcome for the completed stage, and a snapshot of the
task when the callback is invoked.
OnSubtaskUpdated
Select if the callback class must be called on any update (including payload,
comments, attachments, priority, and so on) on a subtask (one of the tasks in a
parallel-and-parallel scenario).
29-76 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If your Oracle JDeveloper installation is updated to include both the BPEL and
BPM extensions, then the following content callbacks are also available for
selection:
Comments Callback
Select if the callback class must be called to store the comments in a schema
other than the WFCOMMENT column. The callback class must implement the
oracle.bpel.services.workflow.callback.NotesStore interface.
Validation Callback
Select if the callback class must be called to validate either the task or payload
before updating, approving, and so on.
2.
In the Java Class column, click the empty field to enter a value. This value is the
complete class name of the Java class that implements
oracle.bpel.services.workflow.task.IRoutingSlipCallback.
Figure 2966 provides details.
29-77
3.
Click OK.
3.
Select the Trigger Workflow Event checkbox. This action disables the Java Class
column, as shown in Figure 2967. Each callback, such as OnAssigned,
corresponds to a business event point. When a business event is fired, the event
details contain the task object and a set of properties that are populated based on
the context of the event being fired.
29-78 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 2967
Note:
4.
5.
In the Template list during Oracle Mediator creation, select Subscribe to Events.
6.
7.
To the right of the Event Definition field, click the Browse icon to select the EDL
file.
The SOA Resource Browser dialog appears.
8.
9.
The Event Chooser is now populated with EDL file business events available for
selection.
12. In the Event field, select the event to which to subscribe. Figure 2968 provides
details.
29-79
You can have multiple human tasks available for subscribing to the event. For
example, assume you performed the following:
Configured a human task named TaskA to subscribe to the event (for example,
OnAssigned)
Configured a human task named TaskB to subscribe to the same event
To distinguish between events for TaskA and TaskB and ensure that an event is
processed only by the intended Oracle Mediator, you can add a static routing
filter:
xpath20:compare(med:getComponentName(), 'TaskA')
This only invokes this routing when the sending component is TaskA.
13. If the EDL file was not selected from the file-based MDS connection, accept to
import the dependent XSD files when prompted, and click OK. If the EDL file was
selected from the file-based MDS connection, you are not prompted.
The Oracle Mediator service component is now populated with the business event
to which to subscribe. You can also subscribe to other business events defined in
the same EDL file now or at a later time.
See the following documentation for additional details about business events and
callbacks:
Chapter 41, "Using Business Events and the Event Delivery Network" for specific
details about business events
Sample workflow-116-WorkflowEventCallback, which is available with the Oracle
SOA Suite samples.
29-80 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Click OK.
This creates the while, pick, and onMessage branch of a pick activity for BPEL callback
customizations inside the task scope activity.
For more information about specifying task and routing customizations, see
Section 28.4.5.1, "Invoking BPEL Callbacks."
Click OK.
29-81
29-82 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
30
30
Section 30.2, "Associating the Task Flow with the Task Service"
Section 30.5, "Refreshing Data Controls When the Task XSD Changes"
Section 30.11, "Reusing the Task Flow Application with Multiple Human Tasks"
For information about troubleshooting human workflow issues, see section "Human
Workflow Troubleshooting" of Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
The task form is a Java Server Page XML (.jspx) file that you create in the Oracle
JDeveloper designer where you created the SOA composite containing the human
task. You must set the page encoding to UTF-8 in Oracle JDeveloper before creating
the Java Server Page XML file. You can do this in Oracle JDeveloper by choosing Tools
> Preferences > Environment, and selecting UTF-8 using the Encoding dropdown list.
Figure 301 shows the Oracle JDeveloper ADF Task Flow Based on Human Task
option where you start creating a task form.
Figure 301 ADF Task Flow Based on a Human Task, in Oracle JDeveloper
30.1.1 What You May Need to Know About Task Forms: Time Zone Conversion
Time zone conversion is not automatic for datetime elements in the task payload when
a task form is created. You must add the <af:convertDateTime> tag to enable time
zone conversion on a datetime element. See any standard task header time label for an
example. Example 301 shows a sample header.
Example 301
<af:outputText value="#{bindings.createdDate.inputValue}"
id="ot15">
<f:convertDateTime type="#{pageFlowScope.dt}"
timeZone="#{pageFlowScope.tz}"
dateStyle="#{pageFlowScope.df}"
timeStyle="#{pageFlowScope.tf}"/>
</af:outputText>
30-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
30.3.1 How To Create an ADF Task Flow from the Human Task Editor
The.task file that specifies the human task is easily associated with the task flow
when the two are located in the same application.
To create an ADF task flow for a human task:
1. Open the BPEL process within the SOA composite application.
2.
3.
In the .task tab (shown in Figure 303), click Create Form and select
Auto-Generate Task Form.
Figure 303 Creating a Task Flow from the Human Task Editor
4.
Provide a project name and a directory path (or use the default) and click OK.
The taskDetails1_jspx icon appears in the designer, as shown in Figure 304.
30-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The task flow and task form are complete and ready to be deployed.
Click OK.
3.
Provide an application name and directory information (or accept the default), and
click Finish.
4.
5.
6.
Select ADF Task Flow Based on Human Task and click OK.
7.
In the SOA Resource Browser, find and select the .task file where you defined
the human task and click OK.
a.
If the human task is in the same application as the task definition, then click
File to use the file browser to navigate to the .task file, which is typically in
the composite directory.
b.
c.
If the .task file is located within the current application, then click
Application.
This displays the Create Task Flow dialog and creates the data controls.
8.
In the Create Task Flow dialog, accept the defaults and click OK.
The taskDetails1_jspx icon appears in the designer, as shown in Figure 304. The
task flow has a view, a control flow, and a task return.
Section 30.4.4, "How To Create a Task Form Using the Complete Task with Payload
Drop Handler."
or
Section 30.4.5, "How To Create Task Form Regions Using Individual Drop
Handlers."
30.3.3 What Happens When You Create an ADF Task Flow Based on a Human Task
With an ADF task flow based on a human task, the task flow application has task data
controls that wire the task form with the workflow services. The data controls provide
the following:
The human task-aware data controls appear in the Data Controls panel of the Oracle
JDeveloper Application Navigator, as shown in Figure 305.
30-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The data controls for the task (represented by the Task node in Figure 305) have drop
handlers to render the task form. See Section 30.4, "Creating a Task Form," for more
information.
30.3.4 What You May Need to Know About Having Multiple ADF Task Flows That
Contain the Same Element with Different Meta-attributes
You must create separate ADF task flows if both contain the same element, but with
different meta-attributes specified (for example, editable and noneditable).
For example, assume you perform the following tasks.
1.
While creating the task form, the wizard provides you with the option to define
the ADF table for payload Employee.
2.
3.
4.
5.
6.
7.
Select the Enter Bank Details task (for EnterBankDetails.task). In the task form, the
Insert New and Delete buttons are still present for Employee data, even though it
is a noneditable payload.
8.
Ensure that you create two separate ADF task flow applications because both contain
the Employee element, but with different meta-attributes specified (editable and
noneditable).
For how to use the Auto-Generate Task Form option, see Section 30.4.1, "How To
Create an Autogenerated Task Form."
For how to use the Launch Task Form Wizard option, see Section 30.4.3, "How To
Create a Task Form Using the Custom Task Form Wizard."
For how to use human task drop handlers, see the following:
Section 30.4.4, "How To Create a Task Form Using the Complete Task with
Payload Drop Handler"
Section 30.4.5, "How To Create Task Form Regions Using Individual Drop
Handlers"
30-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
From the .task editor, click Create Form and select Auto-Generate Task Form, as
shown in Figure 306.
4.
Provide a project name and a directory path (or use the default) and click OK.
The default form opens in the taskDetails1.jspx tab. The default form for
ApprovalHumanTask is shown in Figure 307.
30.4.2 How to Register the Library JAR File for Custom Page Templates
You can optionally specify your own custom page templates in the Custom Task Form
wizard. As described in Section 30.4.3, "How To Create a Task Form Using the Custom
Task Form Wizard," you select Custom Page Template in the Name and Definition
page of the Custom Task Form Wizard and specify the library JAR file name and the
path to the .jspx template file within the JAR file.
As a prerequisite, you first must register the library JAR file in Oracle JDeveloper.
To create the library JAR file for custom page templates:
1. From the Tools menu, select Manage Libraries.
2.
Click New.
The Create Library dialog appears.
30-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Select the class path for the library, and click Select.
The class path is displayed below Class Path and the library JAR file name is
displayed in the Library Name field. Ensure that the library name you select ends
with a suffix of .jar. Figure 308 provides details.
5.
6.
Click OK.
When you run the Custom Task Form wizard, you select Custom Page Template
on the Name and Definition page, and enter the following information that you
registered in the Create Library dialog:
The same library name as you entered in the Library Name field in the Create
Library dialog; these names must match.
The path to the .jspx templates file in the library JAR file in the Template
Path field.
30.4.3 How To Create a Task Form Using the Custom Task Form Wizard
This wizard enables you to create a task form using ADF page templates and
standardized task regions. The page templates can be either of the following:
Default page templates that are automatically provided at the following location:
[JDeveloper_Home}/jdeveloper/soa/modules/oracle.soa.worklist_
11.1.1/adflibWorklistComponents.jar
In the Name and Definition page of the Custom Task Flow wizard, select
Packaged, then select either Default or Tabbed.
Custom page templates that you define. In the Name and Definition page of the
Custom Task Flow wizard, select Custom, then select the library name and the
template name.
You package a page template and its artifacts into an ADF library JAR file. These
JAR files can be packaged, deployed, discovered, and used like any other Oracle
library component. The wizard prompts you to specify the JAR name and
template location in the JAR.
Page templates let you define entire page layouts, including values for certain
attributes of the page. When pages are created using a template, they all inherit the
defined layout. When you make layout modifications to the template, all pages that
consume the template automatically reflect the layout changes.
The templates used in the wizard generate content for the following six facets:
Actions
Attachments
Body
Comments
Header
History
For the action, header, and body facets, you can pick the content and attributes to be
displayed and then fine tune the layout.
All six facets are defined in the default page templates. In the case of custom
templates, you use these exact facet names in your template. If your template does not
include these facets, then the facet content is not generated in the JSPX file.
If you do not want to include page templates in your task form, select None in the
Name and Definition page. In this case, the wizard generates a task form with a
header, body (one or more), and footer, and provides for tabular formatting into
columns and rows. You can select any of the task (system) actions to display on the
form and you can specify that the custom actions defined for the human task appear
on the form as buttons. Any or all parts of the payload can be selected to appear, as
well as attachments and comments.
For more information about facets, see Oracle Fusion Middleware Web User Interface
Developer's Guide for Oracle Application Development Framework.
To create a custom task form:
1. Open the BPEL process within the SOA composite application.
2.
Double-click the human task activity, and click the Edit icon.
The Human Task Editor appears.
3.
Above the editor, click Create Form and select Launch Task Form Wizard.
30-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Provide a project name and a directory path (or use the default), and click OK. The
Custom Form Wizard displays the Name and Definition screen as shown in
Figure 309.
Figure 309 Custom Task Form Wizard: Form Name and Definition
5.
In the Form Name field, provide the name of the form (.jspx file) that is to be
generated at the end of the wizard. If you do not provide a name, then the default
name, Humantasknumber_Form, is provided. Ensure that valid characters are
used in the name. Spaces are not permitted.
6.
Specify the Task Flow Name, that is, the name of the ADF task flow that is
generated at the end of the wizard. Accept the default name of
Humantasknumber_TaskFlow or specify a different name.
7.
Packaged: Select this to use one of the default page templates, then select the
particular template from the list.
Custom: Select the library and template. If no library is listed, click Manage
Libraries and follow the instructions in Section 30.4.2, "How to Register the
Library JAR File for Custom Page Templates."
8.
Click Next. This form is created as an ADF task flow and added to the project. The
Header page appears.
9.
On the Header page, shown in Figure 3010, perform the following procedures
and click Next.
In the Actions facet section, select the options to include in the title bar of the
task form:
Other actions (menu): Lists the system actions that are possible for the
task, such as Request Information, Reassign, Renew, Suspend, Escalate,
and Save.
Outcomes (buttons): Displays buttons for task actions that are defined in
the human task, such as setting task outcomes.
In the Header facet section, enter the number of display columns. If you want
each header label to display in its own column, then enter the same number as
the number of headers you move into the Selected list. If you enter 1, but
select 7 headers, all 7 headers appear in one column.
Move header labels into the Selected list and reorder them as needed.
10. On the Body page, shown in Figure 3011, perform the following procedures in the
30-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
11. On the Row1 Column1 page, shown in Figure 3012, move all or part of the
12. For any Rown Columnn page after Row1 Column1, repeat Step 11 and click Next.
The Footer page that displays is based upon the page template you selected on the
Name and Definition page in Step 6 (either Default Page Template or Custom Page
Template).
If you selected Default Page Template, the Footer page shown in Figure 3013 is
displayed. Deselect any comments, attachments, or history facet that you do not
want to include in the footer, and click Next. By default, the comments,
attachments, and history facets are all selected.
Figure 3013 Custom Task Form Wizard: Selecting the Footer Fields for the Default Page Template
13. On the Summary page, shown in Figure 3014, inspect your selections. Click Back
30-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3016
30.4.4 How To Create a Task Form Using the Complete Task with Payload Drop Handler
The human task drop handlers appear in the context menu of the designer, as shown
in Figure 3017.
Figure 3017 Human Task Drop Handlers for Creating the Task Form
30-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Buttons for task actions are also created in the header, as shown in Figure 3020.
Task Actions
The following task actions appear from the Actions dropdown list or as buttons. The
tasks that appear depend on the state of the task (assigned, completed, and so on) and
the privileges that are granted to the user viewing the task. For example, when a task
is assigned to a group, only the Claim button appears. After the task is claimed, other
actions such as Reject and Approve appear.
The first three custom actions appear on the task form as buttons: Claim, Dismiss, and
Resume. Only those buttons applicable to the task appear. Other actions are displayed
under the Actions list, starting with Request for Information, Reassign, and Route.
Systems actionsWithdraw, Pushback, Escalate, Release, Suspend, and
Renewfollow the custom actions, followed by the Save button. These actions require
no further dialog to complete.
ClaimA task that is assigned to a group or multiple users must be claimed first.
Claim is the only action available in the Task Action list for group or multiuser
assignments. After a task is claimed, all applicable actions are listed.
Note:
If an FYI task is sent to multiple users, a user must first select the
Claim button to claim the task before they can dismiss it.
Pushback is designed to work with single approvers and not with
group votes. Pushback from a stage with group vote (or parallel)
scenario to another stage is not allowed. Similarly, you cannot
push back from a single assignee to a group vote (or parallel)
scenario.
DismissThis action is used for a task that requires the person acting on the task
to acknowledge receipt, but not take any action (like an FYI).
ResumeA task that was halted by a Suspend action can be worked on again. See
Suspend.
Request for InformationYou can request more information from the task creator
or any of the previous assignees. If reapproval is not required, then the task is
assigned to the next approver or the next step in the business process.
ReassignManagers can reassign a task to reportees. The Reassign option also
provides a Delegate function. A task can be delegated to another user or group.
The delegated task appears in both the original users and the delegated users
worklists. The delegated user can act on behalf of the original assignee, and has
the same privileges for that task as the original assignee.
RouteIf there is no predetermined sequence of approvers or if the workflow was
designed to permit ad hoc routing, then the task can be routed in an ad hoc
fashion. For such tasks, a Route button appears on the task details page. From the
Routing page, you can look up one or more users for routing. When you specify
multiple assignees, you can choose whether the list of assignees is for simple
30-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
WithdrawOnly the task creator can withdraw (cancel) the task. The Comments
area is available for an optional comment. The business process determines what
happens next.
PushbackThis action sends a task up one level in the workflow to the previous
assignee. Note: Pushback is designed to work with single approvers and not with
group votes. Pushback from a stage with group vote (or parallel) scenario to
another stage is not allowed. Similarly, you cannot push back from a single
assignee to a group vote (or parallel) scenario.
EscalateAn escalated task is assigned to the users manager. The Comments
area is available for an optional comment.
ReleaseReleasing a task makes it available to other assignees. A task assigned to
a group or multiple users can then be claimed by the other assignees.
SuspendThis action suspends the expiration date indefinitely, until the task is
resumed. Suspending and resuming tasks are available only to users who have
been granted the BPMWorkflowSuspend role. Other users can access the task by
selecting Previous in the task filter or by looking up tasks in the Suspended status.
Buttons that update a task are disabled after suspension.
RenewRenewing a task extends the task expiration date seven days (P7D is the
default). The renewal duration is controlled from Oracle Enterprise Manager Grid
Control Console. A renewal appears in the task history. The Comments area is
available for an optional comment.
SaveChanges to the task are saved.
While you are creating a task form, all possible system action buttons appear, although
only those actions that are appropriate for the task state and fit the users privileges
appear in the worklist.
Task History
The history of task actions appears on the task details page, and is displayed in the
worklist as a history table. The history includes the following fields:
Version number
Action date
See Figure 3219, "History: Graphical View" and Figure 3220, "History: Full Task
Actions" for how task history is displayed in Oracle BPM Worklist, including the
options to take a history snapshot, list future participants, and list full task actions.
Task Comments and Attachments
A trail of comments with the comment date and comment writers user name is
maintained throughout the life cycle of a task.
Files or reference URLs associated with a task can be added by any of the human task
participants.
Figure 3021 shows an example of the comments and attachments region.
The following steps describe how to use a drop handler that creates the task form,
including the payload, without building each region individually. To build each region
individually, see Section 30.4.5, "How To Create Task Form Regions Using Individual
Drop Handlers."
To create a task form using the Complete Task with Payload drop handler:
1. In the designer, double-click taskDetails1_jspx.
2.
In the Create JSF Page dialog, provide a file name and directory information (or
accept the defaults) and click OK.
3.
In the Data Controls panel of the Application Navigator, expand the human task
node, then the getTaskDetails node, and then the Return node.
4.
5.
6.
In the Edit Action Binding dialog, shown in Figure 3022, click OK.
30-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3022
7.
In the next Edit Action Binding dialog, the data collection is selected, as shown in
Figure 3023; click OK.
30-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
30.4.5 How To Create Task Form Regions Using Individual Drop Handlers
You can create a display form with multiple regions using the individual Task Header,
Task Action, Task History, and Task Comment and Attachment drop handlers shown
in Figure 3025.
Task Header provides both header and task actions, so you do not need the Task
Action drop handler when you use Task Header. Use Task Action when you want the
actions dropdown menu and buttons, but not header details.
To create the task form without building each region individually, see Section 30.4.4,
"How To Create a Task Form Using the Complete Task with Payload Drop Handler."
Before you create this task form, you must have created the following:
1.
2.
In the Create JSF Page dialog, provide a file name and directory information (or
accept the defaults) and click OK.
3.
In the Data Controls panel of the Application Navigator, expand the human task
node, then the getTaskDetails node, and then the Return node.
4.
5.
Figure 3026 Designing the Task Form: Buttons for Task Actions
30-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Drag additional Task icons into the JSPX designer, selecting these options with
each iteration:
The task form now has multiple regions for task action dropdown lists and
buttons, task header details, task history, and comments and attachments.
To continue creating the task form, see Step 1 in Section 30.4.6, "How To Add the
Payload to the Task Form."
Expand Layout.
3.
Drag Panel Group Layout between the Header and Comment sections.
4.
5.
Drag the payload data collection to the left of the Panel Group Layout area.
An alternative to dropping the payload node onto the form is to expand the
payload node and drop the necessary child elements onto the form. For example,
to create a read-only form for the VacationRequest payload, expand the payload
node, drag the Vacation Request Process Request node onto the form, and select
Forms > ADF Read-only Form.
6.
From the context menu, select Forms, then ADF Read-only Form, as shown in
Figure 3028.
Figure 3028 Adding ADF Read-Only Fields to the Task Form Payload Region
7.
In the Edit Form Fields dialog, accept the defaults and click OK.
This creates read-only fields in the payload region, between the Details and
History sections.
The payload regions appear, as shown in Figure 3029.
The task form, shown in Figure 3030, is complete and ready to be deployed.
Figure 3030 The Task Form (taskDetails.jspx)
30-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The task form is ready to be deployed. See Section 30.8, "Deploying a Composite
Application with a Task Flow."
Select the Edit Definition option to display the Refresh Data Control dialog, as
shown in Figure 3032.
Default email notificationUse the first page of the task form that you create for
the human task. The content is sent as an HTML-based email. Images in the task
flow are included as attachments so that the notification can be viewed in
disconnected mode. All drop handlers, including Complete Task with Payload
and Complete Task without Payload, are suitable for emails.
Custom email notificationUse the Task display for email drop handler to create
a custom email notification task page.
30-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Add a router to the task flow. The router directs the task flow to send either the
email notification page or the default page, depending on the control flow based
on the bpmClientType page flow scope value.
Edit the generated inline CSS to customize the page. No additional CSS is included
at runtime and the ADF CSS is not available at runtime. See the samples
notification-101 and notification-102 available with the Oracle SOA Suite samples.
Reference images directly from the HTML or JSF page. (Indirect references, for
example, an included JSF that in turn includes the image, are not allowed.)
From the Component Palette, select ADF Task Flow, and drag the View icon into
the designer.
3.
Click view1 below the icon and enter a name for the email notification page.
Figure 3033 shows an example using the name EmailPage.
Figure 3033
4.
5.
To ensure that the router is called, right-click the router icon and click Mark
Activity > Default Activity, as shown in Figure 3034.
7.
8.
9.
Click Add, and in the Outcome field, enter the name of the email notification
page.
10. Use the Expression Builder to enter the following in the expression field:
#{pageFlowScope.bpmClientType=="notificationClient"}
11. In the Component Palette, click Control Flow Case.
12. In the designer, drag from the router page icon to taskDetails1.jspx.
30-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3035
To continue creating the email notification page, see Step 1 in Section 30.7.1.2,
"Creating an Email Notification Page."
1.
2.
In the Create JSF Page dialog, provide a file name and directory information (or
accept the defaults) and click OK.
The EmailPage.jspx tab opens in the designer.
3.
From the Component Palette, drag any of the Common Components (for an
image, for example) or Layout components into the designer.
4.
For the layout component you selected, provide alignment and other details in the
Property Inspector tab.
Figure 3037 shows the layout fields available when Panel Group Layout is
selected.
30-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
See Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle
Application Development Framework for more information about panel group layout.
5.
For more information, see "How to Set Component Attributes" in Oracle Fusion
Middleware Web User Interface Developer's Guide for Oracle Application Development
Framework.
6.
From the Data Controls panel, expand the human task node, then the
getTaskDetails node, and then the Return node.
7.
30-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.
Select Human Task, and then Task details for email, as shown in Figure 3039.
Figure 3039
This drop handler includes a header with inline style, a payload using ADF, and a
comment using inline style. Because the payload is dynamically generated, it does
not include an inline style.
In general, you can find the inline styles for the Header section for each
component and use the same style for the Content section for the respective
components.
9.
In the Edit Action Bindings dialog, select the data collection and click OK.
30.7.3 What You May Need to Know About Creating an Email Notification Page
A notification may not display correctly in email if the styles used in the fields of the
form are not valid for email. Editing the generated inline CSS to customize the page
may be required. See Section 30.7.1, "How To Create an Email Notification," for more
information.
Security issues can also prevent the form from being rendered correctly. See
Section 30.6, "Securing the Task Flow Application," for more information.
3.
Click OK.
30-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<soapClient>
<rootEndPointURL>http://my_host.us.example.com:8001</rootEndPointURL>
</soapClient>
</server>
</workflowServicesClientConfiguration>
30.8.4.2 Configuring Unique Cookie Context Paths for the Session Tracking
Cookies
Before deploying the task form to a non-SOA Oracle Weblogic Server, ensure that the
session tracking cookie of your task-form web application is configured with a cookie
trigger path unique to your application. This ensures that your task form application
has its unique session tracking cookie and cannot be overwritten by the session
tracking cookies created for other Oracle BPM applications like Oracle BPM Worklist
or Oracle Business Process Management Workspace.
To configure the session cookie trigger path, in JDeveloper, open the weblogic.xml
file in your web project. Choose the overview tab in your .xml file editor, and choose
the session. In the cookie trigger path field, enter the application context path of your
web application. For example, if the URL of your application is
http://host:port/my-application-context-root in which
my-application-context-root is the name of your application context root, then
the cookie trigger path is set as follows:
/my-application-context-root
Use Oracle WebLogic Server Administration Console to deploy the JAR file.
To deploy oracle.soa.workflow.jar:
1. Go to Oracle WebLogic Server Administration Console at
http://remote_hostname:remote_portnumber/console
2.
3.
4.
In the Path field, provide the following path and click Next.
ORACLE_JDEV_HOME/jdeveloper/soa/modules/oracle.soa.workflow_
11.1.1/oracle.soa.workflow.jar
5.
Keep the same name for the deployment and click Next, as shown in Figure 3041.
30-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3041 Oracle WebLogic Server Administration Console: Install Applications Assistant
6.
7.
Figure 3042 Oracle WebLogic Server Administration Console: The oracle.soa.workflow Active State
See Section 30.8.4.4, "Defining the Foreign JNDI Provider on a non-SOA Oracle
WebLogic Server," to continue.
30.8.4.4 Defining the Foreign JNDI Provider on a non-SOA Oracle WebLogic Server
Use Oracle WebLogic Server Administration Console to complete this portion of the
task.
Designing Task Forms for Human Tasks 30-41
Click New.
3.
4.
5.
Figure 3044 shows the page where you enter this information.
30-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3044
See Section 30.8.4.5, "Defining the Foreign JNDI Provider Links on a non-SOA Oracle
WebLogic Server," to continue.
30.8.4.5 Defining the Foreign JNDI Provider Links on a non-SOA Oracle WebLogic
Server
Use Oracle WebLogic Server Administration Console to complete this portion of the
task.
To define the foreign JNDI provider links:
1. In the Domain Structure area, expand Services and click Foreign JNDI Providers.
2.
3.
4.
Click New.
Figure 3045 shows the Links tab.
Figure 3045 Defining the Foreign JNDI Provider Links: The Links Tab
5.
6.
30-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
See Chapter 32, "Using Oracle BPM Worklist" for information on how to act on tasks.
Notes:
For the task form to work correctly, always specify the URL using
the complete name for the host on which the task flow is
deployed.
If you want to access the task form from a different URL that has a
different port number than the hostname and port number
previously set in Oracle WebLogic Server Administration Console,
then you must change the port number for the front-end in Oracle
WebLogic Server Administration Console and redeploy the task
form so that the task details appear correctly in the worklist.
30.8.6 What You May Need to Know About Undeploying a Task Flow
When a task flow Web application is deployed, the task flow URL is registered in the
database. This URL is displayed in Oracle BPM Worklist when a task is clicked and the
task details are displayed. If the task flow Web application is later undeployed or
stopped, the task flow URL in the database is not removed as part of the
undeployment. Consequently, when you click the task in the worklist to see the task
details, a 404 Not Found error is displayed rather than the message Details not
available for task. To avoid the 404 Not Found error, use Oracle Enterprise
Manager Fusion Middleware Control to undeploy the task flow application from the
application home page.
30-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can click an available action, RESOLVED or UNRESOLVED, or click the Worklist
Application link to log in to the worklist. Clicking an action displays an email
composer window in which you can add a comment and send the email.
By default, the text in a task notification refers to "Worklist Application," but you can
change that text and its associated URL.
30-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
30.10.1 Changing the Text for the Worklist Application in Task Notifications
By default, the text in a task notification refers to "Worklist Application," but you can
change that text. To change it, you create a custom resource bundle and modify the
appropriate strings.
To change the text in a task notification:
1. Open the WorkflowLabels.properties resource bundle in the sample
workflow-110-workflowCustomizations.
2.
For more details on how to modify the resource bundle string, see the
workflow-110-workflowCustomizations sample.
3.
Host it on the file system, using a URL beginning with file:/// to point to
the appropriate location.
Host the file in MDS, using a URL beginning with oramds:///... .
3.
Right-click soa-infra, and select SOA Administration > Workflow Config > Task
tab.
The Workflow Task Service Properties page appears.
4.
Expand Advanced.
5.
Modify the Worklist Application URL. For example, you can change an existing
entry like this:
http://[HTTP_HOST]:[HTTP_PORT]/integration/worklistapp/TaskDetails?taskId=PC_
HW_TASK_ID_TAG
30.10.3 Showing or Hiding the URL of the Worklist Application in Task Notifications
For information about showing or hiding the URL of the Worklist Application, see
Section 29.8.6, "How to Display the Oracle BPM Worklist URL in Notifications".
30.11 Reusing the Task Flow Application with Multiple Human Tasks
You can reuse a single task flow application with multiple human tasks. To use this
feature, all human tasks must have both the payload elements and.the outcomes must
be identical.
30.11.1 How To Reuse the Task Flow Application with Multiple Human Tasks
1.
2.
For each additional human task, add the following element inside the file (at the
bottom just before </hwTaskFlows>):
<hwTaskFlow>
<WorkflowName>$TASK_NAME</WorkflowName>
<TaskDefinitionNamespace>$TASK_NAMESPACE</TaskDefinitionNamespace>
<TaskFlowId>$TASK_FLOW_NAME</TaskFlowId>
<TaskFlowFileName>$TASK_FLOW_FILENAME</TaskFlowFileName>
</hwTaskFlow
where:
$TASK_NAME is replaced with the name of the human task inside the .task
file (value of the <name> element).
$TASK_NAMESPACE is replaced with the namespace of the human task inside
the .task file (value of the attribute targetNameSpace of element
<taskDefinition>).
$TASK_FLOW_NAME is copied from the existing
<hwTaskFlow>/<TaskFlowId> element.
$TASK_FLOW_FILENAME is copied from the existing
<hwTaskFlow>/<TaskFlowFileName> element.
30.11.2 How to Reuse the Task Flow Application with Different Actions
You can reuse a single task flow that has different actions for different tasks. To do this:
1.
Define all actions in the task that you use to generate the taskflow.
2.
In any given task, disable the actions that you do not want to include.
30-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
31
Human Workflow Tutorial
31
This chapter describes how to design your first workflow from start to finish.
This chapter includes the following sections:
Section 31.6, "Associating the Human Task and BPEL Process Service
Components"
This tutorial describes how to create a new application and SOA project and how to
design a human task to send a vacation request to a manager for approval or rejection.
The resulting SOA composite application contains the following components:
A BPEL process
It also describes how to create an Oracle ADF-based task form that enables the end
user to act upon the vacation request once the application is deployed and running. To
Prerequisites
create an Oracle ADF-based task form you must create a new application and a new
project.
This tutorial guides you through the following tasks:
31.2 Prerequisites
This tutorial makes the following assumptions:
1.
Note:
31-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
From the File main menu, select New > Applications > SOA Application.
3.
Click OK.
4.
5.
6.
In the Composite Template list, select Composite with BPEL Process, and click
Finish.
7.
8.
9.
10. To the right of the Input field, click the Search icon.
"Prerequisites."
13. Click OK until you are returned to the Type Chooser dialog, as shown in
Figure 311.
Figure 311 Type Chooser Dialog with the Request and Response Elements
You are returned to the Create BPEL Process dialog, as shown in Figure 312.
17. Accept the default values for all other settings, and click OK.
For more information about service components and the SOA Composite Editor,
see Chapter 2, "Developing SOA Composite Applications with Oracle SOA Suite."
31-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 311
Field
Value
Name
Enter VacationRequestTask.
Namespace
Do not select the checkbox. Instead, you create a human task that
you later associate with the BPEL process you created in
Section 31.3, "Creating an Application and a Project with a BPEL
Process." The BPEL process was created with an
automatically-bound web service.
3.
Click OK.
The Human Task icon appears in the SOA Composite Editor above the BPEL
process, as shown in Figure 314.
4.
2.
Accept the default values for outcomes (APPROVE and REJECT). For this task,
these outcomes represent the two choices the manager has for acting on the
vacation request.
3.
4.
5.
6.
Select Element.
7.
8.
9.
Ensure that the Editable via worklist checkbox is selected. This provides you with
the option to modify this parameter during runtime from Oracle BPM Worklist.
31-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
13. At the top of the Human Task Editor, click the Edit icon.
The Edit Participant Type dialog appears. You now add participants to this task.
As described in Section 27.2.1.1.2, "Participant Type," Oracle SOA Suite provides
several out-of-the-box patterns known as participant types for addressing specific
business needs.
14. Accept the default participant type of Single that displays in the Type list. You
select this type because a single assignee, the manager, acts on the vacation request
task.
15. In the Participant Names table, click the Add icon, and select Add User.
17. In the Value column, click the Browse icon (the dots) to invoke the Expression
Builder dialog.
18. In the dropdown list in the Functions section, select Identity Service Functions.
19. Select getManager. This function gets the manager of the user who created the
where ns1 is the namespace for this example; your namespace may be different.
23. Click Insert into Expression.
The Expression Builder dialog displays the XPath expression in the Expression
section. Figure 318 provides details.
Figure 318 XPath Expression
3.
4.
5.
6.
From the Task Definition list, select the VacationRequestTask task you created (if
it is not currently displaying).
The dialog refreshes as shown in Figure 319 to display additional fields.
31-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
In the BPEL Variable column, click the Browse icon (dots) shown in Figure 3110.
Figure 3110
8.
9.
31-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3112
BPEL Variable
Figure 3113 Human Task and Partner Links in Oracle BPEL Designer
12. Return to the SOA Composite Editor and note that the BPEL process and human
31-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Click OK.
3.
4.
5.
Click Next.
6.
7.
In the Password field, enter the password for connecting to the application server.
8.
Click Next.
9.
Enter the hostname for the application server that is configured with the SOA
Infrastructure.
10. In the Weblogic Domain field, enter the Oracle WebLogic Server domain.
11. Click Next.
12. Click Test Connection.
Connection Success
From the Create Form menu at the top, select Auto-Generate Task Form.
Figure 3116 provides details.
31-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Additional Tutorials
4.
3.
Follow the pages of the deployment wizard to deploy the task form.
The task form is deployed.
For more information about deployment, see Section 43.7, "Deploying SOA
Composite Applications."
3.
4.
Note that the task form now appears at the bottom of Oracle BPM Worklist.
End-to-End Examples
Sample
Description
Name
Demo Community
Seed Application
workflow-001-DemoCommun
itySeedApp
Vacation Request
workflow-100-VacationReque
st
workflow-102-SalesQuote
Contract Approval
workflow-104-ContractAppro
val
Additional Tutorials
Description
Iterative Design
Workflow
Customizations
workflow-110-workflowCusto
mizations
MLS Sample
workflow-114-MLSSample
Workflow Event
Callback
workflow-116-WorkflowEven
tCallback
Java Samples
31-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Name
workflow-118-JavaSamples
32
32
This chapter describes how worklist users and administrators interact with Oracle
BPM Worklist, and how to customize the worklist display to reflect local business
needs, languages, and time zones.
This chapter includes the following sections:
Section 32.12, "Accessing Oracle BPM Worklist in Local Languages and Time
Zones"
Section 32.13, "Creating Reusable Worklist Regions"
Section 32.14, "Java Code for Enabling Customized Applications in Worklist
Application"
For information about how to use the APIs exposed by the workflow service,
Chapter 33, "Building a Custom Worklist Client."
For information about troubleshooting human workflow issues, see section "Human
Workflow Troubleshooting" of Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
Oracle BPM Worklist provides different functionality based on the user profile.
Standard user profiles include task assignee, supervisor, process owner, and
administrator. For example, worklist users can update payloads, attach documents or
comments, and route tasks to other users, in addition to completing tasks by providing
conclusions such as approvals or rejections. Supervisors or group administrators can
use the worklist to analyze tasks assigned to a group and route them appropriately.
Users can customize their task lists, as required, by adding worklist views, for
example, selecting the columns to display, or displaying a subset of the tasks based on
filter criteria.
Using Oracle BPM Worklist, task assignees can do the following:
Perform authorized actions on tasks in the worklist, acquire and check out shared
tasks, define personal to-do tasks, and define subtasks.
Filter tasks in a worklist view based on various criteria.
Work with standard work queues, such as high priority tasks, tasks due soon, and
so on. Work queues allow users to create a custom view to group a subset of tasks
in the worklist, for example, high priority tasks, tasks due in 24 hours, expense
approval tasks, and more.
Enable group owners to define task dispatching rules for shared tasks.
Workflow Services
The worklist is rendered in a browser by a task form that you create using ADF task
flows in Oracle JDeveloper. See Chapter 30, "Designing Task Forms for Human Tasks"
for more information.
Users can also act on tasks through portals such as Oracle WebCenter Portal. Portals
enable users to present information from multiple, unrelated data sources in a single
organized view. This view, a portal page, can contain one or more components called
portlets that can each collect content from different data sources.
32-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can build clients for workflow services using the APIs exposed by the workflow
service. The APIs enable clients to communicate with the workflow service using local
and remote EJBs, SOAP, and HTTP.
32.1.1 What You May Need To Know About Oracle BPM Worklist
Only one identity provider is supported. Java policy store does not support multiple
providers in a sequence. Therefore, fall-through from one directory server to another is
not supported for worklists.
Type of User
Access
Acts on tasks assigned to him or his group and has access to system and custom
actions, routing rules, and custom views
Supervisor (manager)
Acts on the tasks, reports, and custom views of his reportees, in addition to his own
end-user access
Process owner
Acts on tasks belonging to the process but assigned to other users, in addition to his
own end-user access
Group administrator
Manages group rules and dynamic assignments, in addition to his own end-user
access
Workflow administrator
Administers tasks that are in an errored state, for example, tasks that must be
reassigned or suspended. The workflow administrator can also change application
preferences and map attributes, and manage rules for any user or group, in addition
to his own end-user access.
Note:
Apple Safari
To log in:
Go to
1.
http://hostname:port_number/integration/worklistapp
2.
hostname is the name of the host computer on which Oracle SOA Suite is
installed
The port_number used at installation
3.
Click Login.
32-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This page lists all the tasks and work items assigned to you, depending on your role.
For example, all users can access the My Tasks and Initiated Tasks pages. Only
supervisors can access the My Staff page, and only Process Workspace administrators
can access the Administrative Tasks page.
At the far left, as shown in Figure 323, is a list of views with My Tasks selected.
Expand this list to select:
A particular view showing the number of open tasks for each view. Selecting a
particular view refreshes the task count to the latest number.
To keep this list visible while you work on tasks, click Pin. Then, to hide it, click
Unpin
Figure 323 Selecting a View
Table 322 describes the components of the Home (task list) page.
Table 322
Component
Description
Views list
Inbox, Standard Views, My ViewsSee Section 32.3.2, "How To Create, Delete, and Customize
Worklist Views," for more information.
The inbox views displayed depend on the role granted to the logged-in user.
Everyone (the user role) sees My Tasks, Initiated Tasks and Administrative Tasks.
Users who are also managers see the My Tasks, Initiated Tasks, Administrative Tasks and
My Staff Tasks tabs.
Users who are also administrators (the BPMWorkflowAdmin), but not managers, see the My
Tasks, Initiated Tasks, Administrative Tasks, Administration, and Evidence Search tabs.
Users who are managers and administrators see all the tabs My Tasks, Initiated Tasks, My
Staff Tasks, Administrative Tasks, Administration, and Evidence Search.
Users with the workflow.admin.evidenceStore permission also see the Evidence Search tab.
Section 32.4.4, "How To Act on Tasks That Require a Digital Signature," for information about
evidence search
Section 32.8.1, "How To Manage Other Users or Groups Rules (as an Administrator)"
Worklist
Views
Task Status
A bar chart shows the status of tasks in the current view. See Section 32.3.3, "How To Customize
the Task Status Chart," for more information.
Display Filters Specify search criteria from the Assignee or State fields. The category filters that are available
depend on which tab is selected.
From the My Tasks tab, the Assignee filters are Me, My Group, Me & My Group, Me
(Previously) (tasks worked on previously), and Me (Review Only). From the Initiated Tasks
tab, the assignee filter is not available. From the My Staff Tasks tab, the only assignee filter is
Reportees. From the Administrative Tasks tab, the assignee filter is not available.
The State filters include Any, Assigned, Completed, Suspended, Withdrawn, Expired,
Errored, Alerted, Information Requested.
Use Search to enter a keyword, or use Advanced Search. See Section 32.3.1, "How To Filter Tasks,"
for more information.
32-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Actions List
Select a group action (Claim) or a custom action (for example, Approve or Reject) that was
defined for the human task. Claim appears for tasks assigned to a group or multiple users, even if
the task is an FYI task; one user must claim the task before it can be worked on. Other possible
actions for a task, such as system actions, are displayed on the task details page for a specific task.
You can also create ToDo tasks and subtasks here.
Note:
Default
Columns
If a task is aggregated, you only see actions such as Approve and Reject, even if the
aggregated task includes FYI tasks. No acknowledge action is explicitly provided. Approve or
Reject can be interpreted as an acknowledge action.
The Claim button remains enabled even when Auto Claim has been previously enabled. This
button enables a user to claim and continue working on the task rather than to simply
approve it.
TitleThe title specified when the human task was created. Tasks associated with a purged or
archived process instance do not appear.
CreatorThe user who created the task.
PriorityThe priority specified when the human task was created. The highest priority is 1; the
lowest is 5.
AssignedThe date that the task was assigned.
Task Details
Task details can be viewed in the lower half of the worklist by selecting the task in the Inbox. You
can also view them in a pop-up browser window by double-clicking the task. Buttons indicate
available actions. Once you complete a task:
See Section 32.4, "Acting on Tasks: The Task Details Page," for more information.
Figure 322 also shows the Administration, Reports, and Preferences links
(upper-right corner). Table 323 summarizes the Home, Administration, Reports, and
Preferences pages.
Table 323
Page
Description
Home
As described in Table 322, the logged-in users list of tasks, details for a selected task,
and all the functions needed to start acting on a task are provided.
Description
Administration
Mapping attributes
Configuring tasks
Reports
The following reports are available: Unattended Tasks Report, Tasks Priority Report,
Tasks Cycle Time Report, Tasks Productivity Report, and Tasks Time Distribution
Report. See Section 32.11.1, "How To Create Reports," for more information.
Preferences
Setting rules for users or groups, including vacation rules, and setting vacation
periods
Uploading certificates
32.2.3 What Happens When You Change a Users Privileges While They are Logged in
to Oracle BPM Worklist
If you change a user's privileges in Oracle Enterprise Manager Fusion Middleware
Control while the user is logged in to Oracle BPM Worklist, the changes take effect
only after a subsequent login by the user. This is true for situations in which there are
two active worklist sessions, one in which the user is logged in before the privileges
are changed, and one in which the same user logs in after the privileges are changed.
In the first case, the changes to the user's privileges do not take effect while the user is
logged in. In the second case, when the user logs in to the second instance of the
Worklist Application, the changes to the user's privileges do take effect.
Note:
32-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Filters are used to display a subset of tasks, based on the following filter criteria:
Assignee
From the Assignee drop-down list, select from the following:
Tasks that are assigned to groups to which the logged-in user belongs
Tasks that are assigned to an application role that the logged-in user is
assigned
Tasks that are assigned to multiple users, one of which is the logged-in
user
Note:
1.
2.
Click Advanced.
2.
(Optional) Check Save Search As View, provide a view name, and use the
Display tab to provide other information, as shown in Figure 325 and
Figure 326.
32-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 324 describes the advanced search view columns available in the Display
tab.
Table 324
Column
Description
Start Date
The name of the task component that defines the task instance.
Owner Role
The application role (if any) that owns the task instance. Task
owners can be application roles, users, or groups. If the owner of
the task is an application role, this field is set.
Updated Date
Composite Version
Creator
From User
Percentage Complete
Owner Group
The group (if any) that owns the task instance. Task owners can
be application roles, users, or groups. If the owner of the task is
a group, this field is set.
End Date
Composite
Due Date
Composite Distinguished
Name
Description
Updated By
Outcome
Task Namespace
Approvers
Application Context
Owner User
The user (if any) that owns the task instance. Task owners can be
application roles, users, or groups. If the owner of the task is a
user, this field is set.
Identifier
Category
Acquired By
The name of the user who claimed the task in the case when the
task is assigned to a group, application role, or to multiple users,
and then claimed by the user.
Component
The name of the task component that defines the task instance.
The name of the user who delegated the task in the case when
the user delegates a task to another user.
Assigned
Partition
Title
Number
Priority
Assignees
State
Created
Expires
Custom Date 1
Custom Date 2
Custom String 1
Custom String 2
Custom Number 1
Custom Number 2
The saved view appears in the Views pane under My Views, as shown in
Figure 327.
32-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
3.
4.
Advanced SearchConditions
Condition
Description
User Conditions
Acquired By
The name of the user who claimed the task in the case when the
task is assigned to a group, application role, or to multiple users,
and then claimed by the user.
Approvers
Creator
From User
The name of the user who delegated the task in the case when
the user delegates a task to another user.
Owner Group
The group (if any) that owns the task instance. Task owners can
be application roles, users, or groups. If the owner of the task is
a group, this field is set.
Owner Role
The application role (if any) that owns the task instance. Task
owners can be application roles, users, or groups. If the owner of
the task is an application role, this field is set.
Owner User
The user (if any) that owns the task instance. Task owners can be
application roles, users, or groups. If the owner of the task is a
user, this field is set.
Updated By
Advanced Conditions
Application Context
32-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Component
The name of the task component that defines the task instance.
Composite
Composite Distinguished
Name
Composite Version
Partition
Basic Conditions
Category
Identifier
Number
Outcome
Percentage Complete
Priority
State
The name of the task component that defines the task instance.
Task Namespace
Title
Time Conditions
Assigned
Created
Due Date
End Date
Expires
Start Date
Updated Date
Custom Conditions
Custom Date 1
Custom Date 2
Custom String 1
Custom String 2
Custom Number 1
Custom Number 2
5.
6.
7.
Specify whether to share either this views definition or its data, and the users or
groups to share it with.
8.
Click Search.
The task list appears with the tasks filtered according to your criteria.
InboxShows all tasks that result from any filters you may have used. The
default shows all tasks.
32-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3211
Worklist Views
1.
2.
Use the Definition tab of the Create User View dialog box, shown in Figure 3212,
to do the following:
Create View or Use Public ViewCreate your own view or browse for a
public view to copy.
NameSpecify a name for your view.
Add to Standard ViewsThis option applies to administrators only.
Administrators select this option to create the view as a standard view, which
then appears in the Standard Views list for all worklist users.
AssigneeSelect Me, My Group, Me & My Group, Me (Previously), Me
(Review Only), Creator, Reportees, Admin, Owner.
Add Condition (a plus sign)Select the conditions that apply to your view.
Share ViewYou can grant access to another user to either the definition of
this view, in which case the view conditions are applied to the grantees data,
or to the data itself, in which case the grantee can see the grantors worklist
view, including the data. Sharing a view with another user is similar to
delegating all tasks that correspond to that view to the other user; that is, the
other user can act on your behalf. Shared views are displayed under My
Views.
3.
Use the Display tab of the Create User View dialog, shown in Figure 3213, to
customize the fields that appear in the view.
32-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click OK.
The saved view appears in the Views panel under My Views
To delete a view:
If an administrator inadvertently deletes the pre-seeded
standard views, then those views do not remain permanently deleted.
They are recreated when the server restarts.
Note:
1.
2.
3.
The Confirm Delete dialog box prompts you to confirm that you want to delete the
view.
4.
Select Edit User Preferences. The Edit User Preferences dialog box appears.
3.
Use the items in the Edit User Preferences dialog box to customize the view, as
shown in Figure 3214, and click OK.
Add or remove status states for display, as shown in Figure 3215, and click OK.
32-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Provide details in the Create ToDo Task dialog, shown in Figure 3216, and click
OK.
A ToDo task can have only one level of subtasks. When all ToDo subtasks are
100% complete, the parent ToDo task is also marked as complete. If the parent
ToDo task is completed, then ToDo subtasks are at 100% within the workflow
system.
If the parent is a business task and that task is completed, then the subtasks of that
task are withdrawn.
If you explicitly set a ToDo task to 100%, there is no aggregation on the parent
task.
If you are using a release of Oracle Business Process Management that is before
11g Release 1 (11.1.1.7.0), then you need to re-create the task form for any task for
which you are creating a subtask. You may, however, continue to use processes
that were deployed in earlier releases.
If you do not re-create the task form, then the Actions list in the task form itself
does not provide the option to create a subtask. You can, however, create a
subtask by selecting Create Subtask from the Actions list above the worklist.
If you are the administrator for the BPMN service engine, be aware that subtasks
do not appear in the Oracle Enterprise Manager Fusion Middleware Control.
To create a subtask:
In the worklist, select the task for which you want to create a subtask.
1.
2.
3.
In the Create Subtask dialog, define the subtask, keeping the following in mind:.
32-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Single Approver
Group Vote, also referred to as a parallel task. For this routing type, you
are prompted to enter multiple participants.
You specify participants by performing a search and selecting from the results.
You can select multiple users, groups, or application roles.
When you have finished specifying the subtask, in the Create Subtask dialog box,
click OK. This refreshes the task list. When you select the parent task, the Task
Details page now includes a Subtasks section displaying the details about the
subtask you created for that task.
Note:
If you specified more than one participant for the subtask, then
the Subtask region displays a separate item for each participant.
If a participant completes a subtask, then you must manually
refresh the task to show the details for that completed subtask.
Any kind of change to the task details page, such as changing a priority or adding a
comment or attachment, requires you to save the change before you go on to make any
other changes.
The task details page has the following components:
ActionsLists the system actions that are possible for the task, such as Request
Information, Reassign, Renew, Suspend, Escalate, and Save.
Action buttonsDisplays buttons for custom actions that are defined in the
human task, such as setting task outcomes (for example, Resolved and
Unresolved for a help desk request or Approve and Reject for a loan request). For
the task initiator, manager, or administrator, Withdraw may also appear.
DetailsDisplays task attributes, including the assignee, task creator, task
number, state, priority, who acquired the task, and other mapped attributes. It also
displays dates related to task creation, last update, and expiration date.
HistoryDisplays the approval sequence and the update history for the task. See
Section 32.4.2, "Task History," for more information.
Table 326 tells what the icons used in the Task Details History section signify.
Table 326
Icon
Description
Indicates an approver in an ad hoc routing scenario.
32-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Comments and attachments are shared between tasks and subtasks. For example,
when you create a ToDo task and add comments and attachments, subtasks of this
ToDo task include the same comments and attachments.
The Task Details page may appear differently depending on the tool used during
design time to develop the task form it displays.
A user can view a task when associated with the task as the current assignee (directly
or by group membership), the current assignees manager, the creator, the owner, or a
previous actor.
A users profile determines his group memberships and roles. The roles determine a
users privileges. Apart from the privileges, the exact set of actions a user can perform
is also determined by the state of the task, the custom actions, and restricted actions
defined for the task flow at design time.
Certain functions, such as restricted task reassignment, are
available only when a single task is selected. If multiple tasks that use
restricted reassignment are selected, then the restricted reassignment
algorithm is not invoked. In that case, the complete list of users gets
returned as though restricted reassignment had not been specified.
Note:
The following algorithm is used to determine the actions a user can perform on a task:
1.
Get the list of actions a user can perform based on the privileges granted to him.
2.
Get the list of actions that can be performed in the current state of the task.
3.
4.
Remove any action on the combined list that is specified as a restricted action on
the task.
The resulting list of actions is displayed in the task list page and the task details page
for the user. When a user requests a specific action, such as claim, suspend, or
reassign, the workflow service ensures that the requested action is contained in the list
determined by the preceding algorithm.
Step 2 in the preceding algorithm deals with many cases. If a task is in a final,
completed state (after all approvals in a sequential flow), an expired state, a
withdrawn state, or an errored state, then no further update actions are permitted. In
any of the these states, the task, task history, and subtasks (parent task in parallel flow)
can be viewed. If a task is suspended, then it can only be resumed or withdrawn. A
task that is assigned to a group must be claimed before any actions can be performed
on it.
Note: If you act on a task from the task details page, for example, if
you approve a task, then any unchanged task details data is saved
along with the saved changes to the task. However if you act on a task
from the Actions menu, then unchanged task details are not saved.
Action
Description
Claim
If a task is assigned to a group or multiple users, then the task must be claimed first.
Claim is the only action available in the Task Action list for group or multiuser
assignments. After a task is claimed, all applicable actions are listed.
Escalate
If you are not able to complete a task, you can escalate it and add an optional
comment in the Comments area. The task is reassigned to your manager (up one level
in a hierarchy).
Pushback
Use this action to send a task down one level in the workflow to the previous
assignee.
The pushback action overrides all other actions. For example, if a task is pushed back
and then reassigned, after the reassignee approves it, the task goes to the user who
performed the pushback. This is the expected behavior.
Note:
Reassign
Release
If a task is assigned to a group or multiple users, it can be released if the user who
claimed the task cannot complete the task. Any of the other assignees can claim and
complete the task.
Renew
If a task is about to expire, you can renew it and add an optional comment in the
Comments area. The task expiration date is extended one week. A renewal appears in
the task history. The renewal duration for a task can be controlled by an optional
parameter. The default value is P7D (seven days).
Use these actions if another user requests that you supply more information or to
request more information from the task creator or any of the previous assignees. If
reapproval is not required, then the task is assigned to the next approver or the next
step in the business process.
If a task is not relevant, you can suspend it. These options are available only to users
who have been granted the BPMWorkflowSuspend role. Other users can access the
task by selecting Previous in the task filter or by looking up tasks in the Suspended
status. A suspension is indefinite. It does not expire until Resume is used to resume
working on the task.
Withdraw
If you are the creator of a task and do not want to continue with it, for example, you
want to cancel a vacation request, you can withdraw it and add an optional comment
in the Comments area. The business process determines what happens next. You can
use the Withdraw action on the home page by using the Creator task filter.
Initiate task
Re-initiate task
32-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Completion of task
Error of task
Expiration of task
Withdrawal of task
You can include the following actions in the short history list by modifying the
shortHistoryActions element.
Acquire
Ad hoc route
Delegate
Escalate
Push back
Reassign
Release
Renew
Resume
Suspend
Update
The history provides a graphical view of a task flow, as shown in Figure 3219.
Check Full task actions to see all actions performed, including those that do not make
changes to the task, such as adding comments, as shown in Figure 3220.
Figure 3220 History: Full Task Actions
Aggregate tasks
Note: The history of a parent task also displays the history of any
subtasks it contains.
32-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
the worklist. For such tasks, a Route button appears on the task details page. From the
Route page, you can look up one or more users for routing. When you specify multiple
assignees, you can select whether the list of assignees is for simple (group assignment
to all users), sequential, or parallel assignment.
Parallel tasks are created when a parallel flow pattern is specified for scenarios such as
voting. In this pattern, the parallel tasks have a common parent. The parent task is
visible to a user only if the user is an assignee or an owner or creator of the task. The
parallel tasks themselves (referred to as subtasks) are visible to whomever the task is
assigned, just like any other task. It is possible to view the subtasks from a parent task.
In such a scenario, the task details page of the parent task contains a View SubTasks
button. The SubTasks page lists the corresponding parallel tasks. In a voting scenario,
if any of the assignees updates the payload or comments or attachments, the changes
are visible only to the assignee of that task.
A user who can view the parent task (such as the final reviewer of a parallel flow
pattern), can drill down to the subtasks and view the updates made to the subtasks by
the participants in the parallel flow. The parent task is a container for the subtasks
while they are worked on by the assignees. The task owner must not act on or approve
the parent task.
If a human task was set up to require a password, then when you act on it, you must
provide the password, as shown in Figure 3221.
Figure 3221
Note:
2.
3.
Select the names by clicking on the check box and click OK.
You can reassign to multiple users or groups. One of the assignees must claim the
task, as shown in Figure 3224.
32-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
2.
Request information from a past approver or search for a user name, or push the
task back to the previous assignee, as shown in Figure 3226.
Figure 3226 Requesting Information from Past Approvers or Another User, or Pushing
the Task Back
If you use the Search icon to find a user name, the Identity Browser appears, as
shown in Figure 3227.
Figure 3227 Identity Browser
Note:
3.
Click OK.
To route a task:
1. From the Task Actions list, select Adhoc Route, as shown in Figure 3228.
Figure 3228 Ad Hoc Routing
2.
32-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3229
Single Approver: Use this option for a single user to act on a task. If the task is
assigned to a role or group with multiple users, then one member must claim
the task and act on it.
Group Vote: Use this option when multiple users, working in parallel, must
act, such as in a hiring situation when multiple users vote to hire or reject an
applicant. You specify the voting percentage that is needed for the outcome to
take effect, such as a majority vote or a unanimous vote, as shown in
Figure 3230.
Figure 3230
Routing a Task
Chain of Single Approvers: Use this option for a sequential list of approvers.
The list can comprise any users or groups. (Users are not required to be part of
an organization hierarchy.)
3.
4.
Provide or search for user or group names; then move the names to the Selected
area.
5.
Click OK.
1.
If you are the initiator of the task, then your comment is shared
with all process participants and not only with task assignees. The
option to share with only task participants is not available to you.
Comments added to a parent task also appear in any subtasks of
that parent.
Click Save before you browse for or upload attachments, to
ensure that any previous changes to the task details page are
saved.
When you remove a file or URL attachment, the task is not
automatically updated. You must explicitly select Actions > Save.
Otherwise, the attachment is not removed, even though it is
displayed as removed. This is the expected behavior.
If you add a file attachment, you do not need to explicitly select
Actions > Save.
If you add a URL attachment, you must explicitly select Actions >
Save.
In an environment with servers clustered for high availability
purposes, file uploading is not supported if a failover occurs. If
the active server shuts down, then the uploading process is not
assumed by the other server and the upload fails.
If you are using an ADF connection and you receive a "No
Protocol" error when attempting to add an attachment, verify that
your connections.xml file is synchronized with the correct
WSDL file. The connections.xml file is located in the directory
.adf/META-INF/ in your ADF workspace.
In the Comments or Attachments area, click Add. Figure 3231 provides details.
2.
Enter comment text and click OK. Comments cannot be deleted once they are
added.
The date and timestamp and your user name are included with the comment.
3.
For attachments, provide a file or URL attachment, as shown in Figure 3232, and
click OK.
32-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3232
Note:
For more information about file uploading, see the Oracle Fusion
Middleware Web User Interface Developer's Guide for Oracle Application.
4.
When you act on a task that has a signature policy, the Sign button appears, as shown
in Figure 3233.
The evidence store service is used for digital signature storage and nonrepudiation of
digitally signed human tasks. You can search the evidence store, as shown in
Figure 3234.
Figure 3234 The Evidence Store
See Section 34.1.10, "Evidence Store Service and Digital Signatures" for more
information.
To provide a digital signature:
1. In the upper right corner of Oracle BPM Worklist, click Preferences.
2.
3.
Upload the certificate to use to sign your decision, as shown in Figure 3235.
32-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When signing a task outcome using your certificate, you must upload the entire
chain of certificates through Oracle BPM Worklist as a .P7B (PKCS7 format) file,
not just the one certificate issued to you by the certificate issuer. The entire chain
can be exported through Internet Explorer. Mozilla Firefox does not let you export
the chain as a .P7B file. Therefore, you can perform the following steps:
a.
Export the chain from Mozilla Firefox as a .P12 file (PKCS12 format that also
contains your private key).
b.
c.
d.
Figure 3235
Uploading a Certificate
Note the following important points when providing your certificate to the
system. Otherwise, you cannot use your certificate to sign your decisions on tasks.
4.
The PKCS7 file format is a binary certificate format. Select this option if you
have a standalone certificate file stored on your disk.
The PKCS12 file format is a keystore format. Select this option if you have
your certificate stored inside a keystore.
If you want to copy and paste the contents of the certificate, select Type or
Paste Certificate Contents and paste the BASE64-encoded text into the field.
Do not paste a certificate in any other format into this field. Likewise, if you
choose to upload a certificate, do not try to upload a BASE64-encoded
certificate. Only PKCS12 and PKCS7 formatted files are supported for
uploads.
Return to the task list by clicking the Home link in the upper-right corner of
Oracle BPM Worklist.
Approving Tasks
5.
6.
7.
8.
Select the certificate from the dropdown list to use to sign your decision.
9.
Enter the master password of the web browser that you are using.
The web browser signs the string displayed in the upper half of the Text Signing
Request with the certificate you selected and invokes the action (approval or
rejection) that you selected. The task status is appropriately updated in the human
workflow service.
For more information about how certificates are uploaded and used, see
Section 34.1.10, "Evidence Store Service and Digital Signatures."
Admin
Owner (+
Owner
Group)
Reviewer Approver
Acquire
(Claim)
No
Yes
Yes
No
No
No
Custom
No
Yes1
Yes1
No
No
No
Delegate
No
No
Yes
No
No
No
Delete
No2
No2
Yes2
Yes2
No
No
Error
No
No
Yes3
No
No
No
Escalate
Yes4
Yes4
Yes
No
No
No
Info
Request
No
No
Yes
No
No
No
Info Submit No
No
Yes
No
No
No
Override
Routing
Slip
Yes
Yes
No
No
No
No
Push Back
No
No
Yes
No
No
No
Purge
Yes2
Yes2
No
Yes
No
No
Reassign
Yes5
Yes5
No
No
No
Release
Yes
Yes
Yes
No
No
No
Renew
No
Yes
Yes
No
No
No
Task
Action
32-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Admin
Owner (+
Owner
Group)
Reviewer Approver
Resume
Yes
Yes
Yes
No
No
No
Route
No
Yes
Yes
No
No
No
Skip
Yes
Current
Assignment
Yes
No
No
No
No
Suspend
Yes
Yes
Yes
No
No
No
Update
No
Yes
Yes
Yes
No
No
Update
Yes
Attachment
Yes
Yes
Yes
Yes
No
Update
Comment
Yes
Yes
Yes
Yes
Yes
No
View
Process
History
Yes
Yes
Yes
Yes
No
No
View Sub
Tasks
Yes
Yes
Yes
No
No
No
View Task
History
Yes
Yes
Yes
Yes
Yes
Yes
Withdraw
Yes
Yes
No
Yes
No
No
Task
Action
1
2
3
4
5
Vacation rules are not executed for ToDo tasks. See Section 32.7, "Setting Rules," for
how to set a vacation rule that is synchronized with the vacation period.
To create a vacation period:
1. Click the Preferences link.
The My Rules tab is displayed.
2.
3.
4.
Click Save.
The vacation period is enabled, as shown in Figure 3237.
32-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Setting Rules
A rule cannot always apply in all circumstances in which it is used. For example, if a
rule applies to multiple task types, it may not be possible to set the outcome for all
tasks, since different tasks can have different outcomes.
Rules are executed in the order in which they are listed. Rules can be reordered by
using the up and down buttons in the header, as shown in Figure 3238.
If a rule meets its filter conditions, then it is executed and no other rules are evaluated.
For your rule to execute, you must be the only user assigned to that task. If the task is
assigned to multiple users (including you), the rule does not execute.
You cannot specify business rules for ToDo tasks
Rule name
If the rule is a vacation rule. See Section 32.6, "Setting a Vacation Period," for how
to set the vacation period that is synchronized with the vacation rule.
Which task or task type the rule applies toIf unspecified, then the rule applies to
all tasks. If a task type is specified, then any attributes mapped for that task type
can be used in the rule condition.
When the rule applies
Setting Rules
Conditions on the ruleThese are filters that further define the rule, such as
specifying that a rule acts on priority 1 tasks only, or that a rule acts on tasks
created by a specific user. The conditions can be based on standard task attributes
and any mapped attributes that have been mapped for the specific tasks. See
Section 32.10.1, "How To Map Attributes," for more information.
1.
3.
32-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Setting Rules
Ensuring that high-priority tasks are routed to the least busy member of a group
3.
4.
Enter a group name and click the Search icon, or enter a group name.
The Identity Browser opens for you to find and select a group.
5.
Select the group name under the Group Rules node and click Add New Rule, as
shown in Figure 3239.
6.
A rule is created for user cdickens to reassign all assigned requests to user jstein.
2.
3.
Cdickens claims the task, and the task appears in their inbox.
The task is not automatically reassigned to jstein. The task is routed to jstein, following
the assignment rule set for cdickens, if user jcooper explicitly re-assigns the task only
to cdickens instead of reassigning the task to multiple users (cdickens and cdoyle).
An administrator can view and update all tasks assigned to all users. An
administrators Assignee filter displays Admin when the Admin tab is selected.
This section contains these topics:
32-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For information about specifying mapped attributes, see Section 32.10, "Using Mapped
Attributes (Flex Fields)"
3.
Search for the user or group for whom rules are to be created, as shown in
Figure 3240.
Figure 3240
4.
Click a user rules node, or click a group name (for a group rule).
5.
6.
32-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Figure 3245 shows the Application Preferences page with the Branding Logo field
highlighted. You reach the Application Preferences page by clicking Administration
on the global toolbar at the very top of the Worklist Application interface.
Figure 3245 Specifying the Branding Logo
32-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Refer to an external image-hosting web site. To do this task: In the Branding Logo
field, enter the URL of the image.
Upload an image to a particular location on the server and, in the Branding Logo
field, enter its relative path, for example, /afr/my_logo.png.
Refer to an image from the shared library. To do this task: In the Branding Logo
field, enter the path of the logo name as found in the shared library, for example,
/my_logo.pngv.
Customizing the branding logo from either the Worklist
Application or Process Workspace changes the logo in both
applications. For example, if you change the logo from Worklist, the
Workspace logo is changed automatically.
Note:
For information about deploying images and JAR files as part of a shared library, see
Oracle Fusion Middleware User's Guide for Oracle Business Process Management.
In the Branding Title field, enter a simple string for your title.
In the Branding Title field, enter a label that refers to a key-value pair in the
Resource Bundle. In this way, you can internationalize your title, for example,
LABEL_WORKLIST_TITLE.
To choose a skin:
Do one of the following:
From the Choose a Skin list, select one of the default ADF skins
Upload your own customized skin .css file in a .JAR file and deploy it as a part
of shared library. Then, when you restart your application from the console, your
custom skin appears in the Choose a Skin list.
In this example, you can change the word custom to the name of your own
customized skin.
2.
32-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Create the .JAR file by issuing the following command from the c:\temp
directory:
jar -cvf customSkin.jar META-INF/
4.
2.
Your custom application listed in the Links panel of the Process Workspace
Home page as shown in Figure 3249.
Figure 3249
From the lists in the Map task actions to an image field, select the tasks you want
to map to either the green check mark icon or the red X icon.
3.
Click Save.
32-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For example, you might want to create filters for messages received from customers
with different Service Level Agreements (SLA), specifying to be notified through
business phone and SMS channels for customers with a premium SLA and by EMAIL
for customers with a nonpremium SLA.
Data Type
Comparison Operators
Date
Time
Number
String
Note:
32.9.1.2 Attributes
Table 3210 lists the predefined attributes for messaging filters.
Table 3210
Attribute
Data Type
Total Cost
Number
From
String
Expense Type
String
To
String
Application Type
String
Duration
Number
Application
String
Process Type
String
Status
String
Subject
String
Customer Type
String
Time
Time
Group Name
String
Table 3210
Attribute
Data Type
Processing Time
Number
Date
Date
Due Date
Date
User
String
Source
String
Amount
Number
Role
String
Priority
String
Customer Name
String
Expiration Date
Date
Order Type
String
Organization
String
Classification
String
String
IM
MOBILE
SMS
VOICE
WORKLIST
Addresses for messaging channels are fetched from the configured identity store.
SMS and MOBILE notifications are sent to the mobile phone number.
32-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
You can use the Messaging Channels tab to view, create, edit, and delete messaging
channels.
3.
Address: The address for the channel, such as a phone number or email
address.
Default: Specifies whether this channel is the default messaging channel.
4.
Click View > Columns and select the columns to display or hide.
You can also click View > Reorder Columns to display a dialog to reorder the
displayed columns.
Messaging channel names and addresses are retrieved from the underlying
identity store, such as Oracle Internet Directory.
3.
Click View > Columns and select the columns to display or hide.
32-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
4.
Define the filter conditions using the lists and fields in the Condition section, as
follows:
a.
Select whether notifications must meet all of the conditions or any of the
conditions by selecting either the All of the following conditions or the Any
of the following conditions options.
b.
c.
d.
e.
f.
Repeat these steps to add more filter conditions. To remove a filter condition,
click Delete.
5.
To set the delivery channel, select a channel from the Add Notification Channel
list and click Add. To remove a channel, click Delete.
6.
Use the up and down arrows to prioritize channels. If available, the top-most
channel receives messages meeting the filter criteria if you select Send to the First
Available Channel.
7.
Click OK.
Using Oracle BPM Worklist 32-57
2.
Click Edit.
3.
Click OK to update the messaging filter. Click Cancel to dismiss the dialog
without modifying the filter.
2.
3.
Click OK to delete the messaging filter. Click Cancel to dismiss the dialog without
deleting the filter.
2.
These mappings are valid for a certain task type. Therefore, each task type can have
different mapped attribute mappings. After the mapping is complete and any new
task is initiated, the value of the payload is promoted to the mapped attribute. Tasks
initiated before the mapping do not contain the value in the mapped attribute. Only
top-level simple type attributes in the payload can be promoted to a mapped attribute.
Complex attributes or simple types nested inside a complex attribute cannot be
promoted. It is important to define the payload for a task in the Human Task Editor,
keeping in mind which attributes from the payload may must promoted to a mapped
32-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
attribute. All text and number mapped attributes are automatically included in the
keyword-based search.
Essentially, the Human Task Editor is used only when defining the payload for a task.
All other operations are performed at runtime.
Directory naming is not available concomitant with the flex file naming convention.
Note:
To create labels:
To create a mapped attribute mapping, an administrator first defines a semantic label,
which provides a more meaningful display name for the mapped attribute. Click Add
to use the Create Label dialog, as shown in Figure 3255.
Figure 3255 Creating a Label
As Figure 3255 shows, labelName is mapped to the task attribute TextAttribute3. The
payload attribute is also mapped to the label. In this example, the Text attribute type is
associated with labelName. The result is that the value of the Text attribute is stored in
the TextAttribute3 column, and labelName is the column label displayed in the users
task list. Labels can be reused for different task types. You can delete a label only if it is
not used in any mappings.
A mapped payload attribute can also be displayed as a column in a custom view, and
used as a filter condition in both custom views and workflow rules. The display name
of the payload attribute is the attribute label that is selected when doing the mapping.
Note the following restrictions:
A mapped attribute (and thus a label) can be used only once per task type.
Data type conversion is not supported for the number or date data types. For
example, you may not map a payload attribute of type string to a label of type
number.
1.
2.
Select a row in the label table to display all the payload attributes mapped to a
particular label.
32-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
With the task type displayed in the Edit mappings by task type field, click Go.
All current mappings for the task type are displayed, as shown in Figure 3258.
4.
Attribute
Data Type
customerAttributeString1
String
customerAttributeString2
String
customerAttributeNumber1 Double
customerAttributeNumber2 Double
customerAttributeDate1
Date
32-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3211
Attribute
Data Type
customerAttributeDate2
Date
Use the following Java Architecture for XML Binding (JAXB) methods to set and get
these attributes:
task.getCustomerAttributes.getCustomerAttributeString1()
task.getCustomerAttributes.setCustomerAttributeString1("String")
task.getCustomerAttributes.getCustomerAttributeNumber1()
task.getCustomerAttributes.setCustomerAttributeNumber2(9)
task.getCustomerAttributes.setCustomerAttributeDate1()
task.getCustomerAttributes.setCustomerAttributeDate2()
These fields are persisted in the database as customerAttributeString1,
customerAttributeString2, customerAttributeNumber1,
customerAttributeNumber2, customerAttributeDate1,
customerAttributeDate2.
Report Name
Description
Unattended Tasks
Provides an analysis of
tasks assigned to users'
groups or reportees' groups
that have not yet been
acquired (the "unattended"
tasks).
Input Parameters
Tasks Priority
Description
Input Parameters
Tasks Productivity
Provides an analysis of
assigned tasks and
completed tasks in a given
time period for a user,
reportees, or their groups.
Tasks Time
Distribution
1.
2.
3.
32-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3261
4.
Click Run.
The report shows that the California group has 15 unattended tasks, the Supervisor
group has 7 unattended tasks, and the LoanAgentGroup has 11 unattended tasks. The
unattended (unclaimed) tasks in this report are all DocumentReview tasks. If multiple
types of unattended task exists when a report is run, all task types are included in the
report, and the various task types are differentiated by color.
32-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The report shows that the California group, the Supervisor group, and the
LoanAgentGroup each have 16 tasks of normal priority. The users rsteven and jcooper
have 5 and 22 tasks, respectively, all normal priority. Priorities (highest, high, normal,
low, lowest) are distinguished by different colors in the bar chart.
The report shows that it takes 1 hour and 6 minutes on average to complete
DocumentReview tasks, and 1 hour and 28 minutes on average to complete
VacationApproval tasks. The bar chart shows the average cycle time in milliseconds.
The report shows the number of tasks assigned to the California, LoanAgentGroup,
and Supervisor groups. For individual users, the report shows that jcooper has 22
assigned tasks. In addition to his assigned tasks, jcooper has completed 2 tasks. The
report shows that mtwain and rsteven have completed 6 and 11 tasks respectively. In
the bar chart, the two task statesassigned and completedare differentiated by
color.
The Me and Group and Reportees options have been
removed from the Productivity Report.
Note:
32-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information, see the following sections for instructions on how to select
Browser or Identity Provider in the worklist interface:
Section 32.8.2, "How to Specify the Login Page Realm Label" for how to select
Browser or Identity Provider from the Application Preferences page
Section 32.3, "Customizing the Task List Page" and Figure 3214, "Customizing
Fields in a Worklist View"
However, this can be changed to a custom resource bundle by setting the appropriate
application preference (see Section 32.8.3, "How to Specify the Resource Bundle") or by
providing an updated version of the default bundle class. See the Workflow
Customizations sample for details.
For task attribute names, mapped attribute labels, and dynamic assignment function
names, the strings come from configuring the resource property file
WorkflowLabels.properties. This file exists in the wfresource subdirectory of
the services config directory. See Chapter 34, "Introduction to Human Workflow
Services" for information on adding entries to this file for dynamic assignment
functions and attribute labels.
For custom actions and task titles, the display names come from the message bundle
specified in the task configuration file. If no message bundle is specified, then the
values specified at design time are used. See Chapter 34, "Introduction to Human
Workflow Services" for information on how to specify message bundles so that custom
actions and task titles are displayed in the preferred language.
You cannot use Korean characters in the human task name. In
place of Korean characters, Oracle recommends using only letters A-Z,
a-z, 0-9, and "_" in the human task name.
Note:
32.12.2 How to Change the Preferred Language, Display Names of Users, and Time
Zone Settings if the Identity Store is LDAP-Based
If an LDAP-based provider such as Oracle Internet Directory is used, then language
settings are changed in the Oracle Internet Directory community. Connect to the
embedded LDAP server, where you can change language settings in the Oracle
Internet Directory community.
1.
2.
Connect to the LDAP server by providing the hostname, the port number on
which the server is running, and the administration user credentials with which to
log in.
b.
c.
3.
b.
c.
To change a user's preferred language, navigate to the user entry, and either add
or set the preferredLanguage attribute. See Table 3213, " Languages
Supported in Oracle BPM Worklist" for a list of supported languages.
You can also determine the language in which user names are displayed. To do
this task, navigate to the user entry in the LDAP directory, then add or specify the
displayname attribute. Note, however, that the user name that appears in the
Assignee column in the worklist does not honor the setting of the displayname
attribute.
To change the time zone setting, either add or set the orclTimeZone attribute.
The format of the time zone string is Continent/Region. You can find the time
zone values in the $JAVA_HOME/jre/lib/zi directory. The directories specify
the continent names, for example, Africa, Asia, America, and so on, while the files
within the directories specify the regions. Some regions include subregions, for
example America/Indiana/Indianapolis.
When a user logs in, the worklist pages are rendered in the user's preferred
language and time zone.
Note:
32-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Click human-workflow.
To change the language:
a.
b.
c.
d.
e.
Click Apply.
b.
c.
In the Value field, enter a value. For better performance, ensure that you
include only the languages that you need for task title, category, and
subcategory.
d.
Click Invoke.
32.12.4 How To Change the Language Preferences from a JAZN XML File
In the JAZN XML file, change the portion in bold to set the user's preferred language.
<preferredLanguage>en</preferredLanguage>
Language
Format
English
(en)
French
(fr)
German
(de)
Spanish (International)
(es)
Italian
(it)
Portuguese (Brazil)
(pt-BR)
Japanese
(ja)
Korean
(ko)
Chinese (Traditional)
(zh-TW)
Chinese (Simplified)
(zh-CN)
Arabic
(ar)
Czech
(cs)
Danish
(da)
Dutch
(nl)
Finnish
(fi)
Greek
(el)
Hebrew
(he)
Table 3213
Language
Format
Hungarian
(hu)
Norwegian
(no)
Polish
(po)
Portuguese
(pt)
Romanian
(ro)
Russian
(ru)
Slovak
(sk)
Swedish
(sv)
Thai
(th)
Turkish
(tr)
Canadian French
(fr-CA)
32.12.5 What You May Need to Know Setting Display Languages in Worklist
Oracle BPM Worklist can be configured to set the language from the browser or from
the identity store (LDAP). There are two levels to this setting: the application level and
the user level. If the user preference is set, as LDAP in the user setting, it takes
precedence in determining the worklist display language. If you do not set a language
in LDAP, worklist follows default language as server locale. However, email
notifications always follow the language set in LDAP. If no language is set in LDAP,
email notifications follow server locale.
The format of the time zone string is Continent/Region. You can find the time zone
values in the $JAVA_HOME/jre/lib/zi directory. The directories specify the
continent names, for example Africa, Asia, America, and so on, while the files within
the directories specify the regions. Some regions include sub-regions, for example
America/Indiana/Indianapolis.
32-72 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Open the View Controller Project Properties, Libraries and Classpath section, and
click Add Library to add the following libraries in the class path:
BPM Services
WSRP Container
3.
If your application runs on non-SOA server, you must perform two additional
steps.
a.
b.
4.
Select the View Controller project and choose File > New > Current Project
Technologies > Web Tier > JSF Page to create a jspx file (for example,
testSample.jspx).
Be sure to select Create as XML document (*.jspx) in the Create JSF Page dialog.
5.
32-74 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3269
6.
Component Palette
Drag and drop one of the task flow Regions to the jspx page, and select Region in
the Create menu (for example, taskList-task-flow-definition for Task List Task
Flow).
See the following sections for details about the task flow definitions:
Section 32.13.4, "What You May Need to Know About Task List Task Flow"
Section 32.13.5, "What You May Need to Know About Certificates Task Flow"
Section 32.13.6, "What You May Need to Know About the Reports Task Flow"
Section 32.13.7, "What You May Need to Know About Application Preferences
Task Flow"
Section 32.13.8, "What You May Need to Know About Mapped Attributes Task
Flow"
Section 32.13.9, "What You May Need to Know About Rules Task Flow"
Section 32.13.10, "What You May Need to Know About Approval Groups Task
Flow"
Section 32.13.11, "What You May Need to Know About Task Configuration
Task Flow"
7.
8.
9.
10. Before deploying the application, see Section 32.13.2, "How to Set Up the
Deployment Profile."
Select the domain name soainfra under Domain Structures. The domain name
may be different if a SOA server is not used.
3.
4.
5.
Enter a password in the Credential field. (The same password must be given for
all the federated servers).
6.
Click Save.
7.
32.13.4 What You May Need to Know About Task List Task Flow
The Task List task flow takes in the parameters to control the display behavior of the
embedded region. Figure 3270 provides details.
32-76 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Some of the parameters are listed below. For the full list of parameters, see
Section 36.4, "Passing Worklist Portlet Parameters."
federatedMode
federatedServers
showServerColumn
wfCtxID
federatedMode
If this is passed as true, the task list is shown in the federated mode. To run the task
flow in federated mode, the list of federated servers must be passed to the task flow.
You can pass the federated servers list to the task flow in one of the following two
ways.
If both the client configuration file (wf_client_config.xml) and the JAXB object
were provided to the task flow, the JAXB object takes the precedence.
federatedServers
This parameter is a JAXB object that contains the list of servers if the task flow is run in
federated mode. This parameter takes precedence over the client configuration file
(wf_client_config.xml) if it were also provided. See the code example in
Example 321 for details about to constructing the JAXB object
(WorkflowServicesClientConfigurationType).
Make sure that you set one of the servers as default, as shown in Example 321.
Only one server is required to be designated as the default. Also, verify that the server
you designate as the default is excluded from the federated servers list. The relevant
code for doing this is in bold in the example.
Using Oracle BPM Worklist 32-77
The default server is used when you have many servers defined in wf_client_
config.xml or in the JAXB object, but the workflow client is desired for a single
server. There are a few legacy APIs that do not take a server name as a parameter. To
support such legacy APIs, your must define a single server as the default server,
otherwise any legacy APIs that do not take a server name do not work.
Example 321
federatedServers
import oracle.bpel.services.workflow.client.config.IdentityPropagationType;
import oracle.bpel.services.workflow.client.config.PolicyReferenceType;
import oracle.bpel.services.workflow.client.config.PolicyReferencesType;
import oracle.bpel.services.workflow.client.config.RemoteClientType;
import oracle.bpel.services.workflow.client.config.ServerType;
import oracle.bpel.services.workflow.client.config.SoapClientType;
import
oracle.bpel.services.workflow.client.config.WorkflowServicesClientConfigurationTyp
e;
WorkflowServicesClientConfigurationType wscct =
new WorkflowServicesClientConfigurationType();
List<ServerType> servers = wscct.getServer();
/**** Setting default server in the list ****/
ServerType defalutServer = new ServerType();
servers.add(defalutServer);
defalutServer.setDefault(true);
defalutServer.setExcludeFromFederatedList(true);
defalutServer.setName("default");
RemoteClientType rct = new RemoteClientType();
rct.setServerURL("t3://myhost.us.example.com:7001");
rct.setInitialContextFactory("weblogic.jndi.WLInitialContextFactory");
rct.setParticipateInClientTransaction(false);
defalutServer.setRemoteClient(rct);
SoapClientType sct = new SoapClientType();
PolicyReferencesType prts = new PolicyReferencesType();
PolicyReferenceType prt = new PolicyReferenceType();
prt.setEnabled(true);
prt.setCategory("security");
prt.setUri("oracle/wss10_saml_token_client_policy");
prts.getPolicyReference().add(prt);
IdentityPropagationType ipt = new IdentityPropagationType();
ipt.setMode("dynamic");
ipt.setType("saml");
ipt.setPolicyReferences(prts);
sct.setRootEndPointURL("http://myhost.us.example.com:7001");
sct.setIdentityPropagation(ipt);
defalutServer.setSoapClient(sct);
/****** Setting Federated Server 1 to the list ****/
ServerType server1 = new ServerType();
32-78 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
servers.add(server1);
server1.setName("Human Resource");
RemoteClientType rct1 = new RemoteClientType();
rct1.setServerURL("t3://myhost.us.example.com:7001");
rct1.setInitialContextFactory("weblogic.jndi.WLInitialContextFactory");
rct1.setParticipateInClientTransaction(false);
server1.setRemoteClient(rct1);
SoapClientType sct1 = new SoapClientType();
PolicyReferencesType prts1 = new PolicyReferencesType();
PolicyReferenceType prt1 = new PolicyReferenceType();
prt1.setEnabled(true);
prt1.setCategory("security");
prt1.setUri("oracle/wss10_saml_token_client_policy");
prts1.getPolicyReference().add(prt1);
IdentityPropagationType ipt1 = new IdentityPropagationType();
ipt1.setMode("dynamic");
ipt1.setType("saml");
ipt1.setPolicyReferences(prts1);
sct1.setRootEndPointURL("http://myhost.us.example.com:7001");
sct1.setIdentityPropagation(ipt1);
server1.setSoapClient(sct1);
/****** Setting Federated Server 2 to the list ****/
ServerType server2 = new ServerType();
servers.add(server2);
server2.setName("Financials");
RemoteClientType rct2 = new RemoteClientType();
rct2.setServerURL("t3://myhost.us.example.com:7001");
rct2.setInitialContextFactory("weblogic.jndi.WLInitialContextFactory");
rct2.setParticipateInClientTransaction(false);
server2.setRemoteClient(rct2);
SoapClientType sct2 = new SoapClientType();
PolicyReferencesType prts2 = new PolicyReferencesType();
PolicyReferenceType prt2 = new PolicyReferenceType();
prt2.setEnabled(true);
prt2.setCategory("security");
prt2.setUri("oracle/wss10_saml_token_client_policy");
prts2.getPolicyReference().add(prt2);
IdentityPropagationType ipt2 = new IdentityPropagationType();
ipt2.setMode("dynamic");
ipt2.setType("saml");
ipt2.setPolicyReferences(prts2);
sct2.setRootEndPointURL("http://myhost.us.example.com:7001");
sct2.setIdentityPropagation(ipt2);
server2.setSoapClient(sct2);
showServerColumn
If the task flow is run in federated mode, the server column in the task list is not
shown by default. The server column is shown if this parameter is passed as true,
otherwise it is not.
wfCtxID
This is a workflow context token string. It is used to create workflow context inside the
task flow. If the application is SSO-enabled, or it is secured using ADF security, this
parameter is not required, otherwise this is a required parameter. You can get the
workflow context ID as shown in Example 322.
Example 322
wfCtxID
IWorkflowContext wfCtx =
wfSvcClient.getTaskQueryService().authenticate(username,
password,
realm,
null);
wfCtxID = wfCtx.getToken();
32.13.5 What You May Need to Know About Certificates Task Flow
The user can upload the certificate to use to sign a decision, as shown in the following
graphic. When signing a task outcome using your certificate, you must upload the
entire chain of certificates through Oracle BPM Worklist as a .P7B (PKCS7 format) file,
not only the one certificate issued to you by the certificate issuer.
A digital certificate contains the digital signature of the certificate-issuing authority, so
that anyone can verify that the certificate is real. A digital certificate establishes the
participant's credentials. It is issued by a certification authority (CA). It contains your
name, a serial number, expiration dates, a copy of the certificate holder's public key
(used for encrypting messages and digital signatures), and the digital signature of the
certificate-issuing authority, so that a recipient can verify that the certificate is real.
Certificates task flow does not have any parameters. Figure 3271 provides details.
32-80 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3271
Digital Certificate
32.13.6 What You May Need to Know About the Reports Task Flow
Figure 3272 shows the unattended tasks report.
Figure 3272
Assignee -This option (required) selects tasks assigned to the user's group (My
Group), tasks assigned to the reportee's groups (Reportees), tasks where the user is
a creator (Creator), or tasks where the user is an owner (Owner).
Task State - The state (optional) can by Any, Assigned, Expired, or Information
Requested.
Priority - The priority (optional) can be Any, Highest, High, Normal, Low, or
Lowest.
Tasks Priority
Tasks Priority provides an analysis of the number of tasks assigned to a user, reportees,
or their groups, broken down by priority.
Assignee - Depending on the assignee that you select, this required option
includes tasks assigned to the logged-in user (My), tasks assigned to the user and
groups that the user belongs to (My & Group), or tasks assigned to groups to
which the user's reportees belong (Reportees).
Creation Date - An optional date range
Ended Date - An optional date range for the end dates of the tasks to be included
in the report.
Priority - The priority (optional) can be Any, Highest, High, Normal, Low, or
Lowest.
Assignee - Depending on the assignee that you select, this required option
includes your tasks (My) or tasks assigned to groups to which your reportees
belong (Reportees).
Creation Date - An optional date range
Ended Date - An optional date range for the end dates of the tasks to be included
in the report.
Priority - The priority (optional) can be Any, Highest, High, Normal, Low, or
Lowest.
Tasks Productivity
Tasks Productivity provides an analysis of assigned tasks and completed tasks in a
given time period for a user, reportees, or their groups.
Assignee - Depending on the assignee that the user selects, this required option
includes the user's tasks (My & Group) or tasks assigned to groups to which the
user's reportees belong (Reportees).
Creation Date (range) - An optional creation date range. The default is one week.
Task Type - Use the Search (flashlight) icon to select from a list of task titles. All
versions of a task are listed on the Select Workflow Task Type page (optional).
Assignee - Depending on the assignee that the user selects, this required option
includes the user's tasks (My & Group) or tasks assigned to groups to which the
user's reportees belong (Reportees).
From...to (date range) - An optional creation date range. The default is one week.
32-82 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Task Type - Use the Search (flashlight) icon to select from a list of task titles. All
versions of a task are listed on the Select Workflow Task Type page (optional).
32.13.7 What You May Need to Know About Application Preferences Task Flow
Application preferences customize the appearance of the worklist. Administrators can
specify the following:
Login page realm label-If the identity service is configured with multiple realms,
then the Oracle BPM Worklist login page displays a list of realm names. LABEL_
LOGIN_REALM specifies the resource bundle key used to look up the label to
display these realms. The term realm can be changed to fit the user community.
Terms such as country, company, division, or department may be more
appropriate. Administrators can customize the resource bundle, specify a resource
key for this string, and then set this parameter to point to the resource key.
Global branding icon-This is the image displayed in the top left corner of every
page of the worklist. (The Oracle logo is the default.) Administrators can provide a
.gif, .png, or .jpg file for the logo. This file must be in the public_html
directory.
Resource bundle-An application resource bundle provides the strings displayed
in the worklist. By default, this is the class at
oracle.bpel.worklistapp.resource.WorklistResourceBundle.
Figure 3273 provides details.
32.13.8 What You May Need to Know About Mapped Attributes Task Flow
Human workflow mapped attributes store and query use case-specific custom
attributes. These custom attributes typically come from the task payload values.
Storing custom attributes in mapped attributes provides the following benefits:
For example the Requester, PurchaseOrderID, and Amount fields in a purchase order
request payload of a task can be stored in the mapped attributes. An approver logging
into Oracle BPM Worklist can see these fields as column values in the task list and
decide which task to access. The user can define views that filter tasks based on the
mapped attributes.
For example, a user can create views for purchase order approvals based on different
amount ranges. If the user must also retrieve tasks at some point related to a specific
requester or a purchase order ID, they can specify this in the keyword field and
perform a search to retrieve the relevant tasks. Figure 3274 provides details.
Figure 3274 Mapped Attribute Mapping
32.13.9 What You May Need to Know About Rules Task Flow
Rules act on tasks, either a specific task type, or all the tasks assigned to a user or
group. The graphic below shows where you set rules, including vacation rules.
A rule cannot always apply in all circumstances in which it is used. For example, if a
rule applies to multiple task types, it may not be possible to set the outcome for all
tasks, since different tasks can have different outcomes.
Rules are executed in the order in which they are listed. Rules can be reordered by
using the up and down buttons in the header. If a rule meets its filter conditions, then
it is executed and no other rules are evaluated. For your rule to execute, you must be
the only user assigned to that task. If the task is assigned to multiple users (including
you), the rule does not execute.
The showOtherUsersRules parameter takes a boolean value. When it is passed as
True other users rules are displayed, and when it is passed as False other users
rules are not shown. In addition, this user has to have required permission to view
other user rules. Figure 3275 and Figure 3276 provide details.
32-84 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3275
Vacation Period
32.13.10 What You May Need to Know About Approval Groups Task Flow
Approval groups are either a statically defined or a dynamically generated list of
approvers. Approval groups usually are configured by the process owner using the
worklist application. Typically, they are used to model subject matter experts outside
the transaction's managerial chain of authority, such as human resources or legal
counsel, that must act on a task before or after management approval.
Static approval groups are predetermined lists of approvers, while dynamic approval
groups generate approver lists at run time. Dynamic approval groups require:
32.13.11 What You May Need to Know About Task Configuration Task Flow
Task Configuration is a web-based application in Worklist Application that enables
business users and administrators to review and modify rules that were predefined by
the workflow designer. These predefined rules can be changed for a specific customer
based on the customers applicable corporate policies.
For example, suppose that a corporate policy requires two levels of approvals for
expense amounts greater than 1000. Suppose further that this policy is changed to
require three levels. You can use Task Configuration to change the rule rather than
having your IT department modify the rule in the underlying process and then deploy
it again. Any change to the rule is applied starting with the next instance, and
instances already in progress use the current rule definitions.
Task Configuration enables you to edit the event driven and data-driven rules
associated with an approval flow at run timethat is, when the workflow has already
been deployed.
oracle.bpel.services.workflow.client.IWorkflowServiceClient;
oracle.bpel.services.workflow.runtimeconfig.IRuntimeConfigService;
oracle.bpel.services.workflow.runtimeconfig.model.AttributeLabelType;
oracle.bpel.services.workflow.runtimeconfig.model.AttributeLabelUsageList;
oracle.bpel.services.workflow.runtimeconfig.model.AttributeLabelUsages;
oracle.bpel.services.workflow.verification.IWorkflowContext;
oracle.bpm.ui.customization.CustomLink;
oracle.bpm.ui.customization.IBPMUICustomizations;
32-86 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
null);
CustomLink globalLink3 =
new CustomLink("BUG DB", "https://bug.example.com/", null);
List<CustomLink> globalLinks = new ArrayList<CustomLink>();
globalLinks.add(globalLink1);
globalLinks.add(globalLink2);
globalLinks.add(globalLink3);
return globalLinks;
}
public String getColumnNames() {
return "title,taskNumber,instanceId,creator,protectedTextAttribute1";
}
private static void initDisplayMap(IWorkflowServiceClient client,
IWorkflowContext context) {
// you can use service to load all label namess for text attributes
if (displayNameMap == null) {
synchronized (String.class) {
if (displayNameMap == null) {
displayNameMap = new HashMap();
try {
IRuntimeConfigService service =
client.getRuntimeConfigService();
AttributeLabelUsageList list =
service.getAttributeLabelUsages(context, "Text");
List<AttributeLabelUsages> list1 =
list.getAttributeLabelUsages();
for (AttributeLabelUsages usage : list1) {
AttributeLabelType type = usage.getLabel();
displayNameMap.put(type.getTaskAttribute(),
type.getLabelName());
}
} catch (Exception exc) {
}
}
}
}
}
public String getColumnDisplayName(IWorkflowServiceClient client,
IWorkflowContext context,
java.lang.String colName) {
initDisplayMap(client, context);
return (String)displayNameMap.get(colName);
}
}
32-88 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
33
33
This chapter describes how, starting with the sample Worklist Application, a developer
can build clients for workflow services by using the APIs exposed by the workflow
service. The APIs enable clients to communicate with the workflow service by using
remote EJBs, SOAP, and HTTP.
This chapter includes the following sections:
3.
4.
5.
6.
Iterate over the list of tasks returned, performing actions on the tasks using
ITaskService.
Example 331 demonstrates how to build a client for workflow services. A list of all
tasks assigned to jstein is queried. A task whose outcome has not been set is approved.
Example 331
try
{
//Create JAVA WorflowServiceClient
IWorkflowServiceClient wfSvcClient = WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.REMOTE_CLIENT);
//Get the task query service
ITaskQueryService querySvc = wfSvcClient.getTaskQueryService();
//Login as jstein
IWorkflowContext ctx = querySvc.authenticate("jstein","welcome1".toCharArry(),null);
//Set up list of columns to query
List queryColumns = new ArrayList();
queryColumns.add("TASKID");
queryColumns.add("TASKNUMBER");
queryColumns.add("TITLE");
queryColumns.add("OUTCOME");
//Query a list of tasks assigned to jstein
List tasks = querySvc.queryTasks(ctx,
queryColumns,
null, //Do not query additional info
ITaskQueryService.AssignmentFilter.MY,
null, //No keywords
null, //No custom predicate
null, //No special ordering
0,
//Do not page the query result
0);
//Get the task service
ITaskService taskSvc = wfSvcClient.getTaskService();
//Loop over the tasks, outputting task information, and approving any
//tasks whose outcome has not been set...
for(int i = 0 ; i < tasks.size() ; i ++)
{
Task task = (Task)tasks.get(i);
int taskNumber = task.getSystemAttributes().getTaskNumber();
String title = task.getTitle();
String taskId = task.getSystemAttributes().getTaskId();
String outcome = task.getSystemAttributes().getOutcome();
if(outcome == null)
{
outcome = "APPROVE";
taskSvc.updateTaskOutcome(ctx,taskId,outcome);
}
System.out.println("Task #"+taskNumber+" ("+title+") is "+outcome);
}
}
catch (Exception e)
{
//Handle any exceptions raised here...
System.out.println("Caught workflow exception: "+e.getMessage());
}
oracle.bpel.services.workflow.metadata.config.model
33-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The classes in this package contain the object model for the workflow
configuration in the task definition file. The ObjectFactory class can create
objects.
oracle.bpel.services.workflow.metadata.routingslip.model
The classes in this package contain the object model for the routing slip. The
ObjectFactory class can create objects.
oracle.bpel.services.workflow.metadata.taskdisplay.model
The classes in this package contain the object model for the task display. The
ObjectFactory class can create objects.
oracle.bpel.services.workflow.metadata.taskdefinition.model
The classes in this package contain the object model for the task definition file. The
ObjectFactory class can create objects.
oracle.bpel.services.workflow.client.IWorkflowServiceClient
The interface for the workflow service client.
oracle.bpel.services.workflow.client.WorkflowServiceClientFacto
ry
The factory for creating the workflow service client.
oracle.bpel.services.workflow.metadata.ITaskMetadataService
The interface for the task metadata service.
oracle.bpel.services.workflow.task.ITaskService
The interface for the task service.
oracle.bpel.services.workflow.task.IRoutingSlipCallback
The interface for the callback class to receive callbacks during task processing.
oracle.bpel.services.workflow.task.IAssignmentService
The interface for the assignment service.
The other factory methods enable you to specify the connection properties directly
(rather than having the factory load them from the wf_client_config.xml file),
and enable you to specify a logger to log client activity.
The following enhancements to the workflow service clients are included in this
release:
You can specify the workflow client configuration using either a JAXB object or a
map, as shown in Example 332 and Example 333.
WorkflowServicesClientConfigurationType();
33-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 334
Through the factory, it is possible to get the client libraries for all the workflow
services. See Table 341, " Enterprise JavaBeans, SOAP, and Java Support" for the
clients available for each of the services.
You can obtain instances of BPMIdentityService and
BPMIdentityConfigService by calling the getSOAPIdentityServiceClient
and getSOAPIdentityConfigServiceClient methods on
WorkflowServiceClientFactory. You can obtain all other services through an
instance of IWorkflowServiceClient.
The client classes use the configuration file wf_client_config.xml for the service
endpoints. In the client class path, this file is in the class path directly, meaning the
containing directory is in the class path. The wf_client_config.xml file contains:
Example 335
<remoteClient>
<serverURL>t3://hostname.domain_name:7001</serverURL>
<userName>weblogic</userName>
<password>weblogic</password>
<initialContextFactory>weblogic.jndi.WLInitialContextFactory
</initialContextFactory>
<participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>
A section for SOAP endpoints for each of the services, as shown in Example 336.
Example 336
<soapClient>
<rootEndPointURL>http://hostname.domain_name:7001</rootEndPointURL>
<identityPropagation mode="dynamic" type="saml">
<policy-references>
<policy-reference enabled="true" category="security"
uri="oracle/wss10_saml_token_client_policy"/>
</policy-references>
</identityPropagation>
</soapClient>
Table 331
IWorkflowServiceClient Methods
Method
Interface
getTaskService
oracle.bpel.services.workflow.task.ITaskService
getTaskQueryService
oracle.bpel.services.workflow.query.ITaskQueryService
getTaskReportService
oracle.bpel.services.workflow.report.ITaskReportService
getTaskMetadataService
oracle.bpel.services.workflow.metadata.ITaskMetadataService
getUserMetadataService
oracle.bpel.services.workflow.user.IUserMetadataService
getRuntimeConfigService
oracle.bpel.services.workflow.runtimeconfig.IRuntimeConfigService
getTaskEvidenceService
oracle.bpel.services.workflow.metadata.ITaskMetadataService
${bea.home}/wlserver_10.3/server/lib/wlfullclient.jar
${bea.home}/AS11gR1SOA/webservices/wsclient_extended.jar
${bea.home}/AS11gR1SOA/soa/modules/oracle.soa.fabric_
11.1.1/bpm-infra.jar
${bea.home}/AS11gR1SOA/soa/modules/oracle.soa.workflow_
11.1.1/bpm-services.jar
${bea.home}/AS11gR1SOA/soa/modules/oracle.soa.fabric_
11.1.1/fabric-runtime.jar
You can generate the wlfullclient.jar file using the commands shown in
Example 337.
Example 337
cd ${bea.home}/wlserver_10.3/server/lib
java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar
Note:
wlfullclient.jar
wsclient_extended.jar
wlclient.jar
xmlparserv2.jar
xml.jar
bpm-infra.jar
bpm-services.jar
fabric-runtime.jar
33-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Initiating a Task
Note:
taskDefinitionId
title
payload
priority
The following task attributes are optional, but are typically set by clients:
creator
processInfo
The payload XML element contains all the other XML elements in it. Each XML
element defines a message attribute.
Example 338 shows how to set a task payload.
Example 338
import oracle.bpel.services.workflow.task.model.AnyType;
import oracle.bpel.services.workflow.task.model.ObjectFactory;
import oracle.bpel.services.workflow.task.model.Task;
..........
Document document = //createXMLDocument
Element payloadElem = document.createElementNS("http://xmlns.oracle.com/bpel/workflow/
task", "payload");
Initiating a Task
Note:
33-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
document.appendChild(payloadElem);
task.setPayloadAsElement(payloadElem);
IWorkflowServiceClient workflowServiceClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.SOAP_CLIENT);
ITaskService taskService = workflowServiceClient.getTaskService();
IInitiateTaskResponse iInitiateTaskResponse = taskService.initiateTask(task);
Task retTask = iInitiateTaskResponse.getTask();
System.out.println("Initiated: " + retTask.getSystemAttributes().getTaskNumber() + " - " +
retTask.getSystemAttributes().getTaskId());
return retTask;
33-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
font-size : 9pt;
}
table.banner
{
background-color: #eaeff5;
}
tr.userInfo
{
background-color: #eaeff5;
}
tr.problemInfo
{
background-color: #87b4d9;
}
</style>
</head>
<body bgcolor="White">
<%
HttpSession httpSession = request.getSession(false);
httpSession.setAttribute("pageType","STATUSPAGE");
%>
<table bordercolor="#eaeff5" border="4" width="100%">
<tr><td> <jsp:include page="banner.jsp"/> </td></tr>
</table>
<%
BPMUser bpmUser = null;
String redirectPrefix = request.getContextPath() + "/";
IWorkflowContext ctx = null;
if (httpSession != null) {
ctx = (IWorkflowContext) httpSession.getAttribute("workflowContext");
if (ctx != null) {
bpmUser = getAuthorizationService(ctx.getIdentityContext()).
lookupUser(ctx.getUser());
}
else
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
}
else
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
if(bpmUser == null)
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
String status = (String)httpSession.getAttribute("requeststatus");
if(status != null && !status.equals(""))
{
%>
<p></p>
<div style="text-align:left;color:red" >
<%= status %>
</div>
<%
}
httpSession.setAttribute("requeststatus",null);
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.REMOTE_CLIENT);
List displayColumns = new ArrayList();
displayColumns.add("TASKNUMBER");
displayColumns.add("TITLE");
displayColumns.add("PRIORITY");
displayColumns.add("STATE");
displayColumns.add("UPDATEDDATE");
displayColumns.add("UPDATEDBY");
displayColumns.add("CREATOR");
displayColumns.add("OUTCOME");
displayColumns.add("CREATEDDATE");
displayColumns.add("ASSIGNEEUSERS");
displayColumns.add("ASSIGNEEGROUPS");
List tasks = wfSvcClient.getTaskQueryService().queryTasks
(ctx,
displayColumns,
null,
ITaskQueryService.ASSIGNMENT_FILTER_CREATOR,
null,
null,
null,
0,
0);
%>
<p></p>
<div style="text-align:left;color:green" >
<b>
Previous help desk request
</b>
</div>
<p></p>
<div style="text-align:center" >
<table cellspacing="2" cellpadding="2" border="3" width="100%">
<TR class="problemInfo">
<TH>TaskNumber</TH>
<TH>Title</TH>
<TH>Priority</TH>
<TH>CreatedDate</TH>
<TH>Assignee(s)</TH>
<TH>UpdatedDate</TH>
<TH>UpdatedBy</TH>
<TH>State</TH>
<TH>Status</TH>
</TR>
<%
SimpleDateFormat dflong = new SimpleDateFormat( "MM/dd/yy hh:mm a" );
for(int i = 0 ; i < tasks.size() ; i ++)
{
Task task = (Task)tasks.get(i);
int taskNumber = task.getSystemAttributes().getTaskNumber();
String title = task.getTitle();
int priority = task.getPriority();
String assignee = getAssigneeString(task);
Calendar createdDate = task.getSystemAttributes().getCreatedDate();
Calendar updateDate = task.getSystemAttributes().getUpdatedDate();
String updatedBy = task.getSystemAttributes().getUpdatedBy().getId();
33-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
}
else
{
buffer.append(",");
}
buffer.append(name).append("(G)");
}
if(buffer == null)
{
return "";
}
else
{
return buffer.toString();
}
}
%>
</body>
</html>
33-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
34
Introduction to Human Workflow Services
34
This chapter describes for developers how the human workflow services in Oracle
SOA Suite are used. These services perform a variety of operations in the life cycle of a
task.
This chapter includes the following sections:
Note:
Task service
Identity service
34.1.1 SOAP, Enterprise JavaBeans, and Java Support for the Human Workflow
Services
Table 341 lists the type of Simple Object Access Protocol (SOAP), Enterprise
JavaBeans, and Java support provided for the task services. Most human workflow
services are accessible through SOAP and remote Enterprise JavaBeans APIs. You can
use these services directly by using appropriate client proxies. Additionally, the client
libraries are provided to abstract out the protocol details and provide a common
interface for all transports.
Table 341
Supports SOAP
Web Services
Service Name
Supports
Remote
Enterprise
JavaBeans
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Table 342 lists the location for the SOAP Web Services Description Language (WSDL)
file for each task service.
Table 342
Service name
Task Service
http://host:port/integration/services/TaskServi
ce/TaskServicePort?WSDL
http://host:port/integration/services/TaskQuery
Service/TaskQueryService?WSDL
Identity Service
http://host:port/integration/services/IdentityS
ervice/configuration?WSDL
http://host:port/integration/services/IdentityS
ervice/identity?WSDL
http://host:port/integration/services/TaskMetad
ataService/TaskMetadataServicePort?WSDL
34-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 342 (Cont.) SOAP WSDL Location for the Task Services
Service name
http://host:port/integration/services/UserMetad
ataService/UserMetadataService?WSDL
http://host:port/integration/services/TaskRepor
tService/TaskReportServicePort?WSDL
http://host:port/integration/services/RuntimeCo
nfigService/RuntimeConfigService?WSDL
http://host:port/integration/services/EvidenceS
ervice/EvidenceService?WSDL
Table 343 lists the JDNI names for the different Enterprise JavaBeans.
Table 343
Service name
Task Service
ejb/bpel/services/workflow/TaskServiceBean
ejb/bpel/services/workflow/TaskServiceGlobalTransa
ctionBean
ejb/bpel/services/workflow/TaskMetadataServiceBean
ejb/bpel/services/workflow/TaskQueryService
ejb/bpel/services/workflow/UserMetadataService
ejb/bpel/services/workflow/RuntimeConfigService
ejb/bpel/services/workflow/TaskReportServiceBean
ejb/bpel/services/workflow/TaskEvidenceServiceBean
For more information about the client library for worklist services, see Chapter 33,
"Building a Custom Worklist Client" for details.
In the Domain Structure, select Services > JDBC > Foreign JNDI Providers.
There is one caveat when linking remote Enterprise JavaBeans names to the local
JNDI namespace through a foreign JNDI provider from a SOA server to a
managed server or cluster in the same Oracle WebLogic Server domain. The local
JNDI names are exposed to all of the managed servers within that domain. This
causes namespace collisions on the SOA server within that domain, which already
has those Enterprise JavaBeans registered from the Oracle BPM Worklist. An
alternative, which avoids collisions while keeping configuration to a minimum, is
to use JNDI suffixing. This is done by appending a consistent suffix to the end of
all the local JNDI links of the remote workflow Enterprise JavaBeans and creating
a simple wf_client_config.xml file that contains the suffix key.
You can define client properties in either of three ways. For more information, see
Section 34.6.1.2, "Configuration Option."
3.
4.
Append the JNDI suffix to each Enterprise JavaBeans name shown in Table 343 to
register the foreign JNDI names.
ejb/bpel/services/workflow/TaskServiceGlobalTransactionean_s
erver1
ejb/bpel/services/workflow/TaskServiceBean_server1
ejb/bpel/services/workflow/TaskMetadataServiceBean_server1
TaskQueryService_server1
UserMetadataService_server1
RuntimeConfigService_server1
TaskReportServiceBean_server1
TaskEvidenceServiceBean_server1
Define the remote name by specifying only the ejbJndiSuffix element value in
the wf_client_config.xml file, as shown in Example 341. You can also use
the JAXB WorkflowServicesClientConfigurationType object or the
CONNECTION_PROPERTY.EJB_JNDI_SUFFIX in the Map<CONNECTION_
PROPERTY, String> properties.
Example 341
<remoteClient>
<ejbJndiSuffix>_server1</ejbJndiSuffix>
</remoteClient>
Token
The task query service exposes the authenticate operation that takes the login and
password and returns the human workflow context used for all services. Optionally,
with each request, you can pass the human workflow context with the login and
password.
34-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The authenticate operation also supports the concept of creating the context on
behalf of a user with the admin ID and admin password. This operation enables you to
create the context for a logged-in user to the Oracle BPM Worklist if the password for
that user is not available.
Oracle recommends that you get the workflow context one time and use it
everywhere. There are performance implications for getting the workflow context for
every request.
A realm is an identity service context from the identity configuration. The realm name
can be null if the default configuration is used.
Note:
Note:
In Example 342, the human workflow context is created for user jcooper.
Example 342
IWorkflowContext behalfOfCtx =
taskQueryService.authenticateOnBehalfOf(adminCtx,"jcooper");
Identity Propagation
This API returns a workflow context for the authenticated user if the client configures
the identity propagation for the appropriate client type. If the client type is remote,
Enterprise JavaBeans identity propagation is used with this method. If the client type
is SOAP, SAML token propagation is used with this method.
Method
Description
acquireTask
Acquire a task.
acquireTasks
addAttachment
addComment
createToDoTask
delegateTask
delegateTasks
deleteTask
deleteTasks
34-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
errorTask
escalateTask
escalateTasks
getApprovers
getFutureParticipants
getUsersToRequestInfo
ForTask
initiateTask
Initiate a task.
mergeAndUpdateTask
Merge and update a task. Use this operation when a partial task
should be updated. A partial task is one in which not all the
task attributes are present. In this partial task, only the
following task attributes are interpreted:
Task payload
Comments
Task state
Task outcome
overrideRoutingSlip
purgeTask
purgeTasks
pushBackTask
2.
3.
Reassign a task.
reassignTasks
Description
reinitiateTask
releaseTask
releaseTasks
removeAttachment
renewTask
requestInfoForTask
requestInfoForTaskWit
hReapproval
resumeTask
resumeTasks
routeTask
skipCurrentAssignment
submitInfoForTask
suspendTask
suspendTasks
updateOutcomeOfTasks
updatePriority
Update the priority of the task and its subtasks for the given
task ID. If UpdatePriorityType is INCREMENT then the task
is updated by incrementing the given priority by 1that is, the
priority of the task is raised. If the UpdatePriorityType is
DECREMENT, then the task is updated by decrementing the
priority by 1that is, the priority of the task is lowered,
otherwise the task is updated with the given priority.
34-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
updatePriorityOfTasks
For bulk update of tasks. A list of tasks for which the priority
must be updated can be passed as a parameter to this API. The
priorities of the list of tasks is updated. It updates the priority of
the task and its subtasks.
updateTask
updateTaskOutcome
updateTaskOutcomeAndR
oute
Update the task outcome and route the task. Routing a task
allows a user to route the task in an ad hoc fashion to the next
user(s) who must review the task. The user can specify to route
the tasks in serial, parallel, or single assignment. Routing a task
is permitted only when the human workflow permits ad hoc
routing of the task.
withdrawTask
The creator of the task can withdraw any pending task if they
are no longer interested in sending it further through the
human workflow. A task owner can also withdraw a task on
behalf of the creator. When a task is withdrawn, the business
process is called back with the state attribute of the task set to
Withdrawn.
withdrawTasks
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle SOA Suite
Method
Description
authenticate
countViewTasks
Counts the number of tasks that match the query criteria of the
specified view.
createContext
doesTaskExist
doesViewTaskExist
Checks to see if any tasks exist match the query criteria of the
specified view.
Description
getWorkflowContext
getTaskDetailsByNumber Gets the details of a specific task from the task's task number
property.
getTaskHistory
Gets a list of the task versions for the specified task ID.
getTaskSequence
Gets the task sequence tree of a task whose ID is a task ID, for
those type of sequences.
getTaskVersionDetails
Gets the specific task version details for the specified task ID
and version number.
queryTaskErrors
34-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
queryTasks
34-11
All providers are supported through Oracle Identity Management. The OracleAS
JAAS Provider (JAZN) and LDAP providers are no longer supported. The custom
provider is deprecated and supported only for backward compatibility. All
customization of providers is performed through the custom provider to Oracle
Identity Management, through configuring Oracle Virtual Directory (OVD) as an
LDAP provider to Oracle Identity Management, or through both. OVD aggregates
data across various repositories.
The OPSS layer is used, which includes the following:
Identity store
Policy store
Credential store
Framework
For more information, see Oracle Fusion Middleware Application Security Guide. All
security configuration is done through the jps-config.xml file.
SOAAdmin: Grant this role to users who must perform administrative actions
on any SOA module. This role is also granted the BPMWorkflowAdmin and
B2BAdmin roles.
workflow.mapping.protectedFlexField
workflow.admin.evidenceStore
workflow.admin
34-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Oracle Fusion Middleware Application Security Guide for details about OPSS
Oracle Fusion Middleware Application Developer's Guide for Oracle Identity
Management for details about Oracle Identity Management
Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory for details
about OVD
34-13
Identity Service
Provider Plug-ins
11g IDM
XML
Third Party
LDAP
L
XM
LDAP
Oracle
Internet
Directory
Database
Oracle
Internet
Directory
Database
Database
Database
Repository
34.1.5.1.1 Custom User Repository Plug-ins Starting with release 11g, custom provider
plug-ins in the identity service are not supported. All identity customizations are now
done in the identity store. Oracle Fusion Middleware supports providers that enable
the User and Role API to interact with custom identity stores. For more information,
visit the following URL:
http://www.oracle.com/technetwork/middleware/id-mgmt/overview/index.htm
l
Method
Description
getTaskMetadataByName Gets the TaskMetadata object that describes the human task
space
service component with the specified task definition namespace
and composite version.
getOutcomes
getResourceBundleInfo Gets the resource bundle information of the task. The resource
bundle information contains the location and the name of the
bundle.
34-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
getRestrictedActions
getVersionTrackedAttr Gets the task attributes that when changed cause a task version
s
creation.
listTaskMetadata
For more information, see Oracle Fusion Middleware Workflow Services Java API Reference
for Oracle SOA Suite.
Method
Description
createRule
34-15
Description
decreaseRulePriorit Decreases the priority of a rule by one. This method does nothing if
y
this rule has the lowest priority.
deleteRule
Deletes a rule.
getVacationInfo
Retrieves the date range (if any) during which a user is unavailable
for the assignment of tasks.
getRuleDetail
getRuleList
updateRule
increaseRulePriorit Increases the priority of a rule by one. Rules for a user or group are
y
maintained in an ordered list of priority. Higher priority rules
(those closer to the head of the list) are executed before rules with
lower priority. This method does nothing if this rule has the highest
priority.
getUserTaskViewList Gets a list of the user task views that the user owns.
getGrantedTaskViewL Gets a list of user task views that have been granted to the user by
ist
other users. Users can use granted views for querying lists of tasks,
but they cannot update the view definition.
getStandardTaskView Gets a list of standard task views that ship with the human
List
workflow service, and are available to all users.
getUserTaskViewDeta Gets the details for a single view.
ils
createUserTaskView
updateUserTaskView
deleteUserTaskView
updateGrantedTaskVi Updates details of a view grant made to this user by another user.
ew
Updates are limited to hiding or unhiding the view grant (hiding a
view means that the view is not listed in the main inbox page of
Oracle BPM Worklist), and changing the name and description that
the granted user sees for the view.
getUserPreferences
Gets a list of user preferences for the user. User preferences are
simple name-value pairs of strings. User preferences are private to
each user (but can still be queried and updated by a user with the
workflow.admin privilege).
setUserPreferences
Sets the user preference values for the user. Any preferences that
were previously stored and are not in the new list of user
preferences are deleted.
getPublicPreference Gets a list of public preferences for the user. Public preferences are
s
similar to user preferences, except that any user can query them.
However, only the user that owns the preferences, or a user with
the workflow.admin privilege, can update them. Public
preferences are useful for storing application-wide preferences
(preferences can be stored under a dummy user name, such as
MyAppPrefs).
setPublicPreference Sets the public preferences for the user.
s
setVacationInfo
Sets a date range over which the user is unavailable for the
assignment of tasks. (Dynamic assignment functions do not assign
tasks to a user that is on vacation.)
34-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
getStandardTaskView Gets the full details for a particular standard view, identified by its
Details
viewId.
Chapter 32, "Using Oracle BPM Worklist" for details about the rule configuration
and user preference pages
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle SOA Suite
Report
Description
34-17
users with the workflow.admin privilege can call setTaskDisplayInfo, but any
authenticated user can call getTaskDisplayInfo.
The runtime config service allows administrators to create mappings between simple
task payload attributes and these mapped attributes.
Only a user with the workflow.mapping.publicFlexField or
workflow.mapping.protectedFlexField privilege can make updates to payload
mappings for public mapped attributes. Only a user with the
workflow.mapping.protectedFlexField privilege can make updates to payload
mappings for protected mapped attributes. Any authenticated user can use the query
methods in this service.
An administrator can create attribute labels for the various mapped attributes. These
attribute labels provide a meaningful label for the attribute (for example, a label
Location may be created for the mapped attribute TextAttribute1). A given
mapped attribute may have multiple labels associated with it. This attribute label is
what is displayed to users when displaying lists of attributes for a specific task in
Oracle BPM Worklist. The attribute labels for a specific task type can be determined by
calling the getTaskAttributesForTaskDefinition method on the task metadata
service.
When defining attribute labels, the following fields are automatically populated by the
service. You do not need to specify values for these attributes when creating or
updating attribute labels:
Id
CreatedDate
WorkflowType
Active
Valid values for the task attribute field for public mapped attributes are as follows:
Mappings can then be created between task payload fields and the attribute labels. For
example, the payload field customerLocation can be mapped to the attribute label
Location. Different task types can share the same attribute label. This allows payload
attributes from different task types that have the same semantic meaning to be
mapped to the same attribute label.
Note: Only payload fields that are simple XML types can be
mapped.
Methods for querying the dynamic assignment functions supported by the server
Methods for maintaining the task display URLs used for displaying the task
details in Oracle BPM Worklist and other applications
Methods for getting the server HTTP and JNDI URLs
34-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 349 describes the methods in the runtime config service. Package
oracle.bpel.services.workflow.runtimeconfig corresponds to the runtime
config service.
Table 349
Method
Description
CreateAttributeLabel
createPayloadMapping
DeleteAttributeLabel
deletePayloadMapping
getAttributeLabelUsag Gets a list of attribute labels (either all attribute labels or labels
es
for a specific type of attribute) for which mapping (if any) the
labels are currently used.
getGroupDynamicAssign Returns a list of the dynamic assignment functions that can
mentFunctions
select a group that are implemented on this server.
getTaskDisplayInfo
getTaskStatus
updateAttributeLabel
Section 34.3.1, "Dynamic Assignment and Task Escalation Patterns" for additional
details
Chapter 32, "Using Oracle BPM Worklist" for details about mapped attribute
mappings
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle SOA Suite
34-19
Adding entries to these files for attribute labels is optional. If no entry is present in the
file, the name of the attribute label as specified using the API is used instead.
Is authentic
Asks the user to choose the private key to use for signing.
Generates a digital signature using the private key and task content provided by
Oracle BPM Worklist.
34-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Certificate
Human
Workflow
Task Content
Signature
Stored
Signature
Task Content
Notes:
34-21
34.1.10.1 Prerequisites
Prerequisites for using digital signatures and certificates are as follows:
2.
3.
4.
5.
6.
Click addTrustedCA.
7.
Provide values for caName and caURL. You must do this for each certificate in
the trust chain. For example, values provided for each invocation may look as
shown in Table 3410.
Table 3410
caName
caURL
CN = Intg, OU
=AppServ, O =Oracle,
C = US
http://www.oracle.com/Integration%20CRL%20Data.
crl
CN = Intg1, OU
=AppServ, O =Oracle,
C = US
http://www.oracleindia.in.com/Integration%20In.
crl
CN = Intg2, OU
=AppServ, O =Oracle,
C = US
http://www.oracle.us.com/integration.crl
8.
Click Invoke.
ITaskEvidenceService Interface
Method
Description
createEvidence
34-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3411
Method
Description
getEvidence
uploadCertificate
updateEvidence
Table 3412
Evidence Interface
Method
Description
getCertificate
getCreateDate
getErrorMessage
getEvidenceId
getPlainText
getPolicy
getSignature
getSignedDate
getStatus
Gets the CRL validation status. This can be one of the following:
getTaskId
Gets the unique identifier of the task with which this evidence is
associated.
getTaskNumber
Gets the task number of the task with which this evidence is
associated.
getTaskPriority
Gets the task priority of the task with which this evidence is
associated.
getTaskStatus
Gets the task status of the task with which this evidence is
associated.
getTaskSubStatus
Gets the task substatus of the task with which this evidence is
associated.
getTaskTitle
Gets the title of the task with which this evidence is associated.
34-23
Table 3412
Method
Description
getTaskVersion
getVerifiedDate
Gets the date on which the CRL validation of the certificate used
was performed.
getWorkflowType
Gets the workflow type of the task with which this evidence is
associated. This is typically BPELWF.
Table 3413
Certificate Interface
Method
Description
getCA
getCertificate
getID
getIdentityContext
getUserName
isValid
Table 3414
Method
Description
fromValue
value
Section 29.9.2, "How to Specify a Workflow Digital Signature Policy" for details
about specifying digital signatures and digital certificates in the Human Task
Editor
Chapter 30, "Designing Task Forms for Human Tasks" for details about digitally
signing a task action in the Oracle BPM Worklist
Task Attributes
Description
task/creator
task/dueDate
The due date for the task. This is used on to-do tasks.
34-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3415
Description
task/identificationKey
task/identityContext
The identity realm under which the users and groups are
seeded. In a single realm environment, this defaults to the
default realm.
task/ownerGroup
The group (if any) that owns this task instance. Task owners
can be application roles, users, or groups. If the owner of the
task is a group, this field is set.
task/ownerRole
The application role (if any) that owns this task instance. Task
owners can be application roles, users, or groups. If the owner
of the task is an application role, this field is set.
task/ownerUser
The user (if any) that owns this task instance. Task owners can
be application roles, users, or groups. If the owner of the task
is a user, this field is set.
task/payload
task/startDate
The start date for the task. This is used on to-do tasks.
task/subCategory
task/taskDefinitionId
task/taskDisplayUrl
task/title
Table 3416 lists the attributes that capture process metadata information.
Table 3416
Attribute
Description
task/processInfo/domain
task/sca/applicationName
task/sca/componentName
task/sca/compositeDN
34-25
Table 3416
Attribute
Description
Attachment-related attributes
Attribute
Description
Comment-related Attributes
Attribute
Description
task/userComment/comment
task/userComment/updatedBy
Table 3419 lists the attributes manipulated by the workflow services system.
Table 3419
Attribute
34-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3419
Attribute
34-27
Table 3419
Attribute
Mapped Attributes
Description
On application servers other than Oracle Fusion Middleware, the human workflow
email notification layer can be used for email notifications.
For more information about configuring the Oracle User Messaging Service, see the
following:
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite for instructions on configuring notification
service delivery channels in Oracle Enterprise Manager Fusion Middleware
Control
34-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Task attachments:
For notifications that include task attachments.
Actionable links
Notifications through SMS, IM, and voice contain only the notification message.
The notification message is an XPath expression that can contain static text and
dynamic values. In creating the messages, only the task BPEL variable is available for
dynamic values. This restriction is because the messages are evaluated outside the
context of the BPEL process. The payload in the task variable is also strongly typed to
contain the type of the payload for XPath tree browsing. The XPath extension function
hwf:getNotificationProperty(propertyName) is available to get properties
for a particular notification. The function evaluates to corresponding values for each
notification. The propertyName can be one of the following values:
recipient
The recipient of the notification
recipientDisplay
The display name of the recipient
taskAssignees
The task assignees
taskAssigneesDisplay
The display names of the task assignees
locale
The locale of the recipient
taskId
The ID of the task for which the notification is meant
taskNumber
The number of the task for which the notification is meant
appLink
The HTML link to the Oracle BPM Worklist task details page
34-29
'CONGRATULATIONS', hwf:getNotificationProperty('locale')))
If the human workflow email notification layer and Oracle User Messaging
Service both fail before the Oracle User Messaging Service acknowledges
receipt of a message from the human workflow.
If the Oracle User Messaging Service is down. Message delivery is retried until
successful.
Notifications that cannot be delivered are retried three times and the address is
marked as invalid. The address is also added to the bad address list. If needed,
you can manually remove these addresses from the bad address list in Oracle
Enterprise Manager Fusion Middleware Control. Outgoing notifications are not
resent until the address is corrected. To guard against any incorrect identification,
the address is marked as invalid only for about an hour. No new notifications are
sent in this time.
Incoming notification responses from an address that has been identified as a
spam source are ignored.
Incoming notification messages are persisted.
Incoming notification responses that indicate notification delivery failure (for
example, an unknown host mail) are not ignored. Instead, corrective actions are
automatically taken (for example, the bad address list is updated).
Incoming notification responses can be configured to send acknowledgements
indicating notification status to the sender.
Validation of incoming notification responses is performed by correlating the
incoming notification message with the outgoing notification message.
34-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite
View failed notifications and erroneous incoming notification responses and take
corrective actions.
Perform corrective actions such as delete, resend, and edit on outgoing
notifications and addresses.
View bad emails and block email addresses for incoming notification responses.
Access runtime data of failed notifications. You can purge this data when it is no
longer needed.
For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
3.
34-31
4.
ALL
The email, IM, SMS, and voice channels are configured and notification is sent
through any channel.
EMAIL
Only the email channel is configured for sending notification messages.
NONE
No channel is configured for sending notification messages. This is the default
setting.
Prepackaged strings (action links, comments, Oracle BPM Worklist, and so on)
These strings are internationalized in the product as part of the following package:
oracle.bpel.services.workflow.resource
Notification message
To use values from the resource bundle specified during the task definition,
use the following XPath extension function:
hwf:getTaskResourceBundleString(taskId, key, locale?)
This function returns the internationalized string from the resource bundle
specified in the task definition.
The locale of the notification recipient can be retrieved with the following
function:
hwf:getNotificationProperty('locale')
34-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If a different resource bundle is used, then use the following XPath extension
to retrieve localized messages:
orcl:get-localized-string()
For more information, see Section 29.6.2, "How to Specify Multilingual Settings."
Note:
To send task attachments with the notification message, select Send task
attachments with email notifications.
When an actionable email arrives, perform the following tasks.
3.
Click the Approve link to invoke a new email window with approval data.
Figure 343 provides details.
34-33
4.
Add comments in the comments section of the approval mail. For example:
This contract has been approved based on the attached information.
5.
6.
Do not change anything in the subject or the body in this email. If you change the
content with the NID substrings, the email is not processed.
7.
Click Send.
8.
Set properties such as incoming server, outgoing mail server, outgoing user name
and password, and others from the Oracle User Messaging Service section of
Oracle Enterprise Manager Fusion Middleware Control.
9.
10. In the Workflow Task Service Properties page of Oracle Enterprise Manager Fusion
34-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
34-35
To send reminders:
1. Set reminders in the Advanced tab of the Notification section of the Human Task
Editor. Reminder configuration involves the following parameters:
Recurrence:
Specifies the number of times reminders are sent. The possible values for
recurrence are EVERY, NEVER, 0, 1, 2 , 10.
RelativeDate:
Specifies if the reminder duration is computed relative to the assigned date or
to the expiration date of the task. The possible values for the relativeDate
are ASSIGNED, EXPIRATION, and BEFORE DUE DATE. The final value
appears in Oracle JDeveloper if you modify the escalation and expiration
policy of the task to use the option Action Requested Before (known as Use
Due Date in previous releases).
Duration:
Specifies the duration from the relativeDate and the first reminder and
each reminder since then. The data type of duration is xsd:duration, whose
format is defined by ISO 8601 under the form PnYnMnDTnHnMnS. The capital
letters are delimiters and can be omitted when the corresponding member is
not used. Examples include PT1004199059S, PT130S, PT2M10S, P1DT2S,
-P1Y, or P1Y2M3DT5H20M30.123S.
WorkflowLabels.properties
34-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
34-37
Assignment Pattern
Type
Description
LEAST_BUSY
Dynamic
assignment
MOST_PRODUCTIVE
Dynamic
assignment
ROUND_ROBIN
Dynamic
assignment
These patterns all check a users vacation status. A user that is currently unavailable is
not automatically assigned tasks.
Dynamic assignment patterns can be used when defining a task participant, as
described in Section 29.4.3, "How to Configure the Single Participant Type". They can
also be used with task-assignment rules allowing end-users to specify dynamic
assignment of tasks to the members of groups that they manage, as described in
Section 32.7.2, "How To Create Group Rules."
The dynamic assignment patterns can also be called by using an xpath function in any
xpath expression in the task definition.
The signature of the function is:
hwf:dynamicTaskAssign(patternName, participants, inputParticipantType,
targetAssigneeType, isGlobal, invocationContext, parameter1, parameter2, ...,
parameterN)
34-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example usages:
hwf:dynamicTaskAssign(LEAST_
BUSY,jcooper,jstein,mtwain,user,user,true,ErrorAssignee)
hwf:dynamicTaskAssign(MOST_
PRODUCTIVE,task:task/task:payload/task:users,user,user,false,OwnerUser,T
IME_PERIOD=7)
hwf:dynamicTaskAssign(LEAST_BUSY,DeveloperRole,application_role,group):
Before 11g Release 1 (11.1.1.7), dynamic assignment could be achieved by using the
XPath functions wfDynamicUserAssign and wfDynamicGroupAssign. These
XPath functions have been deprecated in 11g Release 1 (11.1.1.7). They can still be
used, but Oracle recommends that you migrate any existing usage of these XPath
functions to the new dynamicTaskAssign function.
Implementations must provide support for selecting a single assignee from a list of
participants (all of the same type) by implementing the method
getAssigneeFromParticipantList.
An implementation does not have to support all assignee types. The interface provides
the method getSupportedAssigneeType to enable the implementation to specify
which types of assignee it supports.
Implementations can accept input parameters to specify selection criteria, the Dynamic
Assignment Framework validates these input parameters, and the implementation can
define its parameters (if any) in the method getPatternParameters().
An implementation can also accept initialization parameters, which are set when the
implementation is initialized by the framework. The parameter values are defined in
the human workflow configuration (either via configMBean, or by Human Workflow
34-39
These interfaces do not offer all the features available in the new
IDynamicAssingmentPattern interface, and have been deprecated. The Dynamic
Assignment Framework remains backward compatible with implementations that use
the old interface, but Oracle recommends that you migrate any implementations you
have to use the new interface.
For information about the Javadoc for dynamic assignment interfaces and utilities, see
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process
Manager.
name:
The name of the pattern
classpath:
The fully qualified class name of the class that implements the pattern.
In addition, each pattern can optionally have any number of properties. These
properties are simple name-value pairs that are passed as initialization parameters to
the pattern.
The property values specified in these tags are passed as a map (indexed by the value
of the name attributes) to the setInitParameters method of the dynamic
assignment patterns.
Two of the out-of-the-box patterns have initialization parameters. These are:
ROUND_ROBIN
The parameter MAX_MAP_SIZE specifies the maximum number of sets of users or
groups for which the pattern can maintain ROUND_ROBIN counts. The dynamic
assignment pattern holds a list of users and groups in memory for each group (or
list of users and groups) on which it is asked to execute the ROUND_ROBIN pattern.
MOST_PRODUCTIVE
The parameter DEAFULT_TIME_PERIOD specifies the length of time (in days) over
which to calculate the users productivity. This value can be overridden when
calling the MOST_PRODUCTIVE dynamic assignment pattern.
34-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about configuring the dynamic assignment functions from
Oracle Enterprise Manager Fusion Middleware Control, see Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
34-41
Adding entries to these files for dynamic assignment patterns is optional. If no entry is
present in the file, then the name of the function (for example, ROUND_ROBIN) is used
instead.
For more information about the WorkflowLabels.properties file, see the
workflow-110-workflowCustomizations sample available with the Oracle SOA
Suite samples.
The assignment when a user updates the task outcome. When the task outcome is
updated, the task can either be routed to other users or completed.
The assignees from whom information for the task can be requested.
If the task supports reapproval from Oracle BPM Worklist, a user can request
information for reapproval.
The users who reapprove the task if reapproval is supported.
The human workflow service identifies and invokes the assignment service for a
particular task to determine the task assignment.
For example, a simple assignment service iteration is as follows:
1.
2.
3.
When jcooper approves the task, the assignment service assigns the task to
jstein. The assignment service also specifies that a notification must be sent to
the creator of the task, jlondon.
34-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
jstein approves the task and the assignment service indicates that there are no
more users to whom to assign the task.
Task document
The task document that is executed by the human workflow. The task
document contains the payload and other task information like current state,
and so on.
Map of properties
When an assignment service is specified, a list of properties can also be
specified to correlate callbacks with back-end services that determine the task
assignees.
Task history
The task history is a list of chronologically-ordered task documents to trace the
history of the task. The task documents in this list contain a subset of
attributes in the actual task (such as state, updatedBy, outcome,
updatedDate, and so on).
You can implement your own assignment service plug-in that the human workflow
service invokes during human workflow execution.
Example 346 provides a sample IAssignmentService implementation named
TestAssignmentService.java.
Example 346
34-43
34-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
reapprovalUsers.add("jstein");
reapprovalUsers.add("wfaulk");
reapprovalUsers.add("cdickens");
return reapprovalUsers;
}
private Participants createParticipant() {
if (numberOfApprovals > 2) {
numberOfApprovals = 0;
return null;
}
String user = users[numberOfApprovals++];
ObjectFactory objFactory = new ObjectFactory();
Participants participants = objFactory.createParticipants();
Participant participant = objFactory.createParticipantsTypeParticipant();
participant.setName("Loan Agent");
ResourceType resource2 = objFactory.createResourceType(user);
resource2.setIsGroup(false);
resource2.setType("STATIC");
participant.getResource().add(resource2);
participants.getParticipantOrSequentialParticipantOrAdhoc().
add(participant);
return participants;
}
}
34-45
Notes:
Use the Human Task Editor to integrate the rule in a human workflow.
For more information, see Section 29.7.6, "How to Specify Escalation Rules."
IAssignmentService
IRestrictedAssignmentService
IRoutingSlipCallback
IPercentageCompletionCallback
INotificationCallback
Additionally, to support backward compatibility, the project level resource bundles can
also be in the same directory as the .task file.
34-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
It is possible for API clients to override this locale by setting a new value in the
IWorkflowContext object. Oracle BPM Worklist provides a user preference option
that allows users to use their browser's locale, rather than the locale set in their user
directory.
You can customize this bundle to provide alternatives for existing display strings or to
add additional strings (for example, for mapped attribute labels, standard views, or
custom dynamic assignment functions).
The global resource bundle provides resource strings for the following:
Task attributes:
Labels for the various task attributes displayed in Oracle BPM Worklist (or other
clients). Resource string values are returned from the following
TaskMetadataService methods:
getTaskAttributes
getTaskAttributesForTaskDefinition
getTaskAttributesForTaskDefinitions
34-47
Mapped attribute labels created through the runtime config service. These strings
are used in Oracle BPM Worklist when displaying mapped attributes. Resource
string values are returned from the TaskMetadataService methods:
getTaskAttributesForTaskDefinition
getTaskAttributesForTaskDefinitions
If translated resource strings are required for mapped attribute mappings, then
customize the WorkflowLabels.properties bundle to include the appropriate
strings.
Task outcomes:
Default resource strings for common task outcomes. These can be overridden by
the task resource bundle, as described above. The resource strings are returned by
the TaskMetadataService method getTaskDefinitionOutcomes, if no
task-specific resource bundle has been specified. As shipped, the global resource
bundle contains resource strings for the following outcomes:
Approve
Reject
Yes
No
OK
Defer
Accept
Acknowledge
Notification messages:
Resource strings used when the task service sends automatic notifications. These
can be customized to suit user requirements.
34-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
oracle.bpel.worklistapp.resource.WorkflowResourceBundle:
This contains strings used by both the ADF Oracle BPM Worklist, and the
JSP-based sample Oracle BPM Worklist that shipped with version 10.1.3 of Oracle
SOA Suite.
oracle.bpel.worklistapp.resource.WorklistResourceBundle:
This contains strings used only by the ADF Oracle BPM Worklist.
34-49
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
to provide your own customized resource strings for the task detail ADF task flow
application.
stage_name=translated_value
participant_name=translated_value
3.
4.
5.
Click caseSensitive.
6.
7.
Click setValue.
8.
If you are upgrading from 10.1.3, which by default was case sensitive, set
caseSensitive to true for the system to be the same as with 10.1.3.
34-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
Task service
To use any of these services, you must use the abstract factory pattern for workflow
services. The abstract factory pattern provides a way to encapsulate a group of
individual factories that have a common theme.
Perform the following tasks:
Get the IWorkflowServiceClient instance for the specific service type. The
WorkflowServiceClientFactory provides a static factory method to get
IWorkflowServiceClient according to the service type.
Use the IWorkflowServiceClient instance to get the service instance to use.
<workflowServicesClientConfiguration>
<server name="default" default="true">
<remoteClient>
<serverURL>t3://myhost.us.example.com:7001</serverURL>
<userName>weblogic</userName>
<password>weblogic</password>
<initialContextFactory>weblogic.jndi.WLInitialContextFactory
</initialContextFactory>
<participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>
<soapClient>
<rootEndPointURL>http://myhost.us.example.com:7001</rootEndPointURL>
<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>
The client configuration file can contain definitions for several configurations. Each
server must have its own unique name. If the configuration file defines multiple
servers, one server must be set with the default attribute equal to true. The
workflowServicesClientConfiguration has an optional attribute named
serverType that can be set to one of the following: LOCAL, REMOTE, or SOAP. Each
server can override the client type by using the optional attribute clientType.
Example 348 provides details.
Introduction to Human Workflow Services
34-51
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
Example 348
In Example 348, server2 uses the default clientType of REMOTE, while server1
overrides the default clientType value to use the clientType of SOAP. The same
rule applies if the JAXB WorkflowServicesClientConfigurationType object is
used instead of the wf_client_config.xml file.
If the configuration defines a client type, you can use the factory method from the
WorkflowServiceClientFactory class. Example 349 provides details.
Example 349
34-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
java.util.ArrayList;
java.util.HashMap;
java.util.List;
java.util.Map;
import oracle.bpel.services.workflow.IWorkflowConstants;
import oracle.bpel.services.workflow.WorkflowException;
import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
import oracle.bpel.services.workflow.client.IWorkflowServiceClientConstants
.CONNECTION_PROPERTY;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.query.ITaskQueryService.AssignmentFilter;
import oracle.bpel.services.workflow.query.ITaskQueryService.OptionalInfo;
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.verification.IWorkflowContext;
public class WFClientSample {
public static List
try {
34-53
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
PROPAGATION,"non-saml"); // optional
}
// 2. gets IWorkflowServiceClient for specified client type
wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(clientType, properties,
null);
// 3. gets ITaskQueryService instance
taskQuerySvc = wfSvcClient.getTaskQueryService();
// 4. gets IWorkflowContext instance
wfCtx = taskQuerySvc.authenticate("jcooper", "welcome1".toCharArray(),
"jazn.com");
// 5. creates displayColumns
List<String> displayColumns = new ArrayList<String>(8);
displayColumns.add("TASKID");
displayColumns.add("TASKNUMBER");
displayColumns.add("TITLE");
displayColumns.add("CATEGORY");
// 6. creates optionalInfo
List<ITaskQueryService.OptionalInfo> optionalInfo = new
ArrayList<ITaskQueryService.OptionalInfo>();
optionalInfo.add(ITaskQueryService.OptionalInfo.DISPLAY_INFO);
// 7. creates assignmentFilter
AssignmentFilter assignmentFilter = AssignmentFilter.MY_AND_GROUP;
// 8. creates predicate
List<String> stateList = new ArrayList<String>();
stateList.add(IWorkflowConstants.TASK_STATE_ASSIGNED);
stateList.add(IWorkflowConstants.TASK_STATE_INFO_REQUESTED);
Predicate predicate = new Predicate(TableConstants.WFTASK_STATE_COLUMN,
Predicate.OP_IN, stateList);
// 9. creates ordering
Ordering ordering = new Ordering(TableConstants.WFTASK_DUEDATE_COLUMN,
true, false);
ordering.addClause(TableConstants.WFTASK_CREATEDDATE_COLUMN, true,
false);
// 10. calls service - query tasks
List taskList = taskQuerySvc.queryTasks(wfCtx,
(List<String>) displayColumns,
(List<OptionalInfo>) optionalInfo,
(AssignmentFilter)
assignmentFilter,
(String) null, // keywords is
optional (see javadoc)
// optional
predicate,
ordering,
0,
// starting row
100); // ending row for paging, 0
if no paging
// Enjoy result
System.out.println("Successfuly get list of tasks for client type: " +
clientType +
34-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
JAXB object
wf_client_config.xml file
Property map
localClient
remoteClient
soapClient
Oracle recommends that you specify all clients. This is because some services (for
example, the identity service) do not have remote clients. Therefore, when you use
remote clients for other services, the identity service uses the SOAP service.
An example of a client configuration XML file is shown in Example 3413. The
configuration defines a server named default. The XML file must go into the client
applications EAR file.
Example 3413 Client Configuration
<workflowServicesClientConfiguration>
34-55
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
If you do so, the value from wf_client_config.xml found in the class path is used
by the client to access the services. If the file is not found in the class path and you do
not provide the setting according to the service type, a workflow exception is thrown.
If the properties map is null and the file is not found, an exception is thrown. If the
34-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
client omits some properties in the map while the file is not found, the service call fails
at runtime (the properties are complementary to the file).
You can define client properties by using the WorkflowServiceClientFactory
method. Example 3415 provides details.
Example 3415 WorkflowServiceClientFactory Method
public static IWorkflowServiceClient getWorkflowServiceClient(String clientType,
Map<CONNECTION_PROPERTY, String> properties,
Logger logger) hrows WorkflowException
If the map defines a client type with the property CONNECTION_PROPERTY type, the
factory method in Example 3416 can be used:
Example 3416 Factory Method for CONNECTION_PROPERTY Type
public static IWorkflowServiceClient getWorkflowServiceClient(Map<CONNECTION_
PROPERTY, String> properties,
Logger logger) throws WorkflowException
Note:
34-57
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
properties.put(CONNECTION_PROPERTY.EJB_INITIAL_CONTEXT_
FACTORY,"weblogic.jndi.WLInitialContextFactory");
properties.put(CONNECTION_PROPERTY.EJB_PROVIDER_URL,
"t3://myhost.us.example.com:7001");
properties.put(CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL, "weblogic");
properties.put(CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS, "weblogic");
IWorkflowServiceClient client =
WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.REMOTE_CLIENT,
properties, null);
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
There are performance implications for getting the workflow context for every request.
This is also true for identity propagation. If you use identity propagation with
SAML-token or Enterprise JavaBeans, authenticate the client by passing null for the
user and password, get the workflow context instance, and use another service call
with workflow context without identity propagation.
IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_
SECURITY_PRINCIPAL
IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_
SECURITY_CREDENTIALS
34-59
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
The client reference to the policy URI must match the server policy URI. Otherwise,
SAML token propagation fails.
34.6.2.2.3 Identity Propagation Mode Setting in Configuration File In the configuration file,
you can define the propagation mode by using the <identityPropagation>
element in the <soapClient>, as shown in Example 3425.
Example 3425 <identityPropagation> Element
<soapClient>
<rootEndPointURL>http://myhost.us.example.com:7001</rootEndPointURL>
<identityPropagation mode="dynamic" type="saml">
<policy-references>
<policy-reference enabled="true" category="security"
uri="oracle/wss10_saml_token_client_policy"/>
</policy-references>
</identityPropagation>
</soapClient>
For more information, see Oracle Fusion Middleware Security and Administrator's Guide
for Web Services.
34-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services
34.6.2.2.4 Identity Propagation Mode Setting Through the JAXB Object You can
programmatically set the identity propagation mode with the JAXB object.
For more information about how to create and use the public key alias in the credential
store, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
34-61
Report Views
WFUNATTENDEDTASKS_VIEW
WFTASKCYCLETIME_VIEW
WFPRODUCTIVITY_VIEW
WFTASKPRIORITY_VIEW
34-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3423
Name
Type
TASKID1
VARCHAR2(64)
TASKNAME
VARCHAR2(200)
TASKNUMBER
NUMBER
CREATEDDATE
DATE
EXPIRATIONDATE
DATE
STATE
VARCHAR2(100)
PRIORITY
NUMBER
ASSIGNEEGROUPS
VARCHAR2(2000)
For example:
Query unattended tasks that have an expiration date of next week, as shown in
Example 3429.
Example 3429 Query of Unattended Tasks with an Expiration Date of Next Week
SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
WHERE expirationdate > current_date AND expirationdate < current_date +
7;
Query unattended tasks created in the last 30 days, as shown in Example 3431.
Name
Type
TASKID1
VARCHAR2(64)
TASKNAME
VARCHAR2(200)
TASKNUMBER
NUMBER
CREATEDDATE
DATE
ENDDATE
DATE
CYCLETIME
NUMBER(38)
34-63
For example:
Compute the average cycle time (task completion time) for completed tasks that
were created in the last 30 days, as shown in Example 3432.
Example 3432 Average Cycle Time for Completed Tasks Created in the Last 30 Days
SELECT avg(cycletime) FROM
(current_date - 30);
WFTASKCYCLETIME_VIEW
Query the average cycle time for all completed tasks created in the last 30 days
and group them by task name, as shown in Example 3433.
Example 3433 Average Cycle Time for All Completed Tasks Created in Last 30 days
Grouped by Task Name
SELECT taskname, avg(cycletime) FROM WFTASKCYCLETIME_VIEW WHERE
createddate > (current_date - 30) GROUP BY taskname;
Query the least and most time taken by each task, as shown in Example 3434.
Compute the average cycle time for tasks completed in the last seven days, as
shown in Example 3435.
Example 3435 Average Cycle Time for Tasks Completed in the Last Seven Days
SELECT avg(cycletime) FROM
(current_date - 7);
WFTASKCYCLETIME_VIEW
Query tasks that took more than seven days to complete, as shown in
Example 3436.
Name
Type
TASKNAME
VARCHAR2(200)
TASKID
VARCHAR2(200)
TASKNUMBER
NUMBER
USERNAME
VARCHAR2(200)
STATE
VARCHAR2(100)
34-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 3425
Name
Type
LASTUPDATEDDATE
DATE
For completed tasks, the state is null. Use decode(outcome, '', 'COMPLETED', outcome) in
queries.
For example:
Count the number of unique tasks that the user has updated in the last 30 days, as
shown in Example 3437.
Count the number of tasks that the user has updated (one task may have been
updated multiple times) in the last seven days, as shown in Example 3438.
WHERE
Count the number of tasks of each task type on which the user has worked, as
shown in Example 3439.
Example 3439 Number of Tasks of Each Task Type on Which the User has Worked
SELECT username, taskname, count(taskid) FROM WFPRODUCTIVITY_VIEW GROUP
BY username, taskname;
Count the number of tasks of each task type that the user has worked on in the last
100 days, as shown in Example 3440.
Example 3440 Number of Tasks of Each Task Type Worked on in the Last 100 Days
SELECT username, taskname, count(taskid) FROM WFPRODUCTIVITY_VIEW WHERE
lastupdateddate > (current_date -100) GROUP BY username, taskname;
Name
TASKID
Type
1
VARCHAR2(64)
TASKNAME
VARCHAR2(200)
TASKNUMBER
NUMBER
PRIORITY
NUMBER
OUTCOME
VARCHAR2(100)
ASSIGNEDDATE
DATE
UPDATEDDATE
DATE
34-65
Table 3426
Name
Type
UPDATEDBY
VARCHAR2(64)
For example:
Query the number of tasks updated by each user in each task priority, as shown in
Example 3441.
Example 3441 Number of Tasks Updated by Each User in Each Task Priority
SELECT updatedby, priority, count(taskid) FROM
BY updatedby, priority;
WFTASKPRIORITY_VIEW GROUP
Query the number of tasks updated by the given user in each priority, as shown in
Example 3443.
Example 3443 Number of Tasks Updated by the Given User in Each Priority
SELECT priority, count(taskid) FROM WFTASKPRIORITY_VIEW WHERE
updatedby='jstein' GROUP BY priority;
34-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
35
35
Section 35.1, "Configuring Your Environment for Invoking a BPEL Process from an
Excel Workbook"
Section 35.2, "Attaching Excel Workbooks to Human Task Workflow Email
Notifications"
35.1.1 How to Create an Oracle JDeveloper Project of the Type Web Service Data
Control
You use the Create Web Service Data Control Wizard to create the project.
To create an Oracle JDeveloper project of the type web service data control:
1. In Oracle JDeveloper, from the File menu, select New. The New Gallery dialog
appears.
2.
In the Categories section, expand Business Tier, then select Data Controls. The
corresponding items appear in the Items pane.
3.
In the Items pane, select Web Service Data Control and click OK. The Create Web
Service Data Control Wizard appears.
4.
Follow the instructions in the online Help for this wizard. As you follow these
instructions, you are prompted to select the WSDL file and operations to use for
this project.
Configuring Your Environment for Invoking a BPEL Process from an Excel Workbook
In the Categories section, from the Web Tier node, select JSF. The corresponding
items appear in the Items pane.
3.
In the Items pane, select JSF Page and then click OK. The Create JSF Page dialog
appears.
4.
Fill in the various fields by following the instructions in the online Help for this
dialog.
5.
When prompted, drag and drop the controls and fields from the Component
Palette that you are interested in using in the Excel document.
For an example of how to perform this task, see Section 35.2.3.3, "Task 3: Create a Valid
Page Definition File to Be Used in the Excel Workbook."
In the Project Properties dialog, select Technology Scope to view the list of
available technologies.
3.
Choose the ADF Desktop Integration and ADF Library Web Application
Support project technologies and add them to the Selected Technologies list.
4.
Click OK.
35.1.4 What Happens When You Add Desktop Integration to Your Oracle JDeveloper
Project
When you add the Oracle ADF-DI module to the technology scope of your project, the
following events occur:
The project adds the Oracle ADF-DI runtime library. This library references the
following .jar files in its class path:
wsclient.jar
adf-desktop-integration.jar
resourcebundle.jar
35-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Configuring Your Environment for Invoking a BPEL Process from an Excel Workbook
The previous list is not exhaustive. Adding Oracle ADF-DI to a project makes
other changes to web.xml. Some entries in web.xml are only added if they do not
exist.
When you add ADF Library Web Application Support to the technology scope of your
project, the projects web.xml file is modified to include the entries shown in
Example 351.
Example 351
<filter>
<filter-name>ADFLibraryFilter</filter-name>
<filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>ADFLibraryFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>adflibResources</servlet-name>
<servlet-class>oracle.adf.library.webapp.ResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>adflibResources</servlet-name>
<url-pattern>/adflib/*</url-pattern>
</servlet-mapping>
Ensure that the filter for ADF Library Web Application Support
(<filter-name>ADFLibraryFilter</filter-name>) appears below the
adfdiExcelDownload filter entries in web.xml, as shown in Example 352. This
action enables integrated Excel workbooks to be downloaded from the application.
Example 352
<filter>
<filter-name>adfdiExcelDownload</filter-name>
<filter-class>oracle.adf.desktopintegration.filter.DIExcelDownloadFilter</filter-c
lass>
</filter>
<filter>
<filter-name>ADFLibraryFilter</filter-name>
<filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
</filter>
...
<filter-mapping>
<filter-name>adfdiExcelDownload</filter-name>
<url-pattern>*.xlsx</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>adfdiExcelDownload</filter-name>
<url-pattern>*.xlsm</url-pattern>
</filter-mapping>
...
<filter-mapping>
<filter-name>ADFLibraryFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
For more information about web.xml, see Oracle Fusion Middleware Desktop Integration
Developer's Guide for Oracle Application Development Framework.
35.1.8 How to Specify the User Interface Controls and Create the Excel Workbook
For instructions, see Section 35.2.3.4, "Task 4: Prepare the Excel Workbook."
35-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
1.
2.
Modify the settings in the ADF-DI-enabled Excel sheet to point to the server on
which the task flow is deployed, then save this Excel sheet as part of the .war file
packaged for the ADF task flow. The steps for performing these tasks are covered
in Section 35.2.3, "Example: Attaching an Excel Workbook to Email Notifications."
Later, you use the page definition files generated in Section 35.1.2, "How to Create
a Dummy JSF Page."
Packaging the Excel workbook with the ADF task flow
assumes that there is a one-to-one correspondence between the ADF
task flow and the Excel sheet used for a workflow.
Note:
3.
Enable the ADF task flow project for desktop integration and deploy it to the
server.
35.2.2 What Happens During Runtime When You Enable Attachment of Excel
Workbooks to Human Task Workflow Email Notifications
Note the following end-user experience during runtime:
A user receives an email notification regarding a new task, with the Excel
attachment. When the attachment is opened, the user is directed to a login page
and prompted to enter a username and password. This login page is similar to the
login page for Oracle BPM Worklist.
The Excel workbook loads up with the task details (for example, task identifier,
payload, and so on). There are buttons corresponding to actions the user can take.
Clicking one of these buttons starts the BPEL process in which the task is a step.
The Excel workbook is added as an attachment only when the flag include task
attachments for the corresponding task is set to true.
Before adding the Excel workbook as an attachment, runtime verifies that a digital
signature is not enabled for the workflow.
When the ADF task flow is deployed to the server, such data as the hostname and
port number of the task flow URI is registered in the database.
When an email notification is created, runtime retrieves the hostname and port
number of the application server and the context root of the task flow application
from the database. It uses this information to find the Excel workbook,
workflow_name.xls.
35.2.3.1 Task 1: Enable the ADF Task Flow Project with Oracle ADF-DI Capabilities
In this task, you configure the web application to work with Oracle ADF-DI.
1.
Create an ADF task flow project based on a human task. This creates a data control
corresponding to the task and an .xml files corresponding to the task's structure.
Figure 351 shows Oracle JDeveloper with a sample project open.
2.
Add Oracle ADF Desktop Integration to the project by following the instructions
in Section 35.1.3, "How to Add Desktop Integration to Your Oracle JDeveloper
Project."
Figure 352 shows the Oracle JDeveloper Project Properties dialog when you add
Oracle ADF-DI to your project.
35-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
When the technology scopes mentioned in Step 2 are added to the project, verify
that the necessary events have occurred:
a.
b.
c.
Confirm that the entry ADF Desktop Integration Runtime exists and is
checked.
d.
e.
The previous list is not exhaustive. Adding ADF Desktop Integration and ADF
Library Web Application Support to the project makes other changes to
web.xml. Here is a sample snippet of the deployment descriptor:
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<description>...</description>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION
</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>Whether the 'Generated by...' comment at the bottom of ADF
Faces HTML pages should contain version number information.</description>
<param-name>oracle.adf.view.rich.versionString.HIDDEN</param-name>
<param-value>false</param-value>
</context-param>
<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter
</filter-class>
</filter>
<filter>
<filter-name>ADFLibraryFilter</filter-name>
<filter-class>oracle.adf.library.webapp.LibraryFilter
</filter-class>
</filter>
<filter>
<filter-name>adfBindings</filter-name>
<filter-class>oracle.adf.model.servlet.ADFBindingFilter
</filter-class>
</filter>
<filter>
<filter-name>adfdiExcelDownload</filter-name>
<filter-class>
oracle.adf.desktopintegration.filter.DIExcelDownloadFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>adfBindings</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>adfdiRemote</servlet-name>
</filter-mapping>
<filter-mapping>
<filter-name>adfBindings</filter-name>
<servlet-name>adfdiRemote</servlet-name>
</filter-mapping>
<filter-mapping>
<filter-name>adfdiExcelDownload</filter-name>
<url-pattern>*.xlsx</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>adfdiExcelDownload</filter-name>
<url-pattern>*.xlsm</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>ADFLibraryFilter</filter-name>
<url-pattern>/*</url-pattern>
35-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>resources</servlet-name>
<servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-clas
s>
</servlet>
<servlet>
<servlet-name>adflibResources</servlet-name>
<servlet-class>oracle.adf.library.webapp.ResourceServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>adfdiRemote</servlet-name>
<servlet-class>oracle.adf.desktopintegration.servlet.DIRemoteServlet</servlet-c
lass>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/adf/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/afr/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>adflibResources</servlet-name>
<url-pattern>/adflib/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>adfdiRemote</servlet-name>
<url-pattern>/adfdiRemoteServlet</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>35</session-timeout>
</session-config>
<mime-mapping>
<extension>html</extension>
<mime-type>text/html</mime-type>
</mime-mapping>
<mime-mapping>
<extension>txt</extension>
<mime-type>text/plain</mime-type>
</mime-mapping>
<mime-mapping>
<extension>xlsx</extension>
<mime-type>application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</m
ime-type>
</mime-mapping>
<mime-mapping>
<extension>xlsm</extension>
<mime-type>application/vnd.ms-excel.sheet.macroEnabled.12</mime-type>
</mime-mapping>
5.
6.
7.
8.
Ensure there are no compilation errors and the build completes successfully.
2.
From the Application menus, select Secure, then Configure ADF Security.
b.
c.
Click Finish.
b.
c.
35-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Once you have added ADF security, confirm that the following entries are added
to the web.xml file. If some entries are missing, add them manually. Form
authentication, using the login page created in Step 2 of Section 35.2.3.2, "Task 2:
Set up Authentication," is used.
<security-constraint>
<web-resource-collection>
<web-resource-name>allPages</web-resource-name>
<url-pattern>/</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Administrators</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>adfAuthentication</web-resource-name>
<url-pattern>/adfAuthentication</url-pattern>
</web-resource-collection>
<auth-constraint>
35-11
<role-name>Administrators</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name>jazn.com</realm-name>
<form-login-config>
<form-login-page>/LoginPage.jsp</form-login-page>
<form-error-page>/LoginPage.jsp</form-error-page>
</form-login-config>
</login-config>
<security-role>
<role-name>Administrators</role-name>
</security-role>
Figure 354 shows how these entries appear graphically in the Web Application
Deployment Descriptor dialog.
Figure 354 Oracle JDeveloper: Application Deployment Descriptor
4.
For every logical security role added in web.xml, make a corresponding entry in
weblogic.xml as follows:
<weblogic-web-app>
<auth-filter>oracle.bpel.services.workflow.client.worklist.util.FDIAuthFilter</
auth-filter>
<security-role-assignment>
<role-name>Administrators</role-name>
<principal-name>fmwadmin</principal-name>
<principal-name>users</principal-name>
</security-role-assignment>
.
.
</weblogic-web-app>
35-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
The ADF task flow web application is now configured for login capability that can be
used by the Excel workbook.
35.2.3.3 Task 3: Create a Valid Page Definition File to Be Used in the Excel
Workbook
The page definition file ExcelControlsPageDef.xml is used to create the Excel
workbook. Perform the following steps:
1.
Select Technologies > General > Simple Files > Java Class.
b.
2.
Create a data control for this newly created Java class. This data control provides
access to an API that retrieves all assigned tasks for a user. Figure 355 shows the
menu for creating the data control.
3.
Verify that the newly created data control TasksRetriever is visible in the Data
Control palette in the lower portion of the Application Navigator. Figure 356
shows the Application Navigator with the Data Control palette expanded.
35-13
Figure 356 Oracle JDeveloper: Application Navigator with Data Control Palette
Expanded
4.
Create a new JSF JSP page, namely, ExcelControls.jspx. This generates a page
definition that can be used by ADF-DI while authoring the Excel document.
Figure 357 provides details.
5.
Drag and drop the task node from the Data Controls palette to
ExcelControls.jspx.
6.
Select Human Task, then select Complete task with payload. Figure 358
illustrates the sequence of menus you use.
35-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
8.
Drag and drop one or more task actions to the .jspx file. In this example, as
shown in Figure 359, the actions APPROVE, REJECT, update, and Suspend are
added to create the entries in the page definition.
9.
Drag and drop the retrieveTasksForUser() method from the Data Controls palette
(expand the node TasksRetriever) to ExcelControls.jspx.
35-15
10. For now, click OK on the Edit Action Binding dialog. This creates a binding in
13. Depending on the number of task details to be exposed in the Excel workbook,
drag and drop as many ADF controls as needed. In this example, you expose only
as many task details as needed to develop a minimally-operational workbook.
14. Create a list binding in ExcelControlsPageDef.xml that can create a list of
35-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
later to create a list of an updatable table of expense items in the Excel workbook.
<list ListOperMode="navigation" IterBinding="ItemIterator"
id="expenseItemsList" StaticList="false">
<AttrNames>
<Item Value="itemName"/>
</AttrNames>
</list>
17. Click Save All.
18. Right-click the project and click Rebuild.
19. Ensure that there are no compilation errors and the build completes successfully.
For information about desktop requirements for running the ADF-DI solution, see
Chapter "Setting Up Your Development Environment" of Oracle Fusion Middleware
Desktop Integration Developer's Guide for Oracle Application Development Framework.
2.
Open Excel.
b.
c.
Click the Trust Center tab, then click Trust Center Settings.
d.
Click the Macro Settings tab, then click the checkbox labeled Trust Access to
the VBA project object model.
e.
Click OK.
3.
Run the setup tool that comes with the Oracle ADF-DI module. The setup tool is
stored in the following folder: JDEV_
HOME\jdeveloper\adfdi\bin\excel\client.
4.
5.
Click View, then click Refresh. This displays the Excel workbook in Oracle
JDeveloper.
6.
Run the conversion command on the Excel workbook. The Oracle ADF-DI module
stores the conversion tool, convert-adfdi-excel-solution.exe, in
ORACLE_JDEVELOPER_HOME\jdeveloper\adfdi\bin\excel\convert. To
convert the Excel workbook, execute the following command:
convert-adfdi-excel-solution.exe <workbook.xlsx> -attach
The Excel workbook is now enabled to use the Oracle ADF-DI framework.
7.
Open the Excel workbook and choose a page definition. In this use case, the page
definition is expensereporttaskflow_ExcelControlsPageDef.
Figure 3511 provides details.
35-17
8.
9.
35-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3512
For more information, see Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework.
10. From the Document Actions pane, insert ADF Bindings to create the
35-19
11. Insert a methodAction binding to create a button in Excel. Figure 3514 provides
details.
35-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
12. Insert a tree binding to create an ADF Table component. A table component is an
updatable table of records in Excel. For instance, the list binding expenseItemsList
is a candidate for a table component.
Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework for further
information about creating and modifying a Table component.
See Also:
35-21
b.
Figure 3516.
35-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3516
16. Click Save All. The ADF task flow is now ready for deployment.
For the Excel workbook to be sent as an attachment when a task is assigned, you
must configure the corresponding task in the SOA composite application:
a.
b.
c.
In the Advanced tab of the Notification section of the Human Task Editor,
verify that the Send task attachments with email notifications checkbox is
checked.
2.
3.
b.
Select Deploy > application_TaskFlow (in this example, the application task
flow is ExpenseReportTaskFlow).
c.
35-23
Invoke the deployed SOA composite application and verify that the assignee
receives the Excel workbook as part of the email notification. Figure 3517
provides details.
Note:
35-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Open the Excel workbook. You are directed to a login page. (This is
LoginPage.jsp from Section 35.1.2, "How to Create a Dummy JSF Page.")
3.
4.
All the assigned tasks for the logged-in user are retrieved in the Excel
workbook. Figure 3519 provides details.
35-25
You can navigate to the needed task from the list of assigned tasks and update
it as required. For instance, as shown in Figure 3520, you can upload new
expense items in the Expense Report application.
The Status column in the workbook indicates if the upload was successful.
Figure 3521 provides details.
35-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 3521
Also, you can perform actions on the task by clicking Approve, Reject,
Update, or Suspend. Figure 3522 provides details.
Figure 3522
Task Actions
35-27
35-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
36
Configuring Task List Portlets
36
This chapter describes how developers can configure the task list portlets. This action
enables you to review and act upon worklist tasks from an Oracle WebCenter Portal
portlet.
This chapter includes the following sections:
(Domain A)
Task List Portlet
(WSRP Portlet
Producer Application)
(Domain B)
Task List
Since the task list portlet is a WSRP portlet producer application, it must be
deployed on a managed server configured for deploying portlet producer
applications. For this to occur, you must install Oracle WebCenter Portal.
Oracle WebCenter Portal and Oracle SOA Suite must be installed in different
domains.
If the task list portlet producer application is installed on the SOA server, you can
skip the steps described in Section 36.2.3, "How to Connect the Task List Producer
to the Remote SOA Server."
The task list portlet producer application is deployed on the Oracle WebLogic
Server portlet server shown in Figure 361 (the host on which Oracle WebCenter
Portal is installed). The portlet server contacts the remote Oracle WebLogic Server
SOA server to access the task list using remote Enterprise JavaBeans (EJB) calls.
The portlet producer application EAR file is provided on the SOA server in the
following directory:
Oracle_Home/SOA_Home/soa/applications
36-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For this administration domain, start both the Oracle WebLogic Administration
Server and the Oracle WebLogic Server portlet managed server. See Oracle Fusion
Middleware Administrator's Guide for instructions on starting administration and
managed servers.
3.
Because the task list portlet producer application uses the deployed library
oracle.soa.workflow.wc, you must confirm that the library is targeted to the
Oracle WebLogic Server portlet managed server.
a.
where hostname and port are the hostname and port for the Oracle
WebLogic Server Administration Console.
4.
b.
c.
b.
c.
5.
Ensure that the WSRP producer application is running by accessing the WSDL
from a web browser:
http://server:port/TaskListTaskFlow/portlets/wsrp2?WSDL
36.2.3 How to Connect the Task List Producer to the Remote SOA Server
The task list portlet producer application communicates with the remote Oracle
WebLogic Server SOA managed server to get the task list for the logged-in user. See
Figure 361 for details. The task list portlet producer application uses remote EJB calls
to the human workflow services API to achieve this. Therefore, you must configure the
remote JNDI providers on the Oracle WebLogic Server on which Oracle WebCenter
Portal is installed.
36.2.3.1 How to Define the Foreign JNDI on the Oracle WebCenter Portal Oracle
WebLogic Server
To define the foreign JNDI on the Oracle WebCenter Portal Oracle WebLogic
Server:
1. Log in to Oracle WebLogic Server Administration Console:
http://remote_hostname:remote_port/console
where remote_hostname and remote_port are the hostname and port for the
remote Oracle WebCenter Portal Oracle WebLogic Server.
2.
3.
Click New.
4.
5.
Click OK.
6.
7.
Enter values for the fields listed in Table 361, then click Save.
Table 361
Field
Description
Enter weblogic.jndi.WLInitialContextFactory.
Provider URL
Enter t3://soa_hostname:soa_port/soa-infra.
Note: Replace soa_hostname and soa_port with the
hostname and port for the remote Oracle WebLogic Server SOA
server that includes the task list to retrieve.
User
Enter weblogic.
Password
Confirm Password
8.
Click ForeignJNDIProvider-SOA.
9.
Field
Values
Name
Enter RuntimeConfigService.
Enter RuntimeConfigService.
Enter RuntimeConfigService.
12. Repeat Step 11 six times and enter the values shown in Table 363 for the Name,
The...
Enter This Value in the Name, Local JNDI Name, and Remote JNDI Name
Fields, and click OK...
First time
ejb/bpel/services/workflow/TaskServiceBean
Second time
ejb/bpel/services/workflow/TaskMetadataServiceBean
Third time
TaskReportServiceBean
Fourth time
TaskEvidenceServiceBean
36-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Enter This Value in the Name, Local JNDI Name, and Remote JNDI Name
Fields, and click OK...
Fifth time
TaskQueryService
Sixth time
UserMetadataService
For more information about configuring a foreign JNDI provider, see the Oracle Fusion
Middleware Oracle WebLogic Server Administration Console Online Help.
On the left side of the page, select the domain name that you specified during
installation (for example, soainfra).
3.
4.
5.
Log in to the Oracle WebLogic Server Administration Console of the SOA server
Oracle WebLogic Server.
6.
Modify the domain credentials of the SOA server and enter the same password as
entered for the Oracle WebCenter Portal server in Step 4.
7.
Click Save.
The user first logs in to the consumer application. Therefore, the user must be present
in the identity store of this server. Then, when the consumer application contacts the
task list portlet producer application, it must propagate the user name to the Oracle
WebCenter Portal managed server. The same user name must also be present in the
identity store of this server. Then, to fetch the Oracle SOA Suite data, the task list
portlet producer application contacts the Oracle SOA Suite managed server. Therefore,
it must again propagate the user name to the SOA server. Again, the same user name
Configuring Task List Portlets 36-5
must be present in the identity store of the Oracle SOA Suite server. Alternatively, all
the above servers can point to the same identity store.
To configure the identity store:
1. Log in to the Oracle WebLogic Server Administration Console of the Oracle
WebCenter Portal Oracle WebLogic Server.
2.
See Section "Reassociating the Identity Store with an External LDAP" of Oracle
Fusion Middleware Administrator's Guide for Oracle WebCenter Portal for instructions
on configuring the identity store.
3.
36.2.4 How to Secure the Task List Portlet Producer Application Using Web Services
Security
You must perform the following tasks to secure the task list portlet producer
application:
Note:
To secure the task list portlet producer application using web services security:
1. See Sections "Securing a WSRP Producer with WS-Security" and "Securing Oracle
WebLogic Communication Services (OWLCS) with WS-Security" of Oracle Fusion
Middleware Administrator's Guide for Oracle WebCenter Portal for instructions on
enabling WS-Security and setting up the certificate keystores.
While following the instructions in those sections, you access the following pages
in Oracle Enterprise Manager Fusion Middleware Control.
a.
b.
c.
Access the Keystore section at the bottom of the provider configuration page
and click Configure, as shown in Figure 362.
36-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
d.
e.
f.
Restart the managed portlet server and the administration server for the
managed portlet server.
Creating a Portlet Consumer Application for Embedding the Task List Portlet
3.
4.
Select the markup port from the page that is displayed, as shown in Figure 364.
5.
6.
7.
Attach and detach policies appropriate to your use of the task list portlets
producer application (for example, oracle/wss10_saml_token_with_message_
integrity_service_policy).
The policy you select must be the same on both the consumer
and producer sides.
Note:
8.
9.
Restart the managed server to which the task list portlet producer application is
deployed.
36-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Portlet Consumer Application for Embedding the Task List Portlet
36.3.1 How To Create a Portlet Consumer Application for Embedding the Task List
Portlet
Follow these procedures to create a consumer application for embedding the task list
portlet.
To create a portlet consumer application for embedding the task list portlet:
1. Create a new Oracle WebCenter Portal application in Oracle JDeveloper:
a.
b.
c.
d.
Click Finish.
2.
3.
Register the WSRP producer with the consumer by dragging and dropping the
portlet on consumer.jspx:
a.
b.
c.
d.
Click OK.
A Register WSRP Portlet Producer wizard is displayed.
e.
f.
Creating a Portlet Consumer Application for Embedding the Task List Portlet
g.
h.
Click Next.
i.
where server is the host on which the portal service is installed and port is
the port on that server.
j.
36-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Portlet Consumer Application for Embedding the Task List Portlet
k.
Click Next.
l.
m. Click Next.
36-11
Creating a Portlet Consumer Application for Embedding the Task List Portlet
n.
From the Token Profile list, select a token profile appropriate to your
environment. For example, select the SAML Token with Message Integrity
token profile. The token profile selected must be the same as that selected
when you configured WS-Security on the task list portlet producer
application, as described in Section "Securing a WSRP Producer with
WS-Security" of Oracle Fusion Middleware Administrator's Guide for Oracle
WebCenter Portal.
o.
p.
q.
r.
Click the Browse button to select the consumer keystore (consumer.jks file)
you used for configuring web service security for the producer application in
Section 36.2.4, "How to Secure the Task List Portlet Producer Application
Using Web Services Security."
s.
36-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Portlet Consumer Application for Embedding the Task List Portlet
t.
Click Finish.
The registered portlets appear under Application Resources.
u.
36-13
Creating a Portlet Consumer Application for Embedding the Task List Portlet
v.
Drag the task list portlet named Worklist onto the JSPX page
consumer.jspx, as shown in Figure 3612.
w. Specify the height and width for the task list portlet suitable for your page, as
shown in Figure 3613. This dialog typically appears at the bottom right when
you select the portlet component that is dragged onto the page. If this dialog
does not appear, select Property Inspector from the View main menu.
36-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating a Portlet Consumer Application for Embedding the Task List Portlet
Figure 3613
x.
Figure 3614
36-15
4.
Provide values for the parameters described in Table 364. See Section 36.4,
"Passing Worklist Portlet Parameters" for additional details.
Table 364
Parameter
Description of Value
soaURL
5.
Secure the Oracle WebCenter Portal consumer application using ADF security by
following the steps provided in chapter "Enabling ADF Security in a Fusion Web
Application" of Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework (section "How to Enable Oracle ADF Security").
6.
Configure the identity store of the embedded Oracle WebLogic Server of Oracle
JDeveloper to point to that of the SOA server. You can do this by following the
steps described in Section 36.2.3.3, "How to Configure the Identity Store."
7.
b.
Select Run.
This starts the embedded Oracle WebLogic Server instance, deploys the
consumer application, and shows the portlet in the consumer.jspx page.
36-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Pass parameters to filter the task list, such as a list of task types and a task
attributes value list
Display Parameters
Parameters
Description
Values
Mandatory
Possible values:
No
title
number
priority
assignees
state
createdDate
expirationDate
refreshURL
Possible values:
identity (default)
browser
No
Yes
Possible values:
No
true (default)
false
Possible values:
true (default)
false
Possible values:
true (default)
false
No
No
36-17
Description
showViewFilter
showViewsPanel
soaURL
Values
Mandatory
Possible values:
No
true (default)
false
Possible values:
true
false (default)
Possible values:
true (default)
false
Possible values:
true
false (default)
No
No
No
Yes
No
sortOrder
Possible values:
No
wfCtxID
asc
desc (default)
36-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
No
Table 366
Parameters
Filter Parameters
Description
Values
Mandatory
No
Specifies the selected view for which the Enter a custom value that you
tasks are displayed.
create or accept the default value
of Inbox.
No
No
Possible values:
No
and
or (default)
For example, to see the task with attribute filter values as priority = 1, status =
ASSIGNED, and promoted mapped attribute textAttribute1 = NorthAmerica,
then you set the values as follows:
attributeFilterList: priority=1, status=ASSIGNED, textAttribute1=NorthAmerica
The parameters in Table 365 and Table 366 are defined in the page definition of the
test JSPX page. Example 361 shows the consumerPageDef.xml page definition file
syntax when the task list is consumed as a task flow. The attribute value has the value
of the parameter.
Example 361
Parameter Definition
<parameters>
<parameter id="showViewsPanel" value="#{testBean.showViewsPanel}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="showTaskDetailsPanel"
value="#{testBean.showTaskDetailsPanel}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="wfCtxID" value="#{testBean.wfCtxID}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="soaHostName" value="#{testBean.soaHostName}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="soaPort" value="#{testBean.soaPort}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="refreshURL" value="#{testBean.refreshURL}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="localeSource" value="#{testBean.localeSource}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="showActionDropdown" value="#{testBean.showActionDropdown}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="showViewFilter" value="#{testBean.showViewFilter}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
36-19
<parameter id="showAssignmentFilter"
value="#{testBean.showAssignmentFilter}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="showStatusFilter" value="#{testBean.showStatusFilter}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="showSearchControl" value="#{testBean.showSearchControl}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="assignmentFilter" value="#{testBean.assignmentFilter}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="viewFilter" value="#{testBean.viewFilter}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="displayColumnsList" value="#{testBean.displayColumnsList}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="sortColumn" value="#{testBean.sortColumn}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="sortOrder" value="#{testBean.sortOrder}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="taskTypesFilterList"
value="#{testBean.taskTypesFilterList}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="attributesFilterOperator"
value="#{testBean.attributesFilterOperator}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="attributesFilterList"
value="#{testBean.attributesFilterList}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
</parameters>
<variableIterator id="variables">
<variable Name="Worklist1_1_soaURL" Type="java.lang.Object"
DefaultValue="${'http://<soa_host>:<soa_port>'}" />
</variableIterator>
My
Group
My+Group
Reportees
Creator
Owner
Reviewer
Previous
Admin
36-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
package oracle.bpel.services.workflow.repos.table;
public interface WFTaskConstants
{
public static final String TABLE_NAME = "WFTask";
public static final String TL_TABLE_NAME = "WFTask_TL";
public static final String HISTORY_TABLE_NAME = "WFTaskHistory";
public static final String HISTORY_TL_TABLE_NAME = "WFTaskHistory_TL";
public static final String ASSIGNEE_TABLE_NAME = "WFAssignee";
public static final String REVIEWER_TABLE_NAME = "WFReviewer";
public
public
public
public
static
static
static
static
final
final
final
final
String
String
String
String
WFCOMMENT_TABLE_NAME = "WFComments";
WFATTRIBUTES_TABLE_NAME = "WFMessageAttribute";
WFATTACHMENT_TABLE_NAME = "WFAttachment";
WFCOLLECTIONTARGET_TABLE_NAME = "WFCollectionTarget";
//table aliases
public static
public static
public static
public static
public static
public static
public static
public static
public static
public static
final
final
final
final
final
final
final
final
final
final
String
String
String
String
String
String
String
String
String
String
TABLE_ALIAS = "wfn";
TL_TABLE_ALIAS = "wfntl";
HISTORY_TABLE_ALIAS = "wfnh";
HISTORY_TL_TABLE_ALIAS = "wfnhtl";
WFCOMMENT_TABLE_ALIAS = "wfc";
WFATTRIBUTES_TABLE_ALIAS = "wfma";
WFATTACHMENT_TABLE_ALIAS = "wfatt";
ASSIGNEE_TABLE_ALIAS = "wfa";
REVIEWER_TABLE_ALIAS = "wfr";
WFCOLLECTIONTARGET_TABLE_ALIAS = "wfct";
36-21
DIGITALSIGNATUREREQUIRED_COLUMN =
UPDATEDBYDISPLAYNAME_COLUMN = "updatedByDisplayName";
UPDATEDDATE_COLUMN = "updatedDate";
UPDATEDNOTIFICATIONID_COLUMN =
PASSWORDREQUIREDONUPDATE_COLUMN =
SECURENOTIFICATION_COLUMN = "secureNotifications";
ENDDATE_COLUMN = "endDate";
EXPIRATIONDATE_COLUMN = "expirationDate";
EXPIRATIONDURATION_COLUMN = "expirationDuration";
IDENTITYCONTEXT_COLUMN = "identityContext";
FROMUSER_COLUMN = "fromUser";
FROMUSERDSIPLAYNAME_COLUMN = "fromUserDisplayName";
HASSUBTASK_COLUMN = "hasSubtask";
INSHORTHISTORY_COLUMN = "inShortHistory";
ISGROUP_COLUMN = "isGroup";
LANGUAGE_COLUMN = "language";
MAILSTATUS_COLUMN = "mailStatus";
MOREINFOROLE_COLUMN = "moreInfoRole";
NUMBEROFTIMESMODIFIED_COLUMN =
ORIGINALASSIGNEEUSER_COLUMN = "originalAssigneeUser";
REQUESTINFOUSER_COLUMN = "requestInfoUser";
STATE_COLUMN = "State";
SUBSTATE_COLUMN = "SubState";
SYSTEMSTRING1_COLUMN = "systemString1";
SYSTEMSTRING2_COLUMN = "systemString2";
SYSTEMSTRING3_COLUMN = "SystemString3";
TASKGROUPID_COLUMN = "taskGroupId";
TASKID_COLUMN = "taskId";
VERSION_COLUMN = "version";
TASKNUMBER_COLUMN = "taskNumber";
UPDATEDBY_COLUMN = "updatedBy";
VERSIONREASON_COLUMN = "versionReason";
WORKFLOWPATTERN_COLUMN = "workflowPattern";
CALLBACKCONTEXT_COLUMN = "callbackContext";
CALLBACKID_COLUMN = "callbackId";
CALLBACKTYPE_COLUMN = "callbackType";
CREATOR_COLUMN = "creator";
OWNERUSER_COLUMN = "ownerUser";
OWNERGROUP_COLUMN = "ownerGroup";
OWNERROLE_COLUMN = "ownerRole";
PRIORITY_COLUMN = "priority";
DOMAINID_COLUMN = "domainId";
INSTANCEID_COLUMN = "instanceId";
PROCESSID_COLUMN = "processId";
PROCESSNAME_COLUMN = "processName";
PROCESSTYPE_COLUMN = "processType";
PROCESSVERSION_COLUMN = "processVersion";
TITLE_COLUMN = "title";
TITLERESOURCEKEY_COLUMN = "titleResourceKey";
IDENTIFICATIONKEY_COLUMN = "identificationKey";
USERCOMMENT_COLUMN = "userComment";
WORKFLOWDESCRIPTORURI_COLUMN =
TASKDEFINITIONID_COLUMN = "taskDefinitionId";
TASKDEFINITIONNAME_COLUMN = "taskDefinitionName";
36-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
36-23
TEXTATTRIBUTE1_COLUMN = "textAttribute1";
TEXTATTRIBUTE2_COLUMN = "textAttribute2";
TEXTATTRIBUTE3_COLUMN = "textAttribute3";
TEXTATTRIBUTE4_COLUMN = "textAttribute4";
TEXTATTRIBUTE5_COLUMN = "textAttribute5";
TEXTATTRIBUTE6_COLUMN = "textAttribute6";
TEXTATTRIBUTE7_COLUMN = "textAttribute7";
TEXTATTRIBUTE8_COLUMN = "textAttribute8";
TEXTATTRIBUTE9_COLUMN = "textAttribute9";
TEXTATTRIBUTE10_COLUMN = "textAttribute10";
FORMATTRIBUTE1_COLUMN = "formAttribute1";
FORMATTRIBUTE2_COLUMN = "formAttribute2";
FORMATTRIBUTE3_COLUMN = "formAttribute3";
FORMATTRIBUTE4_COLUMN = "formAttribute4";
FORMATTRIBUTE5_COLUMN = "formAttribute5";
URLATTRIBUTE1_COLUMN ="urlAttribute1";
URLATTRIBUTE2_COLUMN ="urlAttribute2";
URLATTRIBUTE3_COLUMN ="urlAttribute3";
URLATTRIBUTE4_COLUMN ="urlAttribute4";
URLATTRIBUTE5_COLUMN ="urlAttribute5";
DATEATTRIBUTE1_COLUMN ="dateAttribute1";
DATEATTRIBUTE2_COLUMN ="dateAttribute2";
DATEATTRIBUTE3_COLUMN ="dateAttribute3";
DATEATTRIBUTE4_COLUMN ="dateAttribute4";
DATEATTRIBUTE5_COLUMN ="dateAttribute5";
NUMBERATTRIBUTE1_COLUMN ="numberAttribute1";
NUMBERATTRIBUTE2_COLUMN ="numberAttribute2";
NUMBERATTRIBUTE3_COLUMN ="numberAttribute3";
NUMBERATTRIBUTE4_COLUMN ="numberAttribute4";
NUMBERATTRIBUTE5_COLUMN ="numberAttribute5";
PROTECTEDTEXTATTRIBUTE1_COLUMN =
PROTECTEDTEXTATTRIBUTE2_COLUMN
PROTECTEDTEXTATTRIBUTE3_COLUMN
PROTECTEDTEXTATTRIBUTE4_COLUMN
PROTECTEDTEXTATTRIBUTE5_COLUMN
PROTECTEDTEXTATTRIBUTE6_COLUMN
PROTECTEDTEXTATTRIBUTE7_COLUMN
PROTECTEDTEXTATTRIBUTE8_COLUMN
PROTECTEDTEXTATTRIBUTE9_COLUMN
PROTECTEDTEXTATTRIBUTE10_COLUMN =
PROTECTEDFORMATTRIBUTE1_COLUMN
PROTECTEDFORMATTRIBUTE2_COLUMN
PROTECTEDFORMATTRIBUTE3_COLUMN
PROTECTEDFORMATTRIBUTE4_COLUMN
PROTECTEDFORMATTRIBUTE5_COLUMN
36-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
for AS11
TEXTATTRIBUTE11_COLUMN = "textAttribute11";
TEXTATTRIBUTE12_COLUMN = "textAttribute12";
TEXTATTRIBUTE13_COLUMN = "textAttribute13";
TEXTATTRIBUTE14_COLUMN = "textAttribute14";
TEXTATTRIBUTE15_COLUMN = "textAttribute15";
TEXTATTRIBUTE16_COLUMN = "textAttribute16";
TEXTATTRIBUTE17_COLUMN = "textAttribute17";
TEXTATTRIBUTE18_COLUMN = "textAttribute18";
TEXTATTRIBUTE19_COLUMN = "textAttribute19";
TEXTATTRIBUTE20_COLUMN = "textAttribute20";
FORMATTRIBUTE6_COLUMN = "formAttribute6";
FORMATTRIBUTE7_COLUMN = "formAttribute7";
FORMATTRIBUTE8_COLUMN = "formAttribute8";
FORMATTRIBUTE9_COLUMN = "formAttribute9";
FORMATTRIBUTE10_COLUMN = "formAttribute10";
URLATTRIBUTE6_COLUMN ="urlAttribute6";
URLATTRIBUTE7_COLUMN ="urlAttribute7";
URLATTRIBUTE8_COLUMN ="urlAttribute8";
URLATTRIBUTE9_COLUMN ="urlAttribute9";
URLATTRIBUTE10_COLUMN ="urlAttribute10";
DATEATTRIBUTE6_COLUMN ="dateAttribute6";
DATEATTRIBUTE7_COLUMN ="dateAttribute7";
DATEATTRIBUTE8_COLUMN ="dateAttribute8";
DATEATTRIBUTE9_COLUMN ="dateAttribute9";
DATEATTRIBUTE10_COLUMN ="dateAttribute10";
NUMBERATTRIBUTE6_COLUMN ="numberAttribute6";
36-25
36-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
public
public
public
public
public
public
public
public
public
static
static
static
static
static
static
static
static
static
final
final
final
final
final
final
final
final
final
String
String
String
String
String
String
String
String
String
//attachment columns
public static final String
public static final String
public static final String
public static final String
public static final String
WFCOMMENT_COMMENTDATE_COLUMN= "commentDate";
WFCOMMENT_ACTION_COLUMN= "action";
WFCOMMENT_WFCOMMENT_COLUMN= "wfcomment";
WFCOMMENT_DISPLAYNAMELANGUAGE_COLUMN=
WFCOMMENT_ACL_COLUMN= "acl";
MAXVERSION_COLUMN= "maxVersion";
WFATTRIBUTES_NAME_COLUMN= "name";
WFATTRIBUTES_STORAGETYPE_COLUMN= "storageType";
WFATTRIBUTES_ENCODING_COLUMN= "encoding";
WFATTRIBUTES_STRINGVALUE_COLUMN= "stringValue";
WFATTRIBUTES_NUMBERVALUE_COLUMN= "numberValue";
WFATTRIBUTES_DATEVALUE_COLUMN= "dateValue";
WFATTRIBUTES_BLOBVALUE_COLUMN= "blobValue";
WFATTRIBUTES_ELEMENTSEQ_COLUMN= "elementSeq";
WFATTACHMENT_ENCODING_COLUMN= "encoding";
WFATTACHMENT_URI_COLUMN= "uri";
WFATTACHMENT_CONTENT_COLUMN= "content";
WFATTACHMENT_NAME_COLUMN= "name";
WFATTACHMENT_ACL_COLUMN= "acl";
36-27
36-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part VI
Part VI
37
Getting Started with Binding Components
37
This chapter describes the supported service and reference binding component types
and technologies that you can integrate in a SOA composite application. Supported
binding components include web services, HTTP binding, JCA adapters, Oracle
Business Activity Monitoring (BAM), Oracle B2B, Oracle Healthcare, ADF-BC services,
EJB services, and direct binding services. Creation of tokens for use in the binding
URLs of external references is also described.
This chapter includes the following sections:
For more information, see Section 2.3, "Adding Service Binding Components" and
Section 2.4, "Adding Reference Binding Components."
Services
Provide the outside world with an entry point to the SOA composite application.
The WSDL file of the service advertises its capabilities to external applications.
These capabilities are used for contacting the SOA composite application
components. The binding connectivity of the service describes the protocols that
can communicate with the service (for example, SOAP/HTTP or a JCA adapter).
References
Enable messages to be sent from the SOA composite application to external
services in the outside world.
Figure 371 shows the OrderBookingComposite project in the Fusion Order Demo in
which a service (UpdateOrderStatus) in the Exposed Services swimlane provides the
entry point to the composite and a reference (BAM_OrderDO) in the External
References swimlane enables information to be sent to an Oracle Business Activity
Monitoring (BAM) Server in the outside world.
37-1
Binding components enable you to integrate the following types of technologies with
SOA composite applications:
Web services
HTTP binding
JCA adapters
Oracle BAM
Oracle B2B
Oracle Healthcare
ADF-BC services
EJB services
Exporting transactions from the local Java Transaction API (JTA) environment for
a web service request.
Importing transactions from a web service request into the local JTA environment.
This allows for distributed transaction processing between multiple nodes in the
web services environment.
Figure 372 shows the support for WS-AT at the bottom of the Create Web Service
dialog.
37-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 371 describes the WS-AT fields. For a description of the remaining fields in the
Create Web Service dialog, see Section 2.3.2, "How to Define the Interface (WSDL) for a
Web Service."
37-3
Table 371
Property
Description
Transaction
Participation
Select a value. If you added the web service to the Exposed Services swimlane,
this action enables external transaction managers to coordinate resources
hosted on Oracle WebLogic Server over WS-AT. If you added the web service
to the External References swimlane, this addition enables Oracle WebLogic
Server transactions to coordinate resources hosted in external environments
over WS-AT.
Never
No transaction context is imported (for services) or exported (for
references). This is the default value if you add the web service as a
service binding component in the Exposed Services swimlane.
Supports
If a transaction exists, a transaction context is imported (for services) or
exported (for references). This information is added to the
composite.xml file.
Mandatory
A transaction context is imported (for services) or exported (for
references). This information is added to the composite.xml file. For
exports, a web service exception message is thrown if there is no active
transaction. For imports, a fault is returned to the client if there is no
transaction context in the request.
WSDLDriven
This property only displays if you add the web service as a reference
binding component in the External References swimlane. This is the
default value.
Version
Displays the WS-AT supported version (1.0, 1,1, 1,2, or default). By default,
this list is only enabled if you select Supports or Mandatory from the
Transaction Participation list.
When complete, the composite.xml file displays your WS-AT selections, as shown
in Example 371.
Example 371
If you want to edit your changes, you can right-click the service and select Edit or
double-click the service in the SOA Composite Editor.
After deployment, you can modify the transaction participation and version values
through the System MBean Browser. For more information, see Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
37-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about WS-AT and WS-Coordination, see Oracle Fusion
Middleware Developer's Guide for Oracle Infrastructure Web Services and the WS-AT and
WS-Coordination specifications, which are available at the following URL:
http://www.oasis-open.org
This setting ensures that, if an error occurs (such as a database adapter invocation
failing due to an integrity constraint violation), a transaction rollback is successfully
completed.
For more information about setting the transaction property, see Section 4.1.1,
"How to Add a BPEL Process Service Component," Section C.1.1, "How to Define
Deployment Descriptor Properties in the Property Inspector," and Section 13.1.1,
"Oracle BPEL Process Manager Transaction Semantics."
37.1.1.1.2 WS-AT Transactions are Not Supported When Optimization is Enabled You can
configure a web service binding component as either a service or reference to support
WS-AT transactions from the Transaction Participation dropdown list of the Create
Web Service dialog. WS-AT transactions are supported in composite-to-web service
environments, or vice-versa, with the
oracle.webservices.local.optimization property set to false.
WS-AT transactions are not supported in composite-to-composite calls, even with the
oracle.webservices.local.optimization property set to false.
For more information about the oracle.webservices.local.optimization
property, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and
Oracle Business Process Management Suite.
37-5
Note:
Direction
Verb
Payload Type
Operation
Supported?
Inbound
GET
URL-encoded
One-way
Yes
Inbound
GET
URL-encoded
Request-response Yes
Inbound
GET
XML
One-way
Inbound
GET
XML
Request-response No
Inbound
POST
URL-encoded
One-way
Inbound
POST
URL-encoded
Request-response Yes
Inbound
POST
XML
One-way
Inbound
POST
XML
Request-response Yes
Outbound
GET
URL-encoded
One-way
Outbound
GET
URL-encoded
Request-response Yes
Outbound
GET
XML
One-way
Outbound
GET
XML
Request-response Yes
Outbound
POST
URL-encoded
One-way
Outbound
POST
URL-encoded
Request-response Yes
Outbound
POST
XML
One-way
Outbound
POST
XML
Request-response Yes
No
Yes
Yes
No
No
No
No
Table 373 shows the supported types in XSDs for the inbound and outbound
directions.
Table 373
Direction
Types in XSDs
Type Is Supported?
Inbound
Simple
Yes
Inbound
Complex
Inbound
Native
37-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
No
Types in XSDs
Type Is Supported?
Outbound
Simple
Yes
Outbound
Complex
Outbound
Native
No
The following HTTP headers are not supported in either the inbound or outbound
direction (that is, you cannot access HTTP headers in the composite and set them in
the composite):
User-agent
Content-type
Content-length
Server
Server-port
Referrer
Authorization
MIME-Version
Location
37-7
Figure 373 Create HTTP Binding Wizard - HTTP Binding Configuration Page
3.
For HTTP POST request methods, you can select a payload type of either
URL-encoded (ampersand-separated name-value pairs) or XML.
For HTTP GET request methods, the payload type is URL-encoded.
For HTTP GET or POST request methods for reference binding components, you
are also prompted to specify the endpoint URL. Support for HTTP authentication
and secure socket layer (SSL) is also provided.
Note:
4.
Click OK.
5.
Browse for an existing request message schema or define your own schema with
the links to the right of the URL field on the Messages page. Figure 374 provides
details.
37-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Click OK.
7.
If you select to define your own schema, you are prompted to specify the element
names, data types, minimum occurrence value, and maximum occurrence value in
the Create Schema dialog. Figure 375 provides details.
8.
Click OK.
At runtime, the concrete WSDL is generated with an HTTP binding and a SOAP
binding; this is because the SOAP endpoint is used to provide HTTP support.
37-9
2.
In the Configure SOA WS Policies dialog, click the Add icon in the Security
section.
3.
4.
Databases
File systems
FTP servers
Message systems such as Advanced Queueing (AQ) and Java Messaging Systems
(JMS)
IBM WebSphere MQ
TCP/IP sockets
Dragging a JCA adapter into a swimlane of the SOA Composite Editor invokes the
Adapter Configuration Wizard for specifying configuration properties.
37.1.3.1 AQ Adapter
The AQ adapter enables you to interact with a single consumer or multiconsumer
queue.
Oracle Streams AQ provides a flexible mechanism for bidirectional, asynchronous
communication between participating applications. Advanced queues are an Oracle
database feature, and are therefore scalable and reliable. Multiple queues can also
service a single application, partitioning messages in a variety of ways and providing
another level of scalability through load balancing.
For more information, see Oracle Fusion Middleware User's Guide for Technology
Adapters.
37-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
For more information, see Oracle Fusion Middleware User's Guide for Technology
Adapters.
For more information, see Oracle Fusion Middleware User's Guide for Technology
Adapters.
37.1.3.6 MQ Adapter
The MQ adapter provides message exchange capabilities between BPEL processes and
Oracle Mediator and the WebSphere MQ queuing systems.
The Messaging and Queuing Series (MQ Series) is a set of products and standards
developed by IBM. The MQ Series provides a queuing infrastructure that provides
guaranteed message delivery, security, and priority-based messaging.
For more information, see Oracle Fusion Middleware User's Guide for Technology
Adapters.
37-11
37-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
As you follow the steps in the Healthcare Configuration Wizard, you are prompted to
select a document definition created in Oracle SOA Suite for health care integration.
You can launch Oracle SOA Suite for health care integration from the wizard to create
a document definition if the right one does not already exist. This is the payload, or
message, that you are receiving from or sending to external systems.
For more information, see Oracle Fusion Middleware Healthcare Integration User's Guide
for Oracle SOA Suite.
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
37-13
Enterprise JavaBeans are server-side domain objects that fit into a standard
component-based architecture for building enterprise applications with Java. These
objects become distributed, transactional, and secure components.
Java interfaces eliminate the need for WSDL file definitions. This type of integration
provides support with the following objects:
Dragging an EJB service into a swimlane of the SOA Composite Editor invokes the
Create EJB Service dialog for specifying configuration properties.
For more information, see Chapter 38, "Integrating Enterprise JavaBeans with SOA
Composite Applications."
If you want to provide the outside world with an entry point to the SOA
composite application, drag the binding component to the Exposed Services
swimlane.
37-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If you want to enable messages to be sent from the SOA composite application
to external services in the outside world, drag the binding component to the
External References swimlane.
Figure 376 shows a web service being dragged into the composite. This action
invokes a dialog for specifying various configuration properties.
Figure 376 Integration of a Web Service Binding Component into a Composite
For more information about adding binding components, see Section 2.3, "Adding
Service Binding Components" and Section 2.4, "Adding Reference Binding
Components."
37.2.2 How to Use ADF Binding to Invoke a Composite Application from a JSP/Java
Class
If a SOA composite application uses a web service binding to define an endpoint
reference, the composite cannot be invoked from a JSP/Java class. Web services
binding is defined with the binding.ws port="" location="" tag in the
composite.xml file. Example 372 provides details.
Example 372
WS Binding Definition
Instead, use ADF binding. After deployment of the composite with ADF binding,
invocation from a JSP/Java class is successful. Example 373 provides details.
Example 373
37.3 Creating Tokens for Use in the Binding URLs of External References
You can create tokens in Oracle JDeveloper for the HTTP protocol, host, and port
values in the binding URLs of external references. The values that you assign to the
37-15
tokens are then substituted in place of the hardcoded HTTP host and port values in
the location attribute of the binding.ws element of the composite.xml file.
For example, Example 374 shows the location attribute with hardcoded values for
protocol (http), host (host.us.example), and port (80).
Example 374
<binding.ws
port="http://www.globalcompany.example.com/ns/CreditAuthorizationService#wsdl.
endpoint(CreditAuthorizationService/CreditAuthorizationPort)"
location="http://host.us.example:80/apps/FusionOrderDemoShared/services/
creditAuthorization/CreditAuthorizationService.wsdl">
Example 375 shows the location attribute after the creation of tokens.
Example 375
<binding.ws
port="http://www.globalcompany.example.com/ns/CreditAuthorizationService#wsdl.
endpoint(CreditAuthorizationService/CreditAuthorizationPort)"
location="${protocol}://${host1}:${port1}/apps/FusionOrderDemoShared/services/
creditAuthorization/CreditAuthorizationService.wsdl">
Notes:
37.3.1 How to Create Tokens for Use in the Binding URLs of External References
Follow the steps in this section to create tokens for use in the binding URLs of external
references.
To create tokens for use in the binding URLs of external references:
1. In Oracle JDeveloper, access the SOA composite application in which to create
tokens.
2.
Above the SOA Composite Editor, click the Binding URL Tokenizer icon.
Figure 377 provides details.
37-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Binding URLs of each external reference that has a binding.ws element with a
location attribute in the composite.xml file that starts with the following
entries are automatically displayed:
http
https
${ (for a URL that uses tokens in place of the hardcoded HTTP protocol, host,
or port values)
callbackServerURL
The Service2 reference in Figure 378 also includes an override of the callback
location using a reference property such as callbackServerURL:
<property name="callbackServerURL" type="xs:string" many="false">
${protocol}://${myhost1}:${myport1}/soa-infra/services/default/service/
bpelprocess1_client_ep</property>
Double-click a row or select the row and click the Edit icon to create tokens for the
HTTP protocol, host, and port values in the binding URLs of external references.
The Binding URL Tokenization dialog appears, as shown in Figure 379.
37-17
4.
Table 374
Field
Description
Token File
Click the Browse button to access the Resource Browser dialog for
selecting the token file that includes the token names and values. The file
can be on the local file system. The names and values specified in this file
replace the hardcoded names and values for protocol, host, and port in
the binding.ws element. This field is automatically populated with
your file selection on subsequent invocations of this dialog. If you specify
a token file from the file system, it must be an XML file that follows this
format:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM
"http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>
URL Resolver file used by the Metadata
manager to resolve $<variable> in URLs
</comment>
<entry key="protocol">oramds</entry>
<entry key="host">MyHost</entry>
<entry key="port">80</entry>
</properties>
Skip this field entirely if you want to manually enter new token names
and values in the Token and Current Values fields, respectively.
Tokens that are not saved to a file are only placed in the location
attribute of the binding.ws element in the composite. It is expected that
you supply a token file at runtime that has tokens matching those
manually entered at design time.
Reference
37-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Protocol
Click the Browse icon to select the token name to use from the Token
Picker dialog. The Token Picker dialog is populated with the token names
that appear in the token file you imported in the Token File field. The
token name you select (for example, port1) and its default value (for
example, 80) are added to the Token and Current Value fields,
respectively. If the token file is writable (meaning an unprotected file in
the file system), you can change the current value of the token name. See
Step 5 for details about accessing the Token Picker dialog. If the file is
read-only, you are warned with a message and allowed to cancel the
operation and continue.
Manually enter the token name and value to use. You can manually enter
information in these fields regardless of whether you imported a file in
the Token File field. If you imported a file that is writable in the Token
File field and manually enter a token name, it is added to the file if it does
not already exist. The current value for the new token name defaults to
the value in the URL that is being tokenized.
Host
Displays the field in which to specify the host token name. See the description
of the Protocol field for details about how to specify information.
Port
Displays the field in which to specify the port token name. See the description
of the Protocol field for details about how to specify information.
Apply these
tokens to
other
References
which have
the same
Current
Values
Deselect this checkbox if you do not want other external references with the
same protocol, host, and port values to be replaced with the same tokens.
5.
If this checkbox is selected and you tokenize just one or two of the URL
objects, then the references for only those objects are modified. For example, if
you only tokenize the host (with a current value of host1.us.oracle), all
references that have that same host value are updated.
If you selected the Browse button in the Protocol, Host, or Port fields, the Token
Picker is displayed, as shown in Figure 3710. This dialog lists all the tokens that
you have defined in the file imported in the Token File field of the Binding URL
Tokenization dialog.
37-19
6.
Select the token name to use through one of the following options:
7.
Click OK.
You are returned to the Binding URL Tokenization dialog with the selected token
name and value displayed in the Token and Current Value fields, respectively.
37-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
38
Integrating Enterprise JavaBeans with SOA
Composite Applications
38
This chapter describes how to integrate Enterprise JavaBeans with SOA composite
applications through use of service data object (SDO) parameters or Java interfaces. It
describes how to design an SDO-based Enterprise JavaBeans application, create an
Enterprise JavaBeans service in Oracle JDeveloper, design an Enterprise JavaBeans
client to invoke Oracle SOA Suite, specify Enterprise JavaBeans roles, and configure
JNDI access.
This chapter includes the following sections:
Through use of SDO-based EJBs (uses a WSDL file to define the interface)
Through use of Java interfaces (does not use a WSDL file to define the interface)
You can also use the spring service component to integrate Java interfaces with SOA
composite applications. For information about using the spring service component, see
Chapter 52, "Integrating the Spring Framework in SOA Composite Applications."
Invoke with
SDO
Parameters
Exposed
Service
Service
SOA
Composite
Application
External
References
Reference
Invoke with
SDO
Parameters
EJB
Application
You use the Create EJB Service dialog in Oracle JDeveloper to define this integration,
as described in Section 38.3.1, "How to Integrate SDO-based Enterprise JavaBeans with
SOA Composite Applications." This option requires the use of a WSDL file. Once
complete, the WSDL interaction is defined in the composite.xml file through the
interface.wsdl entry, as shown in Example 381.
Example 381
<service name="PortfolioService">
<interface.wsdl
interface="http://bigbank.com/#wsdl.interface(PortfolioService)" />
<binding.ejb javaInterface="java.class.ejb.com" serviceId="PortfolioService"
jarLocation="soaejb.jar"/>
38-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Java interfaces differ from SDO interfaces, which are defined in a WSDL file because of
the XML-centric nature of service components such as Oracle BPEL Process Manager,
Oracle Mediator, and others. No SDO parameters are required when using Java
interfaces.
You use the Create EJB Service dialog in Oracle JDeveloper to define this integration,
as described in Section 38.3.2, "How to Integrate Java Interface-based Enterprise
JavaBeans with SOA Composite Applications." This option does not require the use of
a WSDL file. Once complete, the interaction is defined in the composite.xml file
through the interface.java entry, as shown in Example 382.
Example 382
<service name="PortfolioService">
<interface.java interface="com.bigbank.services.MyService" />
binding.ejb uri="MyJNDI" ejb-version="EJB3"/>
The Java class must be in the project's loader to be available to the user interface. The
class must be in SCA-INF to be deployed (not all JAR files in the project class path are
deployed). This typically means that the class must be in the SCA-INF/classes
directory or in a JAR in the SCA-INF/lib directory. However, it can also be an
interface from the system class path.
For information about JAXB, see Oracle Fusion Middleware Solution Guide for Oracle
TopLink and Chapter 52, "Integrating the Spring Framework in SOA Composite
Applications."
Oracle Fusion Middleware Programming Enterprise JavaBeans, Version 3.0 for Oracle
WebLogic Server
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework
Oracle JDeveloper online help table of contents for the following topics:
Enterprise JavaBeans
Access the help by selecting Help > Table of Contents in Oracle JDeveloper.
Oracle JDeveloper enables you to create an SDO service interface for JPA entities.
While this feature is more tailored for use with the Oracle Application
Development Framework (ADF) service binding in a SOA composite application,
you can also use this feature with the Enterprise JavaBeans service binding in SOA
composite applications. The SDO service interface feature generates the necessary
WSDL and XSD files. If you use this feature, you must perform the following tasks
to work with the Enterprise JavaBeans service binding:
Browse for and select this WSDL file in the SOA Resource Browser dialog,
which is accessible from the WSDL URL field of the Create EJB Service dialog
(described in Section 38.3, "Creating an Enterprise JavaBeans Service in Oracle
JDeveloper").
Add the BC4J Service Runtime library to the SOA project. To add this library,
double-click the project and select Libraries and Classpath to add the library
in the Project Properties dialog. You are now ready to design the business
logic.
For more information, see the SDO for Enterprise JavaBeans/JPA topic in the
Oracle JDeveloper online help (this includes instructions on how create to an SDO
service interface).
38.2.2 How to Create a Session Bean and Import the SDO Objects
To create a session bean and import the SDO objects:
1. Create a simple session bean with the Create Session Bean wizard. For details on
using this wizard, see the Creating a Session Bean topic in the Oracle JDeveloper
online help.
2.
Import the SDO objects into your project through the Project Properties dialog.
3.
Add logic and necessary import and library files. In particular, you must import
the Commonj.sdo.jar file. JAR files can be added in the Libraries and Classpath
dialog. This dialog is accessible by double-clicking the project and selecting
Libraries and Classpath in the Project Properties dialog. You are now ready to
design the logic.
4.
38-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
38.2.4 How to Define the SDO Types with an Enterprise JavaBeans Bean
An Enterprise JavaBeans bean must define the SDO types. Example 383 provides
details.
Caution: Where to call define can be nontrivial. You must force the
types to be defined before remote method invocation (RMI)
marshalling must occur and in the right helper context. The
EclipseLink SDO implementation indexes the helper instance with the
application name or class loader.
The weblogic-ejb-jar.xml file is the descriptor file that must be added in the
deployment jar. The weblogic-ejb-jar.xml file is automatically created when you
create a session bean. This file must be modified by adding the following entries
shown in Example 384.
Example 384
weblogic-ejb-jar.xml File
Figure 382 provides a code example of a session bean with SDO logic defined:
Annotations
Name
Description
38-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
@SDODatabinding
@Remote
@PortableWebService(targetNamespace = "http://www.example.org/customer-example",
serviceName = "CustomerSessionEJBService")
@SDODatabinding(schemaLocation = "customer.xsd")
public interface CustomerSessionEJB {
@WebMethod(operationName="createCustomer")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@WebResult(targetNamespace = "http://www.example.org/customer-example",
partName = "parameters", name = "customer")
CustomerType createCustomer();
@WebMethod(operationName="addPhoneNumber")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@WebResult(targetNamespace = "http://www.example.org/customer-example",
partName = "parameters", name = "customer")
CustomerType addPhoneNumber(@WebParam(targetNamespace =
"http://www.example.org/customer-example", partName = "parameters", name =
"phone-number")PhoneNumber phNumber);
}
Select Deploy and deploy the EAR file to a previously created application server
connection.
To Invoke...
External References
Exposed Services
2.
3.
See the step in Table 383 based on the swimlane in which you dragged the EJB
Service.
Table 383
Swimlane Location
Then Go To...
External References
3a
Exposed Services
3b
38-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
a.
View the Create EJB Service dialog that displays in the External References
swimlane, as shown in Figure 383.
b.
View the Create EJB Service dialog that displays in the Exposed Services
swimlane, as shown in Figure 384.
4.
Enter values appropriate to your environment. The fields that display differ based
on the swimlane in which you dragged the EJB Service icon. Table 384 provides
details.
Table 384
Field
Value
Name
Type
Version
Interface
Select WSDL.
JNDI Name
Note: This field only displays if you dragged the EJB Service
icon into the External References swimlane.
Enter the JNDI name of your Enterprise JavaBeans.
Jar File
Click the Search icon to select the EJB JAR file created in
Section 38.2, "Designing an SDO-Based Enterprise JavaBeans
Application." The SOA Resource Browser dialog searches for
and displays JAR files starting in the SCA-INF/lib subdirectory
of the current project directory. The JAR file includes the
interface class and any supporting classes.
Note: If you select a JAR file outside of the current project,
Oracle JDeveloper creates a copy of the JAR file in the
SCA-INF/lib directory of the current project. When prompted,
click OK to accept.
Java Interface
Click the Browse icon to invoke the Class Browser dialog for
selecting the fully qualified Java class name of the previously
created Enterprise JavaBeans interface. This class must exist in
the selected JAR file. If a JAR file is not specified, it is assumed
that the class is in the /SCA-INF/classes subdirectory of the
current project directory.
Note: If you use the Jar File field, you do not need to add a new
JAR file to the project by selecting Project Properties > Libraries
and Classpath > Add JAR/Directory from the Application main
menu.
WSDL URL
Note: Ensure that you have created the annotations for the
Enterprise JavaBeans interface before generating the WSDL file,
as described in Section 38.2.5, "How to Use Web Service
Annotations."
Click the second icon to the right to generate a WSDL file that
represents the Enterprise JavaBeans interface.
If you created SDO objects through Oracle JDeveloper, as
described in Section 38.2.1, "How to Create SDO Objects Using
the SDO Compiler," ensure that you select the WSDL file that
was automatically generated with this option.
Port Type
38-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
Click OK.
2.
3.
The Create EJB Service dialog displays the fields shown in Figure 385.
4.
Enter the details shown in Table 385. The fields are the same regardless of the
swimlane in which you dragged the EJB Service icon.
38-11
Table 385
Field
Value
Name
Type
Version
Interface
Select Java.
JNDI Name
Jar File
Click the Search icon to select the EJB JAR file created in
Section 38.2, "Designing an SDO-Based Enterprise JavaBeans
Application." The SOA Resource Browser dialog searches for
and displays JAR files starting in the SCA-INF/lib subdirectory
of the current project directory. The JAR file includes the
interface class and any supporting classes.
Note: If you select a JAR file outside of the current project,
Oracle JDeveloper creates a copy of the JAR file in the
SCA-INF/lib directory of the current project. When prompted,
click OK to accept.
Java Interface
5.
Click OK.
38-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 386
38-13
38.6.1 How to Configure Enterprise JavaBeans Binding Support in the Credential Store
Framework
All Enterprise JavaBeans bindings now support using the Credential Store Framework
(CSF) to store JNDI user access credentials, and not just service data object (SDO)
Enterprise JavaBeans bindings.
You can edit the following Enterprise JavaBeans binding JNDI properties in Oracle
Enterprise Manager Fusion Middleware Control:
java.naming.factory.initial
java.naming.provider.url
java.naming.dns.url
java.naming.factory.url.pkgs
java.naming.factory.url.pkgs
java.naming.security.authentication
java.naming.security.protocol
java.naming.security.principal
java.naming.security.crendentials
oracle.jps.credstore.map
oracle.jps.credstore.key
38-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Right-click the SOA composite application that includes the Enterprise JavaBeans
binding component.
2.
3.
4.
5.
Domain > Security > Credentials (if the application is deployed on Oracle
WebLogic Server).
or
b.
2.
3.
4.
After completing these steps, you must grant SOA Infrastructure runtime access to the
CSF map store.
1.
2.
3.
4.
Select the entry and edit it to add a credential store access permission.
5.
38-15
38-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
39
Using the Direct Binding Invocation API
39
This chapter describes the Direct Binding Invocation API and how to invoke a SOA
composite application. It describes how to create an inbound direct binding service,
how to create an outbound direct binding reference, and how to set an identity for
Java 2 Platform, Standard Edition (J2SE) clients invoking direct binding. Samples of
using the Direct Binding Invocation API are also provided.
This chapter includes the following sections:
Direct binding must be associated with the interface.wsdl, providing the interface
clause and, optionally, the callbackInterface clause. The associated WSDL must
be imported into the composite.
39-1
The service binding component also publishes a modified version of the WSDL that
advertises the direct binding.
<service name="direct2">
<interface.wsdl
interface="http://xmlns.oracle.com/asyncNonConvDocLit#wsdl.interface(asyncNonConvD
ocLit)"
callbackInterface="http://xmlns.oracle.com/asyncNonConvDocLit#wsdl.interface(async
NonConvDocLitCallback)" xmlns:ns="http://xmlns.oracle.com/sca/1.0"/>
<binding.direct/>
</service>
Properties:
A set of properties that defines the DirectConnection for the end service.
AddressingVersion (optional):
The default addressing version used is 2005/08.
useSSLForCallback:
Use secure socket layer (SSL) for the callback JNDI connection. If this flag is set to
true, then the WS-Addressing replyTo header instructs the service to call back
at an SSL JNDI port.
Sample Configuration
39-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<property
name="java.naming.factory.initial">weblogic.jndi.WLInitialContextFactory</property
>
<property name="java.naming.provider.url">t3://@host:@port</property>
</binding.direct>
</reference>
39-3
oracle.soa.management.facade.Locator
The oracle.soa.management.facade.Locator interface exposes a method,
createConnection, which returns a direct connection. The Locator exposes
the method shown in Example 393 for returning the DirectConnection.
Example 393
oracle.soa.management.facade.Locator
import java.util.Map;
public interface DirectConnectionFactory {
DirectConnection createDirectConnection(CompositeDN compositeDN,
String serviceName) throws Exception;
LocatorFactory Implementation
oracle.soa.api.invocation.DirectConnection
The DirectConnection interface invokes a composite service using direct
binding. For more information, see Oracle Fusion Middleware Infrastructure
Management Java API Reference for Oracle SOA Suite.
oracle.soa.api.message.Message
The Message interface encapsulates the data exchanged. For more information,
see Oracle Fusion Middleware Infrastructure Management Java API Reference for Oracle
SOA Suite.
http://www.w3.org/2005/08/addressing
http://schemas.xmlsoap.org/ws/2004/08/addressing
http://schemas.xmlsoap.org/ws/2003/03/addressing
WS-Addressing Header
<wsa:MessageID>D6202742-D9D9-4023-8167-EF0AB81042EC</wsa:MessageID>
<wsa:ReplyTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>sb://testserver:9001/callback</wsa:Address>
<wsa:ReferenceParameters>
<soa:callback xmlns:soa="http://xmlns.oracle.com/soa/direct"
connection-factory="mytest.MyDirectionConnectionFactory">
<soa:property name="oracle.soa.api.invocation.direct.bean"
value="myTest.MyDirectConnectionBean"/>
<soa:property name="java.naming.provider.url" value="t3://test:8001"/>
<soa:property name="java.naming.factory.initial"
value="weblogic.jndi.WLInitialContextFactory"/>
</soa:callback>
</wsa:ReferenceParameters>
</wsa:ReplyTo>
39-5
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
Note: You must qualify the callback and its property elements
properly with the SOA direct namespace.
The direct binding component is responsible for parsing the addressing headers set on
the message instance. In this example, there are two headers: wsa:MessageID and
wsa:ReplyTo. The service binding component makes the following properties
available for the internal SOA components:
tracking.conversationId = D6202742-D9D9-4023-8167-EF0AB81042E
replyToAddress = sb://testserver:9001/callback
In the SOA direct address, the CompositeDN has the following form:
domainName/compositeName[!compositeVersion[*label]]
Begin the Java transaction from the client and, after performing all the database
operations, perform a commit. You should commit the database operations after a
successful commit from the client side.
Begin the Java transaction from the client side. If a fault is thrown back during any
operation in the SOA composite, then roll back the transaction from the client side.
This rolls back all the database operations.
39-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
Oracle JDeveloper supports creating a direct service binding and a direct reference
binding that invokes either an Oracle Service Bus or another SOA composite.
For a client to invoke composite services over direct binding,
its class path must include both soa-infra-mgmt.jar and
oracle-soa-client-api.jar.
Note:
For more information about the Direct Binding Invocation API, see Section 39.2,
"Introduction to the Direct Binding Invocation API."
3.
From the Service Adapters list, drag the Direct Binding component into the
Exposed Services swimlane. The Create Direct Binding dialog appears.
4.
Table 391
Field
Value
Name
Enter a name.
Type
Reference Target
WSDL URL
39-7
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
Table 391 (Cont.) Direct Binding Service Dialog Fields and Values
Field
Value
Port Type
The port type of the WSDL file. You must select a port from the
list.
Address
Provider URL
When complete, the Create Direct Binding dialog appears as shown in Figure 394.
Figure 394 Create Direct Binding Dialog
5.
Click OK.
The direct binding service displays in the SOA Composite Editor shown in
Figure 395. The single arrow in a circle indicates that this is a synchronous,
one-way, direct binding component.
39-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
Note:
3.
From the Service Adapters list, drag the Direct Binding component into the
External References swimlane. The Create Direct Binding dialog appears.
4.
Table 392
Field
Value
Name
Enter a name.
Type
Reference Target
Select the reference target on which you want the direct binding
service to operate:
39-9
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
Table 392 (Cont.) Direct Binding Service Dialog Fields and Values
Field
Value
WSDL URL
Port Type
The port type of the WSDL file. You must select a port from the
list.
Address
Provider URL
When complete, the Create Direct Binding dialog appears as shown in Figure 396.
For more information about using the Oracle SOA Suite services with Oracle
Service Bus, see Chapter "Oracle SOA Suite Transport (SOA-DIRECT)" of the
Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.
Figure 396 Create Direct Binding Dialog
5.
Click OK.
39-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Invoking a SOA Composite Application in Oracle JDeveloper with the Invocation API
The direct binding reference displays in the designer shown in Figure 397. The
single arrow in a circle indicates that this is a synchronous, one-way direct binding
reference component.
Figure 397 Direct Binding Reference
39.3.3 How to Set an Identity for J2SE Clients Invoking Direct Binding
J2SE clients can set an identity while invoking direct binding, as shown in
Example 397.
Example 397
39.3.4 What You May Need to Know About Invoking SOA Composites on Hosts with
the Same Server and Domain Names
If one SOA composite application invokes another SOA composite application on
another host through direct binding, and both composites are on hosts with the same
server name and domain name, the invocation fails.
This is because the Oracle WebLogic Server transaction subsystem requires the
domain names and server names to be different for transaction management to work
properly. The transaction subsystem uses these names to track the location of a server
related to a transaction. If the two servers in the invocation have the same name, the
transaction subsystem can mistakenly confuse the two servers.
Ensure that you use hosts with separate server names and domain names.
Use of Messages
39-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
39-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part VII
Part VII
Chapter 41, "Using Business Events and the Event Delivery Network"
40
40
For information on invoking the XSLT Mapper from Oracle BPEL Process Manager,
see Section 40.2.1, "How to Create an XSL Map File in Oracle BPEL Process Manager."
For information on invoking the XSLT Mapper from Oracle Mediator, see
Section 40.2.3, "How to Create an XSL Map File in Oracle Mediator."
The Source and the Target schemas are represented as trees and the nodes in the trees
are represented using a variety of icons. The displayed icon reflects the schema or
property of the node. For example:
An XSD attribute is denoted with an icon that is different from an XSD element.
An optional element is represented with an icon that is different from a mandatory
element.
A repeating element is represented with an icon that is different from a
nonrepeating element, and so on.
The various properties of the element and attribute are displayed in the Property
Inspector in the lower right of the XSLT Mapper when the element or attribute is
selected (for example, type, cardinality, and so on). The Component Palette in the
upper right corner of Figure 401 is the container for all functions provided by the
XSLT Mapper. The XSLT Mapper is the actual drawing area for dropping functions
and connecting them to source and target nodes.
When an XSLT map is first created, the target tree shows the element and attribute
structure of the target XSD. An XSLT map is created by inserting XSLT constructs and
XPath expressions into the target tree at appropriate positions. When executed, the
XSLT map generates the appropriate elements and attributes in the target XSD.
Editing can be done in design view or source view. When a map is first created, you
are in design view. Design view provides a graphical display and enables editing of
the map. To see the text representation of the XSLT being created, switch to source
view. To switch views, click the Source or Design tab at the bottom of the XSLT
Mapper.
While in design view, the following pages from the Component Palette can be used:
40-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
User Defined: User-defined functions and templates. This page is visible only
when the user has templates in their XSL or user-defined external functions
defined through the preferences pages.
All Pages: Provides a view of all functions in one page.
My Components: Contains user favorites and recently-used functions. To add a
function to your favorites, right-click the function in the Component Palette and
select Add to Favorites.
The following functions are only available with Oracle
Mediator, and not Oracle BPEL Process Manager, in the XSLT
Mapper.
Note:
getComponentInstanceID()
getComponentName()
getCompositeInstanceID()
getCompositeName()
getECID()
getProperty(propertyName as string)
setCompositeInstanceTitle(titleElement)
For Oracle BPEL Process Manager, you can use these functions in an
assign activity.
While in source view, the XML and the http://www.w3.org/1999/XSL/Transform pages
can be used.
The XSLT Mapper provides three separate context sensitive menus:
Right-click each of the three separate panels to see what the context menus look like.
By default, design view shows all defined prefixes for all nodes in the source and
target trees. You can elect not to display prefixes by selecting Hide Prefixes from the
context menu in the center panel of design view. After prefixes are hidden, select
Show Prefixes to display them again.
At this point, no target fields are mapped. Switching to source view displays an empty
XSLT map. XSLT statements are built graphically in design view, and XSLT text is then
generated. For example, design view mapping is shown in Figure 403.
Figure 403 Design View Mapping
Design view results in the generation of the following XSLT statements in source view:
The OrderDate attribute from the source tree is linked with a line to the
InvoiceDate attribute in the target tree in Figure 403. This results in a value-of
statement in the XSLT, as shown in Example 401.
40-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 401
value-of Statement
<xsl:attribute name="InvoiceDate">
<xsl:value-of select="/ns0:PurchaseOrder/@OrderDate"/>
</xsl:attribute>
The First and Last name fields from the source tree in Figure 403 are
concatenated using an XPath concat function. The result is linked to the Name
field in the target tree. This results in the XSLT statement shown in Example 402:
Example 402
concat Function
<Name>
<xsl:value-of select="concat(/ns0:PurchaseOrder/ShipTo/Name/First,
/ns0:PurchaseOrder/ShipTo/Name/Last)"/>
</Name>
Note the inserted XSLT for-each construct in the target tree in Figure 403. For
each HighPriorityItems/Item element in the source tree, a ShippedItems/Item
element is created in the target tree and ProductName and Quantity are copied for
each. The XSLT syntax shown in Example 403 is generated:
Example 403
for-each Construct
<xsl:for-each
select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
<Item>
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
<Quantity>
<xsl:value-of select="Quantity"/>
</Quantity>
</Item>
</xsl:for-each>
The line linking Item in the source tree to the for-each construct in the target tree
in Figure 403 determines the XPath expression used in the for-each select
attribute. In general, XSLT constructs have a select or test attribute that is
populated by an XPath statement typically referencing a source tree element.
The XPath expressions in the value-of statements beneath the for-each construct
are relative to the XPath referenced in the for-each construct. In general, the XSLT
Mapper creates relative paths within for-each statements.
If you must create an absolute path within a for-each construct, you must do this
within source view. When switching back to design view, it is remembered that the
path is absolute and the XSLT Mapper does not modify it.
Note:
<xsl:if test="ProductName">
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
</xsl:if>
The entire XSLT map generated for this example is shown in Example 404:
Example 404
<xsl:template match="/">
<tns1:Invoice>
<xsl:attribute name="InvoiceDate">
<xsl:value-of select="/ns0:PurchaseOrder/@OrderDate"/>
</xsl:attribute>
<ShippedTo>
<Name>
<xsl:value-of select="concat
(/ns0:PurchaseOrder/ShipTo/Name/First,/ns0:PurchaseOrder/ShipTo/Name/Last)"/>
</Name>
</ShippedTo>
<ShippedItems>
<xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
<Item>
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
<Quantity>
<xsl:value-of select="Quantity"/>
</Quantity>
</Item>
</xsl:for-each>
</ShippedItems>
</tns1:Invoice>
</xsl:template>
Subsequent sections of this chapter describe how to link source and target
elements, add XSLT constructs, and create XPath expressions in design view.
A node in the target tree can be linked only once (that is, you cannot have two
links connecting a node in the target tree).
An incomplete function and expression does not result in an XPath expression in
source view. If you switch from design view to source view with one or more
incomplete expressions, the Mapper Messages window displays warning
messages.
40-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When you map duplicate elements in the XSLT Mapper, the style sheet becomes
invalid and you cannot work in design view. The Log window shows the error
messages when you map an element with a duplicate name. Example 405
provides details.
Example 405
Note:
40.2.1 How to Create an XSL Map File in Oracle BPEL Process Manager
A transform activity enables you to create a transformation using the XSLT Mapper in
Oracle BPEL Process Manager. This tool enables you to map one or more source
elements to target elements. For example, you can map incoming source purchase
order schema data to outgoing invoice schema data.
To create an XSL map file in Oracle BPEL Process Manager:
1. From the Component Palette, drag a transform activity into your BPEL process
diagram. Figure 404 provides an example.
2.
3.
Add source variables from which to map elements by clicking the Add icon
and selecting the variable and part of the variable as needed (for example, a
payload schema consisting of a purchase order request).
40-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note: You can select multiple input variables. The first variable
defined represents the main XML input to the XSL map. Additional
variables that are added here are defined in the XSL map as input
parameters.
b.
c.
Add the target part of the variable (for example, a payload schema consisting
of an invoice) to which to map.
4.
In the Mapper File field, specify a map file name or accept the default name. You
create your mappings in the map file using the XSLT Mapper.
5.
Click the Add icon (second icon to the right of the Mapper File field) to create a
mapping. If the file exists, click the Edit icon (third icon) to edit the mapping.
The XSLT Mapper appears.
6.
Go to Section 40.1, "Introduction to the XSLT Mapper" for an overview of using the
XSLT Mapper.
40.2.2 How to Create an XSL Map File from Imported Source and Target Schema Files
in Oracle BPEL Process Manager
Note: If you select a file with a.xslt extension such as
xform.xslt, it opens the XSLT Mapper to create an XSL file named
xform.xslt.xsl, even though your intention was to use the
existing xform.xslt file. A .xsl extension is appended to any file
that does not have a .xsl extension, and you must create the
mappings in the new file. As a work around, ensure that your files
first have an extension of .xsl. If the XSL file has an extension of
.xslt, then rename it to .xsl.
The following steps provide a high level overview of how to create an XSL map in
Oracle BPEL Process Manager using a po.xsd file and invoice.xsd file.
To create an XSL map file from imported source and target schema files in
Oracle BPEL Process Manager:
1. In Oracle JDeveloper, select the application project in which you want to create the
new XSL map.
2.
3.
Import the po.xsd and invoice.xsd files into the project. For example:
a.
b.
4.
5.
WSDL files that have been added to the project appear under Project
WSDL Files.
Schema files that have been added to the project appear under Project
Schema Files.
Schema files that are not part of the project can be imported using the
Import Schema File facility. Click the Import Schema File icon (first icon
to the right and above the list of schema files).
WSDL files that are not part of the project can be imported using the
Import WSDL File facility. Click the Import WSDL File icon (second icon
to the right and above the list of schema files).
6.
In the File Name field, enter a name for the XSL map file.
7.
Select the root element for the source and target trees. In the example in
Figure 406, the PurchaseOrder element is selected for the source root element
and the Invoice element is selected for the target root element.
8.
Click OK.
A new XSL map is created, as shown in Figure 407.
40-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
Save and close the file now or begin to design your transformation. Information on
using the XSLT Mapper is provided in Section 40.1, "Introduction to the XSLT
Mapper."
10. From the Component Palette, drag a transform activity into your BPEL process.
11. Double-click the transform activity.
12. Specify the following information:
a.
Add source variables from which to map elements by clicking the Add icon
and selecting the variable and part of the variable as needed (for example, a
payload schema consisting of a purchase order request).
Note: You can select multiple input variables. The first variable
defined represents the main XML input to the XSL map. Additional
variables that are added here are defined in the XSL map as input
parameters.
b.
c.
Add the target part of the variable (for example, a payload schema consisting
of an invoice) to which to map.
13. To the right of the Mapper File field, click the Search icon (first icon) to browse for
XSLT Mapper.
To launch the XSLT Mapper from the Mediator Editor and create or update a data
transformation XSL file, follow these steps.
To create an XSL map file in the Mediator Editor:
1. Open the Mediator Editor.
2.
To the left of Routing Rules, click the + icon to open the Routing Rules panel.
The transformation map icon is visible in the routing rules panel.
3.
To the right of the Transform Using field shown in Figure 408, click the
appropriate transformation map icon to open the Transformation Map dialog.
The appropriate Transformation Map dialog displays with options for selecting an
existing transformation map (XSL) file or creating a new map file. For example, if
you select the transformation map icon in the Synchronous Reply section, the
dialog shown in Figure 409 appears.
Figure 409 Reply Transformation Map Dialog
If the routing rule includes a synchronous reply or fault, the Reply Transformation
Map dialog or Fault Transformation Map dialog contains the Include Request in
40-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
the Reply Payload option. When you enable this option, you can obtain
information from the request message. The request message and the reply and
fault message can consist of multiple parts, meaning you can have multiple source
schemas. Callback and callback timeout transformations can also consist of
multiple parts.
Each message part includes a variable. For a reply transformation, the reply
message includes a schema for the main part (the first part encountered) and an
in.partname variable for each subsequent part. The include request message
includes an initial.partname variable for each part.
For example, assume the main reply part is the out1.HoustonStoreProduct
schema and the reply also includes two other parts that are handled as variables,
in.HoustonStoreProduct and in.HoustonStoreProduct2. The request message
includes three parts that are handled as the variables initial.expense,
initial.expense2, and initial.expense3. Figure 4010 provides an example.
Figure 4010
4.
Reply Part
Use Existing Mapper File, and then click the Search icon to browse for an
existing XSLT Mapper file (or accept the default value).
Create New Mapper File, and then enter a name for the file (or accept the
default value). If the source message in the WSDL file has multiple parts,
variables are used for each part, as mentioned in Step 3. When the target of a
transformation has multiple parts, multiple transformation files map to these
targets. In this case, Oracle Mediators transformation dialog has a separate
panel for each target part. For example, Figure 4011 shows a request in which
the target has three parts:
5.
Click OK.
If you chose Create New Mapper File, the XSLT Mapper opens to enable you to
correlate source schema elements to target schema elements.
6.
Go to Section 40.1, "Introduction to the XSLT Mapper" for an overview of using the
XSLT Mapper.
40.2.4 What You May Need to Know About Creating an XSL Map File
XSL file errors do not display during a transformation at runtime if you manually
remove all existing mapping entries from an XSL file except for the basic format data.
Ensure that you always specify mapping entries. For example, assume you perform
the following actions:
1.
Create a transformation mapping of input data to output data in the XSLT Mapper.
2.
Design the application to write the output data to a file using the file adapter.
3.
Manually modify the XSL file and remove all mapping entries except the basic
format data. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0"
xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu
nctions.Xpath20"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:ns0="http://xmlns.oracle.com/pcbpel/adapter/file/MediaterDemo/Validation
UsingSchematron/WriteAccounInfoToFile/"
xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu
nctions.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:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.servi
ce.common.functions.GetRequestHeaderExtnFunction"
xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
xmlns:imp1="http://www.mycompany.com/MyExample/NewAccount"
xmlns:tns="http://oracle.com/sca/soapservice/MediaterDemo/ValidationUsingSchem
atron/CreateNewCustomerService"
xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRe
fXPathFunctions"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
40-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:inp1="http://www.mycompany.com/MyExample/NewCustomer"
exclude-result-prefixes="xsi xsl tns xsd inp1 ns0 imp1 plt xp20 bpws orcl dvm
hwf mhdr ids xref ora">
</xsl:stylesheet>
While the file can still be compiled, the XSL mapping is now invalid.
4.
40.2.5 What You May Need to Know About Importing a Composite with an XSL File
If you import a SOA archive exported from Oracle Enterprise Manager Fusion
Middleware Control into Oracle JDeveloper by selecting File > Import > SOA Archive
Into SOA Project, you cannot open any XSL map files because the map headers have
been removed.
As a work around, perform the following steps:
1.
Select File > New > SOA Tier > Transformations > XSL Map From XSL
Stylesheet, and click OK.
The Create XSL Map File From XSL Stylesheet appears.
2.
In the File Name field, enter a new map name (for this example,
Transformation_new.xsl).
3.
In the XSL Stylesheet to Create From field, enter the name of the map file missing
the map headers (for this example, Transformation_old.xsl).
4.
For the source and target, enter the correct map source and target schema
information to use for recovering the map header.
5.
After successful creation of the new map file, delete the old map file
(Transformation_old.xsl).
6.
Rename the new map file with the recovered map header to the old map file name
to prevent reference breakage (for this example, rename Transformation_
new.xslt to Transformation_old.xsl).
40.2.6 What Happens at Runtime If You Pass a Payload Through Oracle Mediator
Without Creating an XSL Map File
If you design a SOA composite application to pass a payload through Oracle Mediator
without defining any transformation mapping or assigning any values, Oracle
Mediator passes the payload through. However, for the payload to be passed through
successfully, the source and target message part names must be the same and of the
same type. Otherwise, the target reference may fail to execute with error messages
such as Input source like Null or Part not found.
40.2.7 What Happens If You Receive an Empty Namespace Tag in an Output Message
The XML representation from an XSL file may differ from that used in a scenario in
which a message is passed through with a transformation being performed or in
which an assign activity is used, even though the XMLs are syntactically and
semantically the same. For example, if you use an Oracle Mediator service component
Creating Transformations with the XSLT Mapper 40-15
2.
3.
Enter a parameter name for the source (the name can also be qualified by a
namespace and prefix).
40-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4013
4.
In the Source Schema section, click Select to select a schema for the new source.
The Type Chooser dialog appears.
5.
Select or import the appropriate schema or WSDL file for the parameter in the
same manner as when creating a new XSLT map. For this example, the Customer
element from the sample customer.xsd file is selected.
6.
Click OK.
The schema definition appears in the Source Schema section of the Create Source
as Parameter dialog.
7.
Click OK.
The selected schema is imported and the parameter appears in the source panel
above the main source. The parameter can be expanded as shown in Figure 4014
to view the structure of the underlying schema.
Figure 4014
Expanded Parameter
3.
4.
5.
In the Set Text dialog, enter text (for example, Discount Applied, as shown in
Figure 4016).
6.
7.
To modify the text associated with the node, right-click the node and select Edit
Text to invoke the Set Text dialog again.
8.
9.
To remove the text associated with the node, right-click the node and select
Remove Text.
40-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Figure 4017
Description of Function
4.
Drag a function from the Component Palette to the center panel of the XSLT
Mapper. You can then connect the source parameters from the source tree to the
function and the output of the function to a node in the target tree. For the
following example, drag the concat function from the String section of the
Component Palette to the center panel.
5.
6.
Drag a thread from the ShippedTo name and connect it to the output (right) side
on the concat function, as shown in Figure 4018.
For more information about how to add, remove, and reorder function parameters, see
the online Help for the Edit Function dialog.
Drag the left-trim and right-trim functions into the border area of the concat
function.
40-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Chain them as shown in Figure 4020 by dragging lines from the output side of
one function to the input side of the next function.
Chaining Functions
Add the template to an external file that you include in your XSL map.
The templates you define appear in the User Defined Named Templates list of the
User Defined page in the Component Palette. You can use named templates in almost
the same way as you use other functions. The only difference is that you cannot link
the output of a named template to a function or another named template; you can only
link its output to a target node in the target tree.
To create named templates, you must be familiar with the XSLT language. See any
XSLT book or visit the following URL for details about writing named templates:
http://www.w3.org/TR/xslt
For more information about including templates defined in external files, see
Section 40.3.6.7, "Including External Templates with xsl:include."
java.lang.String
int
float
double
boolean
oracle.xml.parser.v2.XMLNodeList
oracle.xml.parser.v2.XMLDocumentFragment
Create an XML extension function configuration file. This file defines the functions
and their parameters.
This file must have the name ext-mapper-xpath-functions-config.xml.
See Section B.7, "Creating User-Defined XPath Extension Functions" for more
information on the format of this file. The following syntax represents the
functions toKilograms and replaceChar as they are coded in Step 1.
<?xml version="1.0" encoding="UTF-8"?>
<soa-xpath-functions version="11.1.1"
xmlns="http://xmlns.oracle.com/soa/config/xpath" xmlns:sample=
"http://www.oracle.com/XSL/Transform/java/oracle.sample.SampleExtensionFunction
s"
>
<function name="sample:toKilograms">
<className>oracle.sample.SampleExtensionFunctions</className>
<return type="number"/>
40-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<params>
<param name="pounds" type="number"/>
</params>
<desc>Converts a value in pounds to kilograms</desc>
</function>
<function name="sample:replaceChar">
<className>oracle.sample.SampleExtensionFunctions</className>
<return type="string"/>
<params>
<param name="inputString" type="string"/>
<param name="oldChar" type="string"/>
<param name="newChar" type="string"/>
</params>
<desc>Returns a new string resulting from replacing all
occurrences
of oldChar in this string with newChar</desc>
</function>
</soa-xpath-functions>
The functions need a namespace prefix and a namespace. In this sample, they
are sample and
http://www.oracle.com/XSL/Transform/java/oracle.sample.Sam
pleExtensionFunctions.
The function namespace must start with
http://www.oracle.com/XSL/Transform/java/ for extension
functions to work with the Oracle XSLT processor.
The last portion of the namespace, in this sample
oracle.sample.SampleExtensionFunctions, must be the fully
qualified name of the Java class that implements the extension functions.
The types and their equivalent Java types shown in Table 401 can be used for
parameter and return values:
Table 401
Java Type
string
java.lang.String
boolean
boolean
number
node-set
oracle.xml.parser.v2.XMLNodeList
tree
oracle.xml.parser.v2.XMLDocumentFragme
nt
3.
Create a JAR file containing both the XML configuration file and the compiled
classes. The configuration file must be contained in the META-INF directory for
the JAR file. For the example in this section, the directory structure is as follows
with the oracle and META-INF directories added to a JAR file:
oracle
META-INF
ext-mapper-xpath-functions-config.xml
5.
Click the Add button and navigate to and select your JAR file.
6.
7.
To make the functions available in the runtime environment, see Section B.7.3,
"How to Deploy User-Defined Functions to Runtime" for details.
3.
Drag the xpath-expression function from the list into the XSLT Mapper.
Figure 4021 provides details.
4.
5.
Press Ctrl+Space to invoke the XPath Building Assistant. Figure 4023 shows the
XPath Building Assistant.
40-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4023
For more information about using the XPath Building Assistant, see the online
Help for the Edit XPath Expression dialog and Section B.6, "Building XPath
Expressions in the Expression Builder in Oracle JDeveloper."
1.
Figure 4024
2.
Drag an XSLT construct from the group onto a node in the target tree. If the XSLT
construct can be applied to the node, it is inserted in the target tree. The when and
otherwise constructs must be applied to a previously-inserted choose node.
To add XSLT constructs through the context menu on the target tree:
1. Right-click the element in the target tree where you want to insert an XSLT
construct. A context menu is displayed. Figure 4025 provides details.
Figure 4025 XSLT Constructs in Available Through the Context Menu
2.
Select Add XSL Node and then the XSLT construct you want to insert.
The XSLT construct is inserted. In most cases, an error icon initially appears next to the
construct. This indicates that the construct requires an XPath expression to be defined
for it.
In the case of the for-each construct, for example, an XPath expression defines the
node set over which the for-each statement loops. In the case of the if construct, the
XPath expression defines a boolean expression that is evaluated to determine if the
contents of the if construct are executed.
The XPath expression can be created in the same manner as mapping elements and
attributes in the target tree. The following methods create an underlying XPath
expression in the XSLT. You can perform all of these methods on XSLT constructs in
the target tree to set their XPath expressions:
Adding functions
The following sections describe specific steps for inserting each supported XSLT
construct.
40-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Connect PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/if/AccountNumber.
If the ProductName field is optional in both the source and target and the element
does not exist in the source document, then an empty ProductName element is
created in the target document. To avoid this situation, add an if statement to test for
the existence of the source node before the target node is created, as shown in the
following code.
<xsl:if test="ProductName">
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
</xsl:if>
3.
Connect PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/choose/when to define the condition.
4.
Connect PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/choose/when/AccountNumber.
5.
In the target tree, select XSL Add Node > choose and right-click to invoke the
context sensitive menu.
6.
7.
Connect PurchaseOrder/BranchAccount/AccountNumber to
Invoice/BilledToAccount/choose/otherwise/AccountNumber.
3.
Connect PurchaseOrder/Items/HighPriorityItems/Item/ProductName to
Invoice/ShippedItems/for-each/Item/ProductName.
4.
Connect PurchaseOrder/Items/HighPriorityItems/Item/Quantity to
Invoice/ShippedItems/for-each/Item/Quantity.
5.
Connect PurchaseOrder/Items/HighPriorityItems/Item/USPrice to
Invoice/ShippedItems/for-each/Item/PriceCharged.
40-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Notes:
3.
4.
Connect PurchaseOrder/Items/LowPriorityItems/Item/ProductName to
Item/ProductName in the copied for-each.
5.
Connect PurchaseOrder/Items/LowPriorityItems/Item/Quantity to
Item/Quantity in the copied for-each.
6.
Connect PurchaseOrder/Items/LowPriorityItems/Item/USPrice to
Item/PriceCharged in the copied for-each.
Select Add XSL Node > sort. The Sort Edit Dialog is displayed, as shown in
Figure 4029.
3.
Select options to add to the sort statement as needed. See the online Help for
information on options.
4.
5.
To set the field on which to sort, drag the necessary sort field node in the source
tree to the sort node in the target tree. This creates a simple link and sets the XPath
expression for the select attribute on the xsl:sort.
6.
To add additional sort statements, right-click the for-each to add another sort or
right-click an existing sort node to insert a new sort statement before the selected
sort node.
7.
To edit a sort node, double-click the sort node or right-click and select Edit Sort
from the context menu. This invokes the Sort Edit Dialog and enables you to
change the sort options.
Right-click the node and select Add XSL Node > copy-of.
40-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If the node is not an any element node, a dialog appears requesting you to either
replace the selected node or replace the children of the selected node.
3.
Select the correct option for your application and click OK.
If you select Replace the selected node with the copy-of construct, a processing
directive is created immediately following the copy-of in the XSL indicating which
node is replaced by the copy-of construct. Without the processing directive in the
XSL, the conversion back to design view is interpreted incorrectly. For this reason,
do not remove or edit this processing instruction while in source view.
4.
Set the source node for the copy-of construct by dragging and dropping from the
source tree or by creating an XPath expression.
Note: Always create the copy-of command in design view so that
the correct processing directive can be created in the XSLT Mapper to
indicate the correct placement of the copy-of command in the target
tree.
3.
Note:
The behavior of the auto map can be tuned by altering the settings in Oracle
JDeveloper preferences or by right-clicking the XSLT Mapper and selecting Auto Map
Preferences. This displays the dialog shown in Figure 4031.
Figure 4031 Auto Map Preferences
Invoke the automatic mapping feature, which attempts to automatically link all
relevant nodes under the selected source and target. When disabled, you must
individually map relevant nodes.
Display and review all potential source-to-target mappings detected by the XSLT
Mapper, and then confirm to create them.
Be prompted to customize the auto map preferences before the auto map is
invoked.
Select the Basic or Advanced method for automatically mapping source and target
nodes. This action enables you to customize how the XSLT Mapper attempts to
automatically link all relevant nodes under the selected source and target.
Manage your dictionaries. The XSLT Mapper uses the rules defined in a dictionary
when attempting to automatically map source and target elements.
40-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information on the fields, see the online Help for the Auto Map
Preferences dialog.
Follow these instructions to see potential source mapping candidates for a target node.
To automatically map nodes:
1. Right-click the target node and select Show Matches.
2.
Figure 4032
For more information on the fields, see the online Help for the Auto Map dialog.
For more information about the fields, see the online Help for the Auto Map dialog.
If no nodes are mapped, the automatic mapping algorithm does not match the names
test1 and test2. However, if mapping exists between the test1 and test2 nodes, the
algorithm predefines the names test1 and test2 as synonyms for any additional
mapping.
In the example in Figure 4034, if you drag the exampleElement from the source to the
target, the automatic mapping algorithm maps the test1 node in the source to the test2
40-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
node in the target because your map previously linked those two names. This results
in the map shown in Figure 4035:
Figure 4035
In the list, select a target node. The node is highlighted. A checkmark indicates
that the target node is required to be mapped. If not required, the checkbox is
empty.
Nodes are marked as required in the Completion Status dialog
based on the XSD definition for a node. It is possible that a node
marked as required is not actually required for a specific mapping if a
parent node of the required node is optional and is not part of the XSL
mapping.
Note:
Go to Tools > Preferences > XSL Maps > Auto Map and note the current
automatic mapping settings.
Because dictionary entries are dependent upon the current
automatic mapping settings, you must make a note of those settings
for future use. To later reapply a dictionary mapping, it is best to set
the automatic mapping preferences to those that were in effect at the
time the dictionary was created. Therefore, it is important to note the
automatic mapping settings at the time the dictionary is created.
Note:
3.
In the XSLT Mapper, right-click the center panel of the XSLT Mapper and select
Generate Dictionary.
40-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This prompts you for the dictionary name and the directory in which to place the
dictionary.
4.
Check the Open Dictionary checkbox to view the dictionary after it is created. If
the dictionary file is empty, this indicates that no fields were mapped that would
not have been mapped with the current automatic mapping settings.
5.
To use the dictionary in another map, load the dictionary by selecting Tools >
Preferences > XSL Maps > Auto Map. Figure 4037 provides details.
Figure 4037
6.
7.
Browse for and select the dictionary XML file that was previously created from a
similar map.
8.
Click OK.
9.
Before leaving the automatic mapping preferences, modify the mapping settings to
match those used when creating the dictionary.
40.3.11 What You May Need to Know About Generating Dictionaries in Which
Functions are Used
You cannot create a dictionary for mappings in which functions are used. In these
cases, the dictionary XML instructions are missing for the elements that were
automatically mapped or which had an XPath function mapping. For example, assume
you use string functions to map XSDs during design time. If you right-click the center
panel of the XSLT Mapper and select Generate Dictionary, the dictionary is created,
Creating Transformations with the XSLT Mapper 40-37
but instructions are not created in all places in which the string functions were used
during mapping.
You can create a dictionary for simple type mappings.
Parameters are created in the source tree, are global, and can be used anywhere in
the mappings.
Variables are created in the target tree, and are either global or local. The location
in which they are defined in the target tree determines if they are global or local.
Global variables are defined immediately beneath the <target> node and
immediately above the actual target schema (for example, POAcknowledge).
Right-click the <target> node to create a global variable.
Local variables are defined on a specific node beneath the actual target schema
(for example, subnode name on schema POAcknowledge). Local variables
can have the same name provided they are in different scopes. Local variables
can only be used in their scopes, while global variables can be used anywhere
in the mappings.
Specify details for the parameter. For this example, a parameter named discount
with a numeric default value of 0.0 is specified.
40-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4038
3.
Click OK.
Specify details.
Since variables appear in the target tree, their XPath expression can be set in the
same manner as other XSLT constructs in the target tree after inserting the
variable. Therefore, the only required information in this dialog is a name for the
variable. To set content for the variable, you must enter it through this dialog.
Content is handled differently from the XSLT select attribute on the variable.
3.
Click OK.
The variable is added to the target tree at the selected position.
The variable initially has a warning icon beside it. This indicates that its select
XPath statement is undefined. Define the XPath through linking a source node,
creating a function, or defining an explicit XPath expression as done for other
target elements and XSLT constructs.
3.
40-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4040
The first match found is highlighted, and the Find dialog closes. If no matches are
found, a message displays on-screen.
4.
Select the F3 key to find the next match in the direction specified. To search in the
opposite direction, select the Shift and F3 keys.
Note: You cannot search on functions or text values set with the Set
Text option.
Generate empty nodes for all required or nillable, unmapped target nodes.
Empty elements are then generated for the selected unmapped nodes. If the
unmapped node is nillable, it is generated with xsi:nil="true".
XSL map generation fails. You can create and import a file that directs the XSLT
Mapper to ignore and preserve these specific elements during XSLT parsing by
selecting Preferences > XSL Maps in the Tools main menu of Oracle JDeveloper.
For example, preprocessing may create elements named myElement and
myOtherElementWithNS that you want the XSLT Mapper to ignore when it creates
the graphical representation of the XSLT document. You create and import a file with
these elements to ignore that includes the syntax shown in Example 406.
Example 406
<elements-to-ignore>
<element name="myElement"/>
<element name="myOtherElementWithNS" namespace="NS"/>
</elements-to-ignore>
40.3.16 How to Import a Customization File to Specify Display Preferences in the XSLT
Mapper
You can import a customization file that specifies display preferences in the XSLT
Mapper. The only option currently available is to allow a fixed attribute value to be
seen as part of the element name in the XSLT Mapper source and target trees.
In the customization file shown in Example 407, the first fixed attribute found on any
element in the XSLT Mapper trees with the name LongName, LongName2, or Name is
shown as part of the element tree name. The fixed attribute value is shown in
parentheses to the right of the actual element name in the tree.
Example 407
Customization File
To the right of the Custom Display Options Config File field, click Browse.
40-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
2.
Replacing a Schema
3.
Select Yes or No. If expressions are not cleared, you may need to correct the map
in source view before entering design view again.
40.3.18 How to Substitute Elements and Types in the Source and Target Trees
You can substitute elements and types in the source and target trees.
Use element substitution when:
A global type is available in the underlying schema that is derived from the type
of an element in the source or target tree. The global type can then be substituted
for the original type of the element. Any type derived from an abstract type can be
substituted for that abstract type.
An element in the source or target tree is defined to be of the type anyType. Any
global type defined in the schema can then be substituted.
From the context menu, select Substitute Element or Type. If this option is
disabled, no possible substitutions exist for the element or its type in the
underlying schema.
The Substitute Element or Type dialog shown in Figure 4042 appears.
3.
4.
5.
Click OK.
The element or type is substituted for the originally selected element. This
selection displays differently depending upon whether this is a type or element
substitution and this is the source or target tree.
40-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4043
Figure 4044
Figure 4045
the original node or a substituted node. You can map to any structural
elements in the substituted element.
Figure 4046 If the Element is in the Source Tree and Element Substitution is Selected
Note:
6.
To remove a substituted node, right-click any node with an S icon and select
Remove Substitution from the context menu.
7.
To see all possible nodes where substitution is allowed, right-click the source or
target tree and select Show Substitution Node Icons.
All nodes where substitution is possible are marked with an * icon, as shown in
Figure 4047.
8.
To hide the icons, right-click and select Hide Substitution Node Icons.
Increase the Xmx value in the ide.conf file. (Note that when you are on a 64-bit
host, this value can be very large.)
Map small sections of the file one at a time.
Reduce the expansion level limit in the Preferences dialog - XSL Maps page. This
page is accessible from the Tools main menu in Oracle BPEL Designer by selecting
Preferences > XSL Maps.
40-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Select the Generate Source XML File checkbox to create a sample XML file based
on the map source XSD schema.
3.
Select the Show Source XML File checkbox to display the source XML files for the
test. The source XML files display in an Oracle JDeveloper XML editor.
If the map has defined parameters, the Parameters With Schema or Parameters
Without Schema table can appear.
a.
If the Parameters With Schema table appears, you can specify an input XML
file for the parameter using the Browse button. Select the Generate File
checkbox to generate a file.
b.
If the Parameters Without Schema table appears, you can specify a value by
selecting the Specify Value checkbox and making appropriate edits to the
Type and Value columns.
4.
In the Target XML File field, enter a file name or browse for a file name in which
to store the resulting XML document from the transformation.
5.
Select the Show Target XML File checkbox to display the target XML file for the
test. The target XML file displays in an Oracle JDeveloper XML editor.
40-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
If you select to show both the source and target XML, you can customize the
layout of your XML editors. Select Enable Auto Layout in the upper right corner
and click one of the patterns.
7.
Click OK.
The test results shown in Figure 4050 appear.
For this example, the source XML and target XML display side-by-side with the
XSL map underneath (the default setting). Additional source XML files
corresponding to the Parameters With Schema table are displayed as tabs in the
same area as the main source file. You can right-click an editor and select Validate
XML to validate the source or target XML against the map source or target XSD
schema.
Figure 4050
Test Results
Note: If the XSL map file contains domain value map (DVM) and
cross reference (XREF) XPath functions, it cannot be tested. These
functions cannot be executed during design time; they can only be
executed during runtime.
XSL map file name, source and target schema file names, their root element names,
and their root element namespaces
1.
For more information about the fields, see the online Help for the Generate Report
dialog.
3.
-Xmx1024M
In addition, you can also unselect the Open Report option on the Generate Report
dialog before generating the report.
40-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Maximum depth
To avoid the occurrence of recursion in sample XML generation caused by
optional elements, specify a maximum depth in the XML document hierarchy tree
beyond which no optional elements are generated.
In addition to this sample, Oracle provides other transformation samples that are
available for download. These samples are described in Table 402. To access these
samples, see the Oracle SOA Suite samples.
Table 402
Transformation Samples
Sample
Description
mapper-101-basic-mapping
mapper-102-import-and-test
mapper-104-auto-mapping
Report execution
Using variables
Description
mapper-109-whats-new
2.
3.
4.
5.
From the Oracle Extensions section of the Component Palette, drag a Transform
activity below the SetDiscontinuedProducts assign activity.
40-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
5.
b.
c.
d.
Click OK.
e.
Click the Add icon a second time and select DiscontinuedList from the
Source Variable list. The variable is created in the SetDiscontinuedProducts
assign activity before the transformation activity.
f.
Click OK.
g.
From the Target Variable list, select outputVariable. This is the invoice that is
returned from the BPEL process.
h.
i.
Click the Create Mapping icon to the right of the Mapper Name field to create
and open the mapper file.
The XSLT Mapper opens.
j.
From the File menu, select Save All. Your map looks as shown in
Figure 4052. The second source is loaded as a parameter with the name
DiscontinuedList:
Figure 4052
40.5.3 How To Use Type Substitution to Map the Purchase Order Items
You now use type and element substitutions to map the purchase order items to the
invoice items.
To use type substitution to map the purchase order items:
1. In the target tree, expand the tree so that Invoice/Items/Item is visible. The Item
element has an error icon next to it.
2.
Move the mouse over the element to display a tool tip indicating that this element
is defined as an abstract type.
To map to the Item element, you must first indicate which type the element takes
in the final XML output.
3.
Perform the following steps to indicate which type the element takes:
a.
b.
Note:
4.
5.
From the File menu, select Save All to save the map file.
Define the test expression for the if statement by selecting the following (the
method for how variables are set has changed from the Release 10g versions of
Oracle JDeveloper):
40-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
a.
Add a global variable to the target tree by right-clicking the Invoice node and
selecting Add Variable.
The Add Variable dialog appears.
b.
In the Local Name field, enter DelimitedList. In the following steps, this
variable is set to a string with a delimited list of discontinued product names.
c.
Click OK.
The variable is added with a warning icon next to it.
d.
To set the value of the variable, drag the create-delimited-string function from
the String section of the Component Palette to the center panel.
e.
f.
g.
h.
i.
Click OK.
The input source is referenced in XPath expressions with $DiscontinuedList.
This source is referenced as an input parameter in XPath expressions.
3.
To set the XPath expression for the if statement, drag the contains function from
the String section of the Component Palette to the center panel.
4.
Drag the not function from the Logical Functions section of the Component
Palette to the shaded area surrounding the contains function you added in Step 3.
5.
Drag a line from the output side of the contains function to the input side of the
not function.
6.
Drag a line from the output side of the not function to the if statement.
7.
8.
Enter values for the inputString and searchString, and click OK.
9.
From the File menu, select Save All to save the map file.
The map file now looks as shown in Figure 4054.
Place the mouse over this element to display a tool tip indicating that this element
is abstract.
In this situation, you must perform an element substitution to map the element.
3.
Right-click the Contact element in the source tree and select Substitute Element or
Type.
The Substitute Element or Type dialog is displayed with a list of elements in the
substitution group of the abstract element Contact.
4.
5.
6.
Expand the ShippedTo element in the target tree to show the target address fields.
Note the similarity in field names here, indicating that the automatic mapper can
be used.
7.
8.
Map any remaining elements not matched by the automatic mapper so that this
section of the map is as shown in Figure 4055:
40-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4055
9.
XSLT Mapper
From the File menu, select Save All to save the map file.
3.
Use the copy-of xsl statement to copy the attachment data from the source to the
target any element:
a.
Right-click the Invoice/Data/any element and select Add XSL Node >
copy-of.
The copy-of statement is added and the original any element is grayed out.
This indicates that it is to be replaced by the nodes selected by the copy-of
statement.
b.
4.
5.
b.
c.
Right-click the for-each statement in the target tree and select Add XSL Node
> sort.
The Sort Edit dialog appears.
b.
c.
d.
e.
From the File menu, select Save All to save the map file. The map now looks as
shown in Figure 4056:
2.
Follow these steps to select the sample input file for testing:
a.
b.
Click the Browse button for the Source XML File field.
c.
A second sample file has been created with discontinued item data. This file is
artifacts/xml/DiscontinuedItems.xml.
3.
4.
Follow these steps to use this file as the second source input.
a.
b.
40-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
40-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
41
41
For samples that show how to use business events with Oracle Mediator, see the
Oracle SOA Suite samples.
For information about creating composite sensors on service components that
subscribe to business events, see Section 50, "Defining Composite Sensors."
For information about troubleshooting business events, including specifying the
number of threads, stopping event delivery, and specifying the maximum number of
deliveries, see Appendix "Troubleshooting Oracle SOA Suite and Oracle BPM Suite" of
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
For information about business event tuning, see Oracle Fusion Middleware Performance
and Tuning Guide.
Need to know where subscribers (if any) are and what they do with the data.
These are important distinctions between business events and direct service
invocations that rely on the Web Services Description Language (WSDL) file contract
(for example, a SOAP service client). If the author of the event depends on the receiver
of the event, then messaging typically must be accomplished through service
invocation rather than through a business event. Unlike direct service invocation, the
business event separates the client from the server.
A business event is defined using the event definition language (EDL). The EDL is a
schema used to build business event definitions. Applications work with instances of
the business event definition.
The EDL consists of the following:
Global name
Typically a Java package name (for example,
com.acme.ExpenseReport.created), though this is not required.
Payload definition
The most common use for a definition is an XML Schema (XSD). The payload of a
business event is defined using an XSD. The schema URI is contained in the root
element of the payload.
Example 411 shows an EDL file with two business events in the BugReport event
definition: bugUpdated and bugCreated. The namespace (BugReport) and
associated schema file (BugReport.xsd) are referenced.
Example 411
41-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Business events are deployed to the Oracle Metadata Services (MDS) Repository.
Deploying a business event to the MDS Repository along with its artifacts (for
example, the XSDs) is known as publishing the EDL (or event definition). This action
transfers the EDL and its artifacts to a shared area in the MDS Repository. An object in
an MDS Repository shared area is visible to all applications in the Resource Palette of
Oracle JDeveloper. After an EDL is published, it can be subscribed to by other
applications. EDLs cannot be unpublished; the definition always exists.
A subscription is for a specific qualified name (QName) (for example,
x.y.z/newOrders). A QName is a tuple (URI, localName) that may be derived
from a string prefix:localName with a namespace declaration such as
xmlns:prefix=URI or a namespace context. In addition, subscriptions can be further
narrowed down by using content-based filters.
Business events are published to the EDN. The EDN runs within every SOA instance.
Raised events are delivered by EDN to the subscribing service components. Oracle
Mediator service components and BPEL process service components can subscribe to
and publish events.
The EDN has two different implementations:
If you are using an Oracle database, Oracle recommends that you use EDN-DB instead
of EDN-JMS.
The EDN does not support durable subscriptions (whether
they are backed by native advanced queueing (AQ) or Oracle
WebLogic Server JMS). The subscribing service component must be
running to receive events.
Note:
optimized to use local event connections. The boundary for events is the application
instance. When an event is raised in the application instance, subscriptions registered
in the application instance are executed. Events are not propagated from one
application instance to another. Propagation is achieved through an Oracle Mediator
in both instances, which listens for events and publishes them to a JMS queue.
41.1.2 Events Published and Subscribed to in the Same Process Are Not Delivered
If an event is published and subscribed to in the same process, the event is not
delivered to the subscriber to avoid any cyclic execution. This is by design.
If you require this functionality, you can delegate event publishing to a separate
process.
In the SOA Composite Editor, click the icon above the designer. Figure 411
provides an example.
b.
From the File main menu, select New > SOA Tier > Service Components >
Event Definition.
Table 411
Field
Value
Enter a name.
Note: Do not enter a forward slash (/) as the event name. This
creates an event definition file consisting of only an extension for
a name (.edn).
Directory
Namespace
41-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
5.
Click the Search icon to select the payload, and click OK. Figure 412 provides
details.
6.
7.
Click OK.
The added event now appears in the Events section, as shown in Figure 414.
8.
Above the editor, click the cross icon (x) next to event_definition_name.edl
to close the editor.
9.
Click Yes when prompted to save your changes. If you do not save your changes,
the event is not created and cannot be selected in the Event Chooser window.
The business event is published to the Oracle MDS Repository and you are
returned to the SOA Composite Editor. The business event displays for browsing
in the Resource Palette.
3.
4.
5.
6.
41-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Events are delivered to the subscriber in its own global (that is, JTA)
transaction. Any changes made by the subscriber within that transaction are
committed after the event processing is complete. If the subscriber fails, the
transaction is rolled back. Failed events are retried a configured number of
times.
guaranteed
Events are delivered to the subscriber asynchronously without a global
transaction. The subscriber can choose to create its own local transaction for
processing, but it is committed independently of the rest of event processing.
This option incurs a lower cost than the one and only one option because
there is only the trip to one queue (the main event queue). In addition, EDN
does not attempt to resend an event (regardless of the backing store being AQ
or JMS). If one or more subscribers fail to consume the event (while others
succeed), those subscribers lose the message. In this respect, guaranteed
delivery actually means best effort delivery; that is, it is not guaranteed that
each subscriber definitely consumes the message.
immediate
Events are delivered to the subscriber in the same global transaction and same
thread as the publisher. The publish call does not return until all immediate
subscribers have completed processing. If any subscribers throw an exception,
no additional subscribers are invoked and an exception is thrown to the
publisher. The transaction is rolled back in case of any error during immediate
processing.
7.
If you want to filter the event, double-click the Filter column of the selected event
or select the event and click the filter icon (first icon) above the table. This displays
the Expression Builder dialog. This dialog enables you to specify an XPath filter
expression. A filter expression specifies that the contents (payload or headers) of a
message be analyzed before any service is invoked. For example, you can apply a
filter expression that specifies that a service be invoked only if the message
includes a customer ID.
When the expression logic is satisfied, the event is accepted for delivery.
For more information about filters, see Section 20.3.2.8, "How to Specify an
Expression for Filtering Messages."
Figure 415 shows the Create Mediator dialog.
8.
Click OK.
Figure 416 shows an icon on the left side that indicates that Oracle Mediator is
configured for an event subscription.
41.3.2 What Happens When You Create and Subscribe to a Business Event
The source code in Example 412 provides details about the subscribed event of the
Oracle Mediator service component.
Example 412
Subscribed Event
<component name="OrderPendingEvent">
<implementation.mediator src="OrderPendingEvent.mplan"/>
<business-events>
<subscribe
xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
</business-events>
</component>
While not explicitly demonstrated in this example, you can define XPath filters on
events. In Example 413, the event is accepted for delivery only if the initial deposit is
greater than 50000:
41-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 413
<business-events>
. . .
. . .
<filter>
<xpath xmlns:be="http://oracle.com/fabric/businessEvent"
xmlns:ns1="http://xmlns.oracle.com/singleString"
<xpath expression= "/be:business-event/be:content/
sub1:AccountInfo/Details[@initialDeposit > 50000]" />
</filter>
. . .
. . .
</business-events>
41.3.3 What You May Need to Know About Subscribing to a Business Event
Subscribers in nondefault revisions of SOA composite applications can still get
business events. For example, note the following behavior:
To subscribe to a business event:
1. Create a composite application with an initial Oracle Mediator service component
named M1 that publishes an event and a second Oracle Mediator service
component named M2 that subscribes to the event. The output is written to a
directory.
2.
3.
4.
5.
3.
4.
5.
6.
In the Domain Structure section, expand Services > Foreign JNDI Providers.
3.
4.
Click New.
5.
In the Name field, enter a name (for example, SOA_JNDI), and click Next.
6.
7.
In the Name column, click the provider name you entered in Step 5.
8.
Table 412
Configuration Details
Field
Description
Enter weblogic.jndi.WLInitialContextFactory.
Provider URL
Enter t3://hostname:soa_server_port.
User
Enter the password for the Oracle WebLogic Server user name.
9.
10. Enter the details shown in Table 413, and click OK.
Table 413
Configuration Details
Field
Description
Name
Enter SOA_EDNDataSource.
Local Name
Enter jdbc/EDNDataSource.
Remote Name
Enter jdbc/EDNDataSource.
Configuration Details
Field
Description
Name
Enter SOA_EDNLocalTxDataSource.
Local Name
Enter jdbc/EDNLocalTxDataSource.
Remote Name
Enter jdbc/EDNLocalTxDataSource.
41-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Select the following EDN-DB JNDI data sources, and click Remove.
jdbc/EDNDataSource
jdbc/EDNLocalTxDataSource
In the Domain Structure section, expand Services > Foreign JNDI Providers.
5.
Click New.
6.
In the Name field, enter a name for the foreign JNDI provider.
7.
Select targets for the new JNDI provider, and click Finish.
8.
9.
Specify provider settings (the initial context factory, provider URL, and so on),
and click Save.
jms/fabric/EDNConnectionFactory.
13. Repeat Step 12, and specify a name and the local and remote JNDI name of
jms/fabric/xaEDNConnectionFactory.
14. Repeat Step 12, and specify a name and the local and remote JNDI name of
jms/fabric/EDNQueue.
41-11
If you do not make these configuration changes, errors similar to those shown in
Example 414 occur.
Example 414
<component name="PublishOrderPendingEvent">
<implementation.mediator src="PublishOrderPendingEvent.mplan"/>
<business-events>
<publishes
xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
name="pub1:NewOrderSubmitted"/>
</business-events>
</component>
<component name="OrderPendingEvent">
<implementation.mediator src="OrderPendingEvent.mplan"/>
<business-events>
<subscribe
xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
</business-events>
</component>
41-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In the Name field, enter a name. Do not change any other default option and click
OK.
The BPEL process service component is created.
3.
4.
Drag a Receive activity from the Component Palette into the SOA Composite
Editor, below the receiveInput activity.
The onMessage branch of a pick activity can also be set up to
receive events from the EDN. For more information about the
onMessage branch, see Section 15.2, "Creating a Pick Activity to Select
Between Continuing a Process or Waiting."
Note:
5.
Double-click the Receive activity. The Receive dialog opens. Alternatively, you
can also right-click the Receive activity and click Edit.
6.
7.
From the Interaction Type list, select Event. The layout of the Receive dialog
changes.
8.
Click the Browse Events icon to the right of the Event field. The Subscribed Events
dialog appears, as shown in Figure 417.
9.
41-13
guaranteed
Events are delivered to the subscriber asynchronously without a global
transaction. The subscriber can choose to create its own local transaction for
processing, but it is committed independently of the rest of event processing.
This option incurs a lower cost than the one and only one option because
there is only the trip to one queue (the main event queue). In addition, EDN
does not attempt to resend an event (regardless of the backing store being AQ
or JMS). If one or more subscribers fail to consume the event (while others
succeed), those subscribers lose the message. In this respect, guaranteed
delivery actually means best effort delivery; that is, it is not guaranteed that
each subscriber definitely consumes the message.
immediate
Events are delivered to the subscriber in the same global transaction and same
thread as the publisher. The publish call does not return until all immediate
subscribers have completed processing. If any subscribers throw an exception,
no additional subscribers are invoked and an exception is thrown to the
publisher. The transaction is rolled back in case of any error during immediate
processing.
12. If you want to filter the event, double-click the Filter column of the selected event
or select the event and click the filter icon (first icon) above the table. This displays
the Expression Builder dialog. This dialog enables you to specify an XPath filter
expression. A filter expression specifies that the contents (payload or headers) of a
message be analyzed before any service is invoked. For example, you can apply a
filter expression that specifies that a service be invoked only if the order includes
an order ID.
When the expression logic is satisfied, the event is accepted for delivery.
41-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
13. Click OK to close the Subscribed Events dialog. You are returned to the Receive
dialog.
Note: Optionally, you can select the Create Instance checkbox, if this
receive activity is the initiating receive activity that starts the BPEL
process service component instance. This action enables creation of a
new BPEL process service component instance for every invocation.
Figure 419 shows a BPEL process service component that is configured for event
subscription.
Figure 419 BPEL Process Service Component Configuration for Event Subscription
Double-click the Invoke activity. The Invoke dialog opens. Alternatively, you can
also right-click the Invoke activity and click Edit.
3.
4.
From Interaction Type list, select Event. The layout of the Invoke dialog changes.
5.
To the right of the Event field, click the Browse Events icon. The Event Chooser
dialog appears.
6.
7.
Click OK.
Figure 4110 shows a BPEL process service component that is configured for an
event subscription and publication. The blue lightning bolt in the circle on the left
side indicates event subscription. The yellow lightning bolt in the circle on the
right side indicates event publication. Clicking the blue arrow inside the title
changes it to display the title of the published event.
41-15
Figure 4110 BPEL Process Service Component Configuration for Event Subscription
and Publishing
41.4.3 What Happens When You Subscribe to and Publish a Business Event
The source code in Example 416 shows how the composite.xml source changes for
the subscribed and published events of a BPEL process service component.
Example 416
<component name="EventBPELProcess">
<implementation.bpel src="EventBPELProcess.bpel"/>
<property name="configuration.monitorLocation" type="xs:string"
many="false">EventBPELProcess.monitor</property>
<business-events>
<subscribe xmlns:sub1="http://mycompany.com/events/orders"
name="sub1:OrderReceivedEvent" consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
<publishes xmlns:pub1="http://mycompany.com/events/orders"
name="pub1:ProductSoldAlert"/>
</business-events>
</component>
While not explicitly demonstrated in this example, you can define XPath filters on
events. A filter is typically present in event subscriptions. The subscribe element
limits the type of event to which this service component is subscribed, and the filter
section further limits the event to specific content in which the component is
interested. In Example 417, the event is accepted for delivery only if the initial deposit
is greater than 50000.
Example 417
<business-events>
. . .
. . .
<filter>
<xpath xmlns:be="http://oracle.com/fabric/businessEvent"
xmlns:ns1="http://xmlns.oracle.com/singleString"
<xpath expression= "/be:business-event/be:content/
sub1:AccountInfo/Details[@initialDeposit > 50000]" />
</filter>
. . .
. . .
</business-events>
The standard BPEL activities such as receive, invoke, onMessage, and onEvent (in
BPEL 2.0) are extended with an extra attribute bpelx:eventName, so that the BPEL
process service component can receive events from the EDN event bus. The schema
for the eventName attribute is shown in Example 418:
41-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 418
Example 419 shows how the eventName attribute is used in the BPEL source file:
Example 419
The schema definition for the invoke and onMessage activities are modified similarly.
41-17
How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator
41.4.4 What You May Need to Know About Subscribing to a Business Event
Subscribers in nondefault revisions of SOA composite applications can still get
business events. For example, note the following behavior:
To subscribe to a business event:
1. Create a composite application with an initial Oracle Mediator service component
or BPEL process service component named S1 that publishes an event and a
second Oracle Mediator service component or BPEL process service component
named S2 that subscribes to the event. The output is written to a directory.
2.
3.
4.
5.
Service component S2 writes the output to two files with the same content in the
directory. As expected, service component S3 picks up the event and writes the output
successfully to another directory. However, service component S2 (from revision 1)
also picks up and processes the published event from revision 2 of the composite
application. Therefore, it creates one more output file in the same directory.
Add a business event definition to the project. This action generates an EDL file
and an XSD file. The XSD file contains the definition of the payload. Ensure also
that you specify that the event be raised by the Oracle ADF Business Component
upon creation.
For more information about creating and publishing Oracle ADF Business
Component business events, see Oracle Fusion Middleware Fusion Developer's Guide
for Oracle Application Development Framework.
3.
Create a SOA composite application and manually copy the EDL and XSD schema
files to the root directory of the SOA project. For example:
JDeveloper/mywork/SOA_application_name/SOA_project_name
4.
Place schema files at the proper relative location from the EDL file based on the
import.
5.
6.
In the Event Chooser window, select the EDL file of the event, as described in
Section 41.3.1, "How to Subscribe to a Business Event."
41-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator
7.
Create a BPEL process service component in the same SOA composite application
for Oracle Mediator to invoke. In the Input Element field of the Advanced tab,
ensure that you select the payload of the Business Component business event XSD
created in Step 2.
8.
9.
10. Use the payload of the business event XSD to complete the Subject and Body
fields.
11. Return to the Oracle Mediator service component in the SOA Composite Editor.
12. Design a second service component to publish the event, such as a BPEL process
41-19
How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator
41-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part VIII
Part VIII
42
Enabling Security with Policies
42
This chapter describes how to attach policies to binding components and service
components during design-time in SOA composite applications. Policies apply
security to the delivery of messages. This chapter also describes how to override policy
configuration property values.
This chapter includes the following sections:
Category
Description
Message Transmission
Optimization
Mechanism (MTOM)
Reliability
Addressing
Security
Management
Within each category there are one or more policy types that you can attach. For
example, if you select the reliability category, the following types are available for
selection:
oracle/wsrm10_policy
Supports version 1.0 of the Web Services Reliable Messaging protocol
oracle/wsrm11_policy
Supports version 1.1 of the Web Services Reliable Messaging protocol
oracle/no_wsrm_policy
Supports the disabling of a globally attached Web Services Reliable Messaging
policy
For more information about available policies, details about which ones to use in your
environment, and global policies, see Oracle Fusion Middleware Security and
Administrator's Guide for Web Services.
3.
For Request:
42-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Select the request binding for the service component with which to bind. You
can only select a single request binding. This action enables communication
between the binding component and the service component.
When request binding is configured for a service in the Exposed Services
swimlane, the service acts as the server. When request binding is configured
for a reference in the External References swimlane, the reference acts as the
client.
The Configure SOA WS Policies dialog shown in Figure 421 appears. For this
example, the For Request option was selected for a service binding component.
The same types of policy categories are also available if you select For Callback.
Figure 421 Configure SOA WS Policies Dialog
4.
MTOM
Reliability
Addressing
Security
Management
For this example, Security is selected. The dialog shown in Figure 422 is
displayed.
Figure 422 Security Policies
5.
Place your cursor over a policy name to display a description of policy capabilities.
6.
7.
Click OK.
You are returned to the Configure SOA WS Policies dialog shown in Figure 423.
The attached security policy displays in the Security section.
42-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.
9.
3.
Security
Management
5.
Click OK.
6.
7.
For information about attaching policies during runtime in Oracle Enterprise Manager
Fusion Middleware Control, see Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
42-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
Click the Edit icon. Regardless of which policies you select, the property names,
values, and overridden values display for all of your attached client policies.
4.
In the Override Value column, enter a value to override the default value shown
in the Value column. Figure 426 provides details.
5.
6.
7.
<wsp:PolicyReference URI="oracle/wss_saml_token_over_ssl_client_policy"
orawsp:category="security"
orawsp:status="enabled"/>
<wsp:PolicyReference URI="oracle/log_policy"
orawsp:category="management"
orawsp:status="enabled"/>
<property name="user.roles.include" type="xs:string"
many="false">true</property>
</binding.ws>
For more information about overriding policy settings, see Oracle Fusion Middleware
Security and Administrator's Guide for Web Services.
2.
3.
Select an attached policy that permits you to override its value, and click the Edit
icon.
4.
In the Override Value column, enter a value to override the default value shown
in the Value column. Figure 428 provides details. If the policy store is
unavailable, the words no property store found in the store display in red
in the Value column.
42-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
6.
7.
For more information about overriding policy settings, see Oracle Fusion
Middleware Security and Administrator's Guide for Web Services.
42-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
43
43
Section 43.6, "Customizing Your Application for the Target Environment Before
Deployment"
See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite for instructions about deploying SOA composite
applications from Oracle Enterprise Manager Fusion Middleware Control and Oracle
Fusion Middleware WebLogic Scripting Tool Command Reference for instructions about
deploying SOA composite applications with the WLST utility.
Deployment prerequisites
Packaging details
Anatomy of a composite
Deployment Prerequisites
Composite deployment
For more information about the deployment life cycle, see Oracle Fusion Middleware
Administrator's Guide.
Oracle JDeveloper
During deployment on the Deployment Action page, you select the Deploy to
SAR option. For more information, see Section 43.7.1.3, "Deploying the Profile."
ant scripts
Use the ant-sca-package script to package your artifacts. For more
information, see Section 43.7.6.3, "How to Use ant to Package a SOA Composite
Application into a Composite SAR File."
WLST commands
43-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Use the sca_package script to package your artifacts. For more information, see
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
A SAR file is a special JAR file that requires a prefix of sca_ (for example, sca_
HelloWorld_rev1.0.jar).
In addition, when you deploy a SOA composite application with the Deploy to
Application Server option on the Deployment Action page in Oracle JDeveloper, all
required artifact files within a project are automatically packaged into one of the
following files:
A ZIP file of multiple SOA composite applications that share metadata with one
another
You can deploy and use shared data across SOA composite applications. Shared
data is deployed to the SOA Infrastructure on the application server as an Oracle
Metadata Services (MDS) Repository archive JAR file. The archive file contains all
shared resources. For more information, see Section 43.7.3, "How to Deploy and
Use Shared Data Across Multiple SOA Composite Applications in Oracle
JDeveloper."
messages or dequeue incoming messages. The Oracle JCA adapters listed in Table 431
require JDBC data sources and queues to be configured before deployment.
Table 431
Adapter
Database adapter
AQ adapter
JMS adapter
Queue
43.5.1.1 Script for Creation of JMS Resource and Redeployment of JMS Adapter
Example 431 provides a script for creating the JMS resource and redeploying the JMS
adapter.
This script is for demonstration purposes. You may need to
modify this script based on your environment.
Note:
Example 431
43-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
except:
print "Error while modifying jms adapter connection factory"
43.5.1.2 Script for Creation of the Database Resource and Redeployment of the
Database Adapter
Example 432 provides a script for creating the database resource and redeploying the
database adapter.
This script is for demonstration purposes. You may need to
modify this script based on your environment.
Note:
Example 432 Script for Creation of the Database Resource and Redeployment of the
Database Adapter
import os
connect(userName,passWord,'t3://'+wlsHost+':'+adminServerListenPort)
edit()
startEdit()
soaJDBCSystemResource1 = create('DBAdapterTestDataSource',"JDBCSystemResource")
soaJDBCResource1 = soaJDBCSystemResource1.getJDBCResource()
soaJDBCResource1.setName('DBAdapterDataSource')
soaConnectionPoolParams1 = soaJDBCResource1.getJDBCConnectionPoolParams()
soaConnectionPoolParams1.setTestTableName("SQL SELECT 1 FROM DUAL")
soaConnectionPoolParams1.setInitialCapacity(10)
soaConnectionPoolParams1.setMaxCapacity(100)
soaDataSourceParams1 = soaJDBCResource1.getJDBCDataSourceParams()
soaDataSourceParams1.addJNDIName('jdbc/dbSample')
soaDriverParams1 = soaJDBCResource1.getJDBCDriverParams()
soaDriverParams1.setUrl('jdbc:oracle:thin:@'+db_host_name+':'+db_port+':'+db_sid)
soaDriverParams1.setDriverName('oracle.jdbc.xa.client.OracleXADataSource')
soaDriverParams1.setPassword('my_password')
soaDriverProperties1 = soaDriverParams1.getProperties()
soaProperty1 = soaDriverProperties1.createProperty("user")
soaProperty1.setValue('scott')
varSOAServerTarget = '/Servers/'+serverName
soaServerTarget = getMBean(varSOAServerTarget)
soaJDBCSystemResource1.addTarget(soaServerTarget)
dumpStack()
try :
save()
activate(block="true")
except:
print "Error while trying to save and/or activate!!!"
dumpStack()
The ra.xml file, which is the deployment descriptor XML file containing
deployment-specific information about the resource adapter
Declarative information about the contract between Oracle WebLogic Server and
the resource adapter
Adapters also package the weblogic-ra.xml template file, which defines the
endpoints for connection factories.
For information about creating connection factories and connection pools, see Oracle
Fusion Middleware User's Guide for Technology Adapters.
For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
43.5.7.1 What You May Need to Know About Opening the composite.xml File
Through a SOA-MDS Connection
If you create a SOA-MDS connection in Oracle JDeveloper, expand the connection, and
attempt to open the composite.xml file of a composite from the Resource Palette, the
file may not load correctly. Only open a composite from the Application Navigator.
For information about the Oracle MDS Repository, see Oracle Fusion Middleware
Administrator's Guide.
43-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
43.6.1 How to Use Configuration Plans to Customize SOA Composite Applications for
the Target Environment
As you move projects from one environment to another (for example, from testing to
production), you typically must modify several environment-specific values, such as
JDBC connection strings, hostnames of various servers, and so on. Configuration plans
enable you to modify these values using a single text (XML) file. The configuration
plan is created in either Oracle JDeveloper or with WLST commands. During process
deployment, the configuration plan searches the SOA project for values that must be
replaced to adapt the project to the next target environment.
You create and edit a configuration plan file in which you can replace the
following attributes and properties:
Attribute values for bindings (for example, the location for binding.ws)
Service component
Note: The configuration plan does not alter XSLT artifacts in the
SOA composite application. To modify any XSL, use the XSLT
Mapper. Using a configuration plan is not useful. For example, you
cannot change references in XSL using the configuration plan file.
Instead, they must be changed manually in the XSLT Mapper in
Oracle JDeveloper when moving to and from test, development, and
production environments. This ensures that the XSLT Mapper opens
without any issues in design time. However, leaving the references
unchanged does not impact runtime behavior. For more information
about transformations and the XSLT Mapper, see Chapter 43,
"Deploying SOA Composite Applications."
You attach the configuration plan file to a SOA composite application JAR file or
ZIP file (if deploying a SOA bundle) during deployment with one of the following
tools:
Oracle JDeveloper
For more information, see Section 43.7.1.3, "Deploying the Profile."
ant scripts
For more information, see Section 43.7.6.4, "How to Use ant to Deploy a SOA
Composite Application."
WLST commands
For more information, see Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.
composite.xml File
<composite .....>
<import namespace="http://example.com/hr/"
location="http://myserver17.us.example.com:8888/hrapp/HRAppService?WSDL"
importType="wsdl"/>
<service name="readPO">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/readPO/#wsdl.interface(Read
_ptt)"/>
<binding.jca config="readPO_file.jca"/>
<property name="inFileFolder" type="xs:string" many="false"
override="may">/tmp/inFile</property>
</service>
<reference name="HRApp">
<interface.wsdl
interface="http://example.com/hr/#wsdl.interface(HRAppService)"/>
<binding.ws
port="http://example.com/hr/#wsdl.endpoint(HRAppService/HRAppServiceSoapHttpPort)"
location="http://myserver17.us.example.com:8888/hrapp/HRAppService?WSDL"/>
<binding.java serviceName="{http://example.com/hr/}HRAppService"
registryName="HRAppCodeGen_JBOServiceRegistry"/>
</reference>
</composite>
<binding type="*">
<property name="inFileFolder">
<replace>/mytestserver/newinFileFolder</replace>
</property>
</binding>
</service>
</composite>
<!-- For all composite replace host and port in all imports wsdls -->
<composite name="*">
<import>
<searchReplace>
<search>myserver17</search>
<replace>test-server</replace>
</searchReplace>
<searchReplace>
<search>8888</search>
<replace>8198</replace>
</searchReplace>
</import>
<reference name="*">
<binding type="ws">
<attribute name="location">
<searchReplace>
<search>myserver17</search>
<replace>test-server</replace>
</searchReplace>
<searchReplace>
<search>8888</search>
<replace>8198</replace>
</searchReplace>
</attribute>
</binding>
</reference>
</composite>
</SOAConfigPlan>
A policy is replaced if a policy for the same URI is available. Otherwise, it is added.
This is different from properties, which are modified, but not added.
2.
User A deploys Foo to a development server, fixes bugs, and refines the process
until it is ready to test in the staging area.
3.
User A creates and edits a configuration plan for Foo, which enables the URLs and
properties in the application to be modified to match the testing environment.
4.
User A deploys Foo to the testing server using Oracle JDeveloper or a series of
command-line scripts (can be WLST-based). The configuration plan created in
Step 3 modifies the URLs and properties in Foo.
5.
User A deploys SOA composite application Bar in the future and applies the same
plan during deployment. The URLs and properties are also modified.
The following steps provide an overview of how to use a configuration plan when
creating environment-independent processes:
43-11
This use case is useful for users that have their own
development server and a common development and testing server if
they share development of the same process. Users that share the
same deployment environment (that is, the same development server)
may not find this use case as useful.
Note:
1.
2.
User A deploys Foo to their development server, fixes bugs, and refines the
process until it is ready to test in the staging area.
3.
User A creates a configuration plan for Foo, which enables the URLs and
properties in the process to be modified to match the settings for User A's
environment.
4.
User A checks in Foo and the configuration plan created in Step 3 to a source
control system.
5.
6.
User B makes a copy of the configuration plan to match their environment and
applies the new configuration plan onto Foo's artifacts.
7.
User B imports the application into Oracle JDeveloper and makes several changes.
8.
User B checks in both Foo and configuration plan B (which matches user B's
environment).
9.
User A checks out Foo again, along with both configuration plans.
Deploying the SOA composite application JAR or ZIP file in which the
configuration plan is included
43-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Table 432
Field
Description
Specify the file name (.xml) Enter a specific name or accept the default name for the
for the configuration plan
configuration plan. The file is created in the directory of the
project and packaged with the SOA composite application JAR
or ZIP file.
Note: During deployment, you can specify a different
configuration file when prompted in the Deploy Configuration
page of the deployment wizard. For more information, see
Section 43.7.1.3, "Deploying the Profile."
Overwrite existing file
43-13
4.
Click OK.
This creates and opens a single configuration plan file for editing, similar to that
shown in Example 434. You can modify URLs and properties for the
composite.xml, WSDL, and schema files of the SOA composite application.
Figure 433 provides details.
5.
Add values for server names, port numbers, and so on to the existing syntax. You
can also add replacement-only syntax when providing a new value. You can add
multiple search and replacement commands in each section.
6.
7.
Above the editor, click the x to the right of the file name to close the configuration
plan file.
8.
43-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
Select the configuration plan to validate. This step identifies all search and
replacement changes to be made during deployment. Use this option for
debugging only.
10. Note the directory in which a report describing validation results is created, and
click OK.
The Log window in Oracle JDeveloper indicates if validation succeeded and lists
all search and replacement commands to perform during SOA composite
application deployment. This information is also written to the validation report.
The old composite.xml, WSDL, and XSD files are not
replaced with files containing the new values for the URLs and
properties appropriate to the next environment. Replacement occurs
only when the SOA composite application is deployed.
Note:
11. Deploy the SOA composite application by following the instructions in one of the
following sections:
43-15
Attach the configuration plan file to the SOA composite application JAR file:
sca_attachPlan(sar, configPlan, overwrite, verbose)
Extract a configuration plan packaged with the JAR file for editing:
sca_extractPlan(sar, configPlan, overwrite, verbose)
For information about using these commands, see Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
43-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
application servers such as IBM WebSphere Server, see Oracle Fusion Middleware
Third-Party Application Server Guide.
To create an application server connection:
1. From the File main menu, select New.
2.
3.
4.
5.
In the Connection Type list, select WebLogic 10.3 to create a connection to Oracle
WebLogic Server.
6.
Click Next.
The Authentication page appears.
7.
In the Username field, enter the user authorized for access to the application
server.
8.
9.
Click Next.
The Configuration page appears.
10. In the Weblogic Hostname (Administration Server) field, enter the host on which
default values.
12. If you want to use secure socket layer (SSL), select the Always use SSL checkbox.
Table 433 describes what occurs when you select this checkbox.
Table 433
An HTTPS server URL must exist to deploy the composite with SSL.
Otherwise, deployment fails.
If the server has only an HTTP URL, deployment also fails. This option
enables you to ensure that SSL deployment must not go through a
non-SSL HTTP URL, and must only go through an HTTPS URL.
Not selected
13. In the WebLogic Domain field, enter the Oracle SOA Suite domain. For additional
43-17
16. If the connection is successful, click Finish. Otherwise, click Back to make
3.
Click Deployment.
4.
Click New.
The Create Deployment Profile dialog appears.
5.
Table 434
Field
Description
Archive Type
Name
6.
Click OK.
The SAR Deployment Profile dialog appears.
7.
43-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
43-19
3.
Deploy to SAR
Creates a SAR (JAR) file of the selected SOA project, but does not deploy it to
an application server such as Oracle WebLogic Server. This option is useful for
environments in which:
Oracle WebLogic Server may not be running, but you want to create the
artifact JAR file.
You want to deploy multiple JAR files to Oracle WebLogic Server from a
batch script. This option offers an alternative to opening all project profiles
(which you may not have) and deploying them from Oracle JDeveloper.
Table 435
Deployment Target
If You Select...
Go to...
Step 4a
Deploy to SAR
Step 4b
a.
43-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
b.
43-21
5.
Table 436
Field
Description
Composite Revision ID
Project
Current Revision ID
New Revision ID
Do not attach
Configuration_
plan.xml
BPEL Monitor
43-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Deselect this checkbox to display BPEL Monitor deployment
errors. This checkbox corresponds to the ignoreErrors
property in the monitor.config BPEL project file. This file
defines runtime and deployment properties needed to connect
with Oracle BAM Server to create the Oracle BAM data objects
and dashboards.
If Oracle BAM Server is unreachable, and ignoreErrors is set
to true, deployment of the composite does not stop. If set to
false and Oracle BAM Server is unavailable, deployment fails.
Mark composite revision as If you do not want the new revision to be the default, you can
default
deselect this box. By default, a newly deployed composite
revision is the default. This revision is instantiated when a new
request comes in.
The option only displays if you selected Deploy to Application
Server on the Deployment Action page.
Overwrite any existing
composites with the same
revision ID
Click Next.
43-23
7.
If the SOA project you selected for deployment includes a task flow project
defined for a human task, you are prompted with the Task Flow Deployment
dialog, as shown in Figure 439.
Otherwise, go to Step 10.
You create or configure an Enterprise Resource Archive (EAR) file for the task
flow forms of human tasks. The EAR file consists of a Web Resource Archive
(WAR) profile that you select in the Deployable Taskflow Projects table of this
dialog.
8.
Table 437
Field
Description
Application Name
Deploy to specific
composite revision &
partition
43-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Overwrite Existing
Application
Deployable Taskflow
Projects
Select the task flow project WAR profiles to include in the EAR
file. The task flow project WAR profiles are grouped in
accordance with the composites that include the human task
related to the task flow project. The context root of the WAR
changes if the Add generated profiles to application checkbox
is selected.
Note: If you do not select a WAR profile, no task flows are
deployed.
Projects
Select from the list of deployable task flow projects or select the
Projects checkbox to choose all available task flows. The task
flows that display are based on the composites included in the
SOA project or bundle selected for deployment.
WAR Profiles
Select the task flow project WAR files. Only the most recently
created or modified task flow of the human task is available for
selection.
When you deploy a task form for a human task, as part of notification, the task
form details are included in an email. For dynamic payloads, this email includes
the content of the payload as it appears at that particular time.
For information about deploying SOA composite applications with task flows to
multiple partition environments, see Section 43.7.1.4, "What You May Need to
Know About Deploying Human Task Composites with Task Flows to Partitions."
9.
Click Next.
10. If you selected to deploy to an application server in Step 3, the Select Server page
43-25
partitions, you cannot deploy this archive. Also, if the server is not in a running
state, you cannot deploy this archive. By default, a partition named default is
automatically included with Oracle SOA Suite. You create partitions in the
Manage Partitions page of Oracle Enterprise Manager Fusion Middleware
Control.
Human workflow artifacts such as task mapped attributes
(previously known as flex field mappings) and rules (such as vacation
rules) are defined based on the namespace of the task definition.
Therefore, the following issues are true when the same SOA
composite application with a human workflow task is deployed into
multiple partitions:
Note:
43-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4311
Finish.
Figure 4312
Summary Page
43-27
16. If you selected to deploy to an application server in Step 3, view the messages that
A JAR file for the SOA project is created under the deploy folder in Oracle
JDeveloper with a naming convention of sca_composite_name_revrevision_
number.jar.
The project is displayed in the Resource Palette under application_server_
connection_name > SOA > SOA_server_name > partition_name.
The project is displayed in the Application Server Navigator under
application_server_connection_name > SOA > SOA_server_name >
partition_name.
You are now ready to monitor your application from Oracle Enterprise Manager
Fusion Middleware Control. See Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for details.
If deployment is unsuccessful, view the messages that display in the Deployment
log window and take corrective actions. For more information, see Section 43.9,
"Testing and Troubleshooting."
For information about creating partitions, see the following documentation:
Note:
43.7.1.4 What You May Need to Know About Deploying Human Task Composites
with Task Flows to Partitions
To deploy a SOA composite application with a task flow from Oracle JDeveloper to a
multiple partition environment, select the task flows to be deployed to the same
partition in which the SOA composite application is being deployed.
When the task flow is deployed using only the EAR profile (deploying the task flow
using the EAR deployer), the task flow is not partition-aware. Therefore, you must
modify the hwtaskflow.xml file to include the partition name in the generated EAR
file (the project version of the file remains unchanged). This file is located under the
TaskForm project adfmsrc directory (for example,
HelpDeskRequestTaskFlow\adfmsrc\hwtaskflow.xml). Example 435
provides details.
Example 435
<hwTaskFlows
xmlns="http://xmlns.oracle.com/bpel/workflow/hwTaskFlowProperties">
43-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<ApplicationName>worklist</ApplicationName>
<LookupType>LOCAL</LookupType>
<TaskFlowDeploy>false</TaskFlowDeploy>
<PartitionName>partition2</PartitionName>
In addition, if you want to reuse the same task flow project for another partition, you
must change the web context-root.
Application Properties
2.
3.
Click New.
The Create Deployment Profile dialog appears.
4.
5.
43-29
6.
Click OK.
7.
8.
Select the SARs you want to include in this bundle, as shown in Figure 4315.
9.
Click OK.
43-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
43.7.3 How to Deploy and Use Shared Data Across Multiple SOA Composite
Applications in Oracle JDeveloper
This section describes how to deploy and use shared data such as WSDLs, XSDs, and
other file types across multiple SOA composite applications.
Shared data is deployed to the SOA Infrastructure on the application server as a JAR
file. The JAR file should contain all the resources to share. In Oracle JDeveloper, you
can create a JAR profile for creating a shared artifacts archive.
All shared data is deployed to an existing SOA Infrastructure partition on the server.
This data is deployed under the /apps namespace. For example, if you have a
MyProject/xsd/MySchema.xsd file in the JAR file, then this file is deployed under
the /apps namespace on the server. When you refer to this artifact in Oracle
JDeveloper using a SOA-MDS connection, the URL becomes
oramds:/apps/MyProject/xsd/MySchema.xsd.
Notes:
3.
4.
Click New.
The Create Deployment Profile dialog appears.
5.
6.
In the Name field, enter a name (for this example, shared_archive is entered).
The Create Deployment Profile dialog looks as shown in Figure 4316.
43-31
7.
Click OK.
The JAR Deployment Profile Properties dialog appears.
8.
9.
43-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4317
10. Select File Groups > Project Output > Contributors from the navigational tree on
the left.
11. Deselect the Project Output Directory and Project Dependencies options, as
43-33
The Add Contributor dialog appears. This dialog enables you to add artifacts to
your archive.
13. Click Browse.
14. Select the folder in which your artifacts reside, as shown in Figure 4319. This
43-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
left.
18. Select only the artifacts to include in the archive, as shown in Figure 4320. For this
SOADemoComposite/xsd/DemoProcess.xsd
SOADemoComposite/xsd/Quote.xsd
SOADemoComposite/xsd/VacationRequest.xsd
Figure 4320
3.
From the Archive Type list, select SOA Bundle. A bundle is a collection of
multiple SOA composite applications.
43-35
4.
5.
Click OK.
6.
7.
Select the JAR file and SOA-SAR profiles you previously created (for this example,
named shared_archive and sharedArtifactBundle, respectively). You have the
option of a JAR, a SOA-SAR, or both. Figure 4322 provides details.
43-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4322
8.
9.
See Step 3 of Section 43.7.1.3, "Deploying the Profile" for details about responses to
provide.
This deploys the SOA bundle to the application server (shared artifacts are
deployed to the Oracle MDS Repository database of Oracle SOA Suite).
43-37
2.
Table 438
Field
Description
Connection Name
43-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Connection Type
DB Based MDS
For most production environments, you use a
database-based repository. Most components, such as
Oracle SOA Suite, require that a schema be installed in a
database, necessitating the use of a database-based
repository. To use a database-based repository, you must
first create it with the Repository Creation Utility.
Choose a database
connection
Test Connection
Status
3.
Click OK.
You can now browse the connection in the Resource Palette and view shared
artifacts under the /apps node.
43.7.3.4.2 Creating a BPEL Process You can now browse and use the shared data from a
different SOA composite application. For this example, you create a BPEL process
service component in a different application.
To create a BPEL process:
Create a new BPEL process service component in a different application.
1.
2.
In the Create BPEL Process dialog, click the Browse icon to the right of the Input
field.
The Type Chooser dialog appears.
3.
In the upper right corner, click the Import Schema File icon.
The Import Schema File dialog appears.
4.
5.
At the top of the dialog, select Resource Palette from the list.
6.
Select shared data, as shown in Figure 4324. For this example, the Quote.xsd file
that you selected to include in the archive in Step 18 of Section 43.7.3.1, "Create a
JAR Profile and Include the Artifacts to Share" is selected.
43-39
7.
Click OK.
8.
9.
In the Type Chooser dialog, select a node of Quote.xsd (for this example,
QuoteRequest), and click OK.
43-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Figure 4325
5.
Table 439
Field
Description
SOA Server
43-41
Table 439 (Cont.) Create Deployment Profile Dialog Fields and Values
Field
Description
Partition
Status
Server URL
Choose target SOA server(s) to which Select the Oracle WebLogic Administration Server to
you want to deploy this archive
which to deploy the archive.
SOA Archive
6.
Click OK.
For more information on deploying and testing SOA composite applications from the
Application Server Navigator, see Section 2.8, "Managing and Testing a SOA
Composite Application."
43.7.5 How to Manage SOA Composite Applications with the WLST Utility
You can manage SOA composite applications with the WLST utility. This utility is
well-suited for automation and can be easily integrated into existing release processes.
For instructions, see Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference.
43-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Script
Description
ant-sca-test.xml
ant-sca-compile.xml
ant-sca-package.xml
ant-sca-deploy.xml
ant-sca-deploy.xml
undeploy
ant-sca-deploy.xml
exportComposite
ant-sca-deploy.xml
exportUpdates
ant-sca-deploy.xml
importUpdates
ant-sca-deploy.xml
exportSharedData
ant-sca-deploy.xml
removeSharedData
ant-sca-mgmt.xml
startComposite
ant-sca-mgmt.xml
stopComposite
ant-sca-mgmt.xml
activateComposite
ant-sca-mgmt.xml
retireComposite
ant-sca-mgmt.xml
Assigns a default revision version.
assignDefaultComposit
e
ant-sca-mgmt.xml
Lists deployed SOA composite applications.
listDeployedComposite
s
ant-sca-mgmt.xml
listPartitions
ant-sca-mgmt.xml
Lists all composites in a partition.
listCompositesInParti
tion
ant-sca-mgmt.xml
createPartition
43-43
Table 4310
Script
Description
ant-sca-mgmt.xml
deletePartition
43.7.6.1 How to Use ant to Automate the Testing of a SOA Composite Application
Example 436 provides an example of executing a test case. Test cases enable you to
automate the testing of SOA composite applications.
Example 436
Testing an Application
43-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4311
Argument
Definition
scatest
java.passed.home
The script picks this from the environment value of JAVA_HOME.
Provide this input to override.
wl_home
This is the location of Oracle WebLogic Server home (defaults to
Oracle_Home/.../wlserver_10.3).
scatest.input
The name of the composite to test.
scatest.format
The format of the output file (defaults to native; the other option
is junit).
scatest.result
The result directory in which to place the output files (defaults to
temp_dir/out).
jndi.properties.input
The jndi.properties file to use.
jndi. properties
Absolute path to the JNDI property file. This is a property file that
contains JNDI properties for connecting to the server. For example:
java.naming.factory.initial=weblogic.jndi.WLInitialContextFac
tory
java.naming.provider.url=t3://myserver.us.example.com:8001/so
a-infra
java.naming.security.principal=weblogic
dedicated.connection=true
dedicated.rmicontext=true
Since a composite test (in a test suite) is executed on the SOA
Infrastructure, this properties file contains the connection information.
For this example, these properties create a connection to the SOA
Infrastructure hosted in myserver.us.example.com, port 8001 and
use a user name of weblogic. You are prompted to specify the
password.
You typically create one jndi.properties file (for example, in
/home/myhome/jndi.properties) and use it for all test runs.
For more information on creating and running tests on SOA composite applications,
see Chapter 44, "Automating Testing of SOA Composite Applications" and Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
Compiling an Application
ant -f ant-sca-compile.xml
-Dscac.input=/myApplication/myComposite/composite.xml
43-45
Table 4312
Argument
Definition
scac
java.passed.home
The script picks this from the environment value of JAVA_HOME.
Provide this input to override.
wl_home
This is the location of Oracle WebLogic Server home (defaults to
Oracle_Home/.../wlserver_10.3).
scac.input
The composite.xml file to compile.
scac.output
The output file with scac results (defaults to temp_
dir/out.xml).
scac.error
The file with scac errors (defaults to temp_dir/out.err).
scac.application.home
The Oracle JDeveloper application home directory of the SOA
composite application being compiled that contains the .adf
directory in it.
scac.displayLevel
Controls the level of logs written to scac.output file. The value
can be 1, 2, or 3 (this defaults to 1).
Packaging an Application
ant -f ant-sca-package.xml
-DcompositeDir=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POPr
ocessing
-DcompositeName=POProcessing
-Drevision=6-cmdline
-Dsca.application.home=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProces
sing
Argument
Definition
compositeDir
compositeName
revision
sca.application.ho
me
43-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4313
Argument
Definition
oracle.home
Deploying an Application
ant -f ant-sca-deploy.xml
-DserverURL=http://localhost:8001
-DsarLocation=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POPro
cessing\deploy\sca_POProcessing_rev6-cmdline.jar
-Doverwrite=true
-Duser=weblogic
-DforceDefault=true
-Dconfigplan=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POProc
essing\demed_cfgplan.xml
-Dscac.user.classpath=C:\jarfolder\custom.jar
-Dpartition=partition.name
Note:
Argument
Definition
serverURL
URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost10:8001).
sarLocation
overwrite
SAR file.
user
password
43-47
Table 4314
Argument
Definition
forceDefault
configplan
sysPropFile
Passes in a system properties file that is useful for setting extra system
properties, for debugging, for SSL configuration, and so on.
If you specify a file name (for example, tmp-sys.properties), you
can define properties such as the following:
javax.net.debug=all
scac.user.classp Optional. The name of the external custom library. If you have a SOA
ath
composite application with a BPEL process service component that
refers to a custom JAR file, set this property.
Optional. The name of the partition in which to deploy the SOA
composite application. The default value is default. If you do not
specify a partition, the composite is automatically deployed into the
default partition.
partition
Note:
Note:
43-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4315
Argument
Definition
serverURL
URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost10:7001).
compositeName
revision
user
password
partition
Note:
Argument
Definition
serverURL
The URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost:8001).
updateType
sarFile
compositeName
revision
user
Optional. The user name for accessing the server when basic
configuration is configured.
43-49
Table 4316
Argument
Definition
password
Example 4313 shows how to export a composite with all postdeployment changes.
Example 4313 Exporting a Composite With All Postdeployment Changes
ant -f ant-sca-deploy.xml exportComposite -DserverURL=http://myhost:8001
-DupdateType=all
-DsarFile=/tmp/sca_HelloWorld_rev1.0-all.jar -DcompositeName=HelloWorld
-Drevision=1.0
43-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Argument
Definition
serverURL
The URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost:8001).
updateType
jarFile
compositeName
revision
user
Optional. The user name for accessing the server when basic
configuration is configured.
password
43-51
Note:
Argument
Definition
serverURL
The URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost:8001).
jarFile
compositeName
The name of the composite into which the postdeployment changes are
imported.
revision
user
Optional. The user name for accessing the server when basic
configuration is configured.
password
43.7.6.9 How to Use ant to Export Shared Data of a Given Pattern into a JAR File
Example 4322 provides an example of exporting shared data of a given pattern into a
JAR file.
Example 4322 Exporting Shared Data of a Given Pattern into a JAR File
ant -f ant-sca-deploy.xml exportSharedData -DserverURL=server.url
-DjarFile=jar.file -Dpattern=pattern -Duser=user
Note:
43-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4319
Argument
Definition
serverURL
The URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost:8001).
jarFile
pattern
user
Optional. The user name for accessing the server when basic
configuration is configured.
password
Example 4323 shows how to export shared data of a given pattern into a JAR file.
Example 4323 Exporting Shared Data of a Given Pattern into a JAR File
ant -f ant-sca-deploy.xml exportSharedData -DserverURL=http://myhost:8001
-DjarFile=/tmp/MySharedData.jar
-Dpattern="/Project1/**"
Note:
Argument
Definition
serverURL
URL of the server that hosts the SOA Infrastructure application (for
example, http://myhost10:8001).
foldername
user
Optional. The user name for accessing the server when basic
configuration is configured.
password
Example 4325 shows how to remove a top-level shared data folder named
Project1.
43-53
Note:
Argument
Definition
host
port
user
password
compositeName
revision
label
partition
Note:
43-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4322
Argument
Definition
host
port
user
password
compositeName
revision
label
partition
Note:
Argument
Definition
host
port
user
password
compositeName
revision
label
partition
43-55
Note:
Argument
Definition
host
port
user
password
compositeName
revision
label
partition
43.7.6.15 How to Use ant to Assign the Default Version to a SOA Composite
Application
Example 4330 provides an example of assigning the default version to a SOA
composite application.
Example 4330 Assigning the Default Version to a SOA Composite Application
ant -f ant-sca-mgmt.xml assignDefaultComposite -Dhost=myhost -Dport=8001
-Duser=weblogic -DcompositeName=HelloWorld -Drevision=1.0
-Dpartition=partition.name
Note:
Argument
Definition
host
43-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4325
Argument
Definition
port
user
password
compositeName
revision
partition
43.7.6.16 How to Use ant to List the Deployed SOA Composite Applications
Example 4331 provides an example of listing the deployed SOA composite
applications.
Example 4331 Listing the Deployed SOA Composite Applications
ant -f ant-sca-mgmt.xml listDeployedComposites -Dhost=myhost -Dport=8001
-Duser=weblogic
Note:
Argument
Definition
host
port
user
password
43.7.6.17 How to Use ant to List All Available Partitions in the SOA Infrastructure
Example 4332 provides the syntax for listing all available partitions in the SOA
Infrastructure.
Example 4332 Listing All Available Partitions in the SOA Infrastructure
ant -f ant-sca-mgmt.xml listPartitions -Dhost=host -Dport=port -Duser=user
Note:
43-57
Table 4327
Argument
Definition
host
port
user
password
Example 4333 provides an example of listing all available partitions in the SOA
Infrastructure.
Example 4333 Listing All Available Partitions in the SOA Infrastructure
ant -f ant-sca-mgmt.xml listPartitions -Dhost=myhost10 -Dport=8001
Note:
Argument
Definition
host
port
user
password
partition
43-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Argument
Definition
host
port
user
password
partition
Note:
Argument
Definition
host
port
user
password
partition
43-59
Note:
Argument
Definition
host
port
user
password
partition
Example 4341 provides an example of starting all composites in the partition named
myPartition.
Example 4341 Starting All Composites in the Partition
ant -f ant-sca-mgmt.xml startCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition
Note:
43-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 4332
Argument
Definition
host
port
user
password
partition
Example 4343 provides an example of stopping all composites in the partition named
myPartition.
Example 4343 Stopping All Composites in the Partition
ant -f ant-sca-mgmt.xml stopCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition
Note:
Argument
Definition
host
port
user
password
partition
43-61
Note:
Argument
Definition
host
port
user
password
partition
Example 4347 provides an example of retiring all composites in the partition named
myPartition.
Example 4347 Retiring All Composites in the Partition
ant -f ant-sca-mgmt.xml retireCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition
build.properties
43-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Postdeployment Configuration
A file that you edit to reflect your environment (for example, specifying Oracle
home and Java home directories, setting server properties such as hostname and
port number to use for deployment, specifying the application to deploy, and so
on).
build.xml
Used by ant to compile, build, and deploy composite applications to the server
specified in the build.properties file.
1.
2.
43.7.7 How to Deploy SOA Composite Applications from Oracle Enterprise Manager
Fusion Middleware Control
You can deploy SOA composite applications from Oracle Enterprise Manager Fusion
Middleware Control. You must first create a deployable archive in Oracle JDeveloper
or through the ant or WLST command line tools. The archive can consist of a single
SOA composite application revision in a JAR file or multiple composite application
revisions (known as a SOA bundle) in a ZIP file. For more information, see Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
43.8.1 Security
For information about securing SOA composite applications, see Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
43-63
43-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
43-65
By reducing these two values, you increase the number of classes and methods
that are generated for the compiled process map. As a best practice, if the process
fails to compile using the default settings, set the property with smaller values.
The following values are good combinations to try:
32,16
16,8
8,4
4,2
4.
5.
6.
If you are deploying a single composite application, ensure that you are deploying
from the Project menu. Right-click the project name in the Application Navigator,
and select Deploy > SOA_profile_name.
If you are deploying multiple composite applications, ensure that you are
deploying from the Application menu. (Right-click the application name in the
Application Navigator, and select Deploy > SOA_bundle_profile_name).
Once you click Deploy and select the profile name, ensure that the Deployment
Action page of the deployment wizard is displayed.
Optionally enter a new revision ID (optional) and select the configuration plan (if
any).
If the composite application you are deploying is already located on the server
with the same revision ID, then check the Overwrite any existing composites
with the same revision ID checkbox in the Deploy Configuration page of the
deployment wizard. Without selecting this option, deployment fails.
If compilation fails, a compiler error occurred, and not a deployment error. You
only see this error when you compile your project.
If compiler messages are not obvious, check the compiler log. A link to this log file
(scac.log) is displayed in the Messages tab. The message looks similar to that
shown in Example 4350.
43-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For a SOA bundle archive, the message shown in Example 4352 is displayed in
the Deployment tab.
Example 4352 Archive Message
Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/SecondComposite/deploy/sca_
SecondComposite_rev1.0.jar
Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/FirstComposite/deploy/sca_
FirstComposite_rev1.0.jar
Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/deploy/soabundle1.zip
After this occurs, Oracle JDeveloper sends the archive binaries to the server. The
following message is displayed in the Deployment tab. At this point, Oracle
JDevelopers deployment role ends and the server (SOA Infrastructure) takes
control of deployment.
Deploying sca_FirstComposite_rev1.0.jar to myhost19:7001
Upon successful deployment, you see the message shown in Example 4353 in the
Deployment tab.
In most cases, the server provides some information about the error that occurred
on the server. If you do not receive any error message from the server, then check
soa_server1-diagnostic.log on the server to find additional information
(where soa_server1 is the name of the managed server). This file is located on
the server in domain_home/servers/soa_server1/logs.
43-67
If you selected a configuration plan to deploy, and it is not taking effect on the
server, open the SAR file containing the configuration plan. You can find the file
location from the Deployment tab in Oracle JDeveloper. Example 4355 provides
details.
Open the JAR file and ensure that it contains the soaconfigplan.xml file. This
file is generated during deployment based on the configuration plan you selected.
If this file is not present, try deploying the composite application again to ensure
that you have correctly selected the configuration plan in the Deploy
Configuration page of the deployment wizard.
The Oracle WebLogic Administration Server must be running. Deployment uses the
Oracle WebLogic Administration Server connection to identify the servers running
Oracle SOA Suite. In addition, do not create an application server connection to a
Managed Server; only create connections to an Oracle WebLogic Administration
Server.
You can also receive a similar error if the condition of the SOA-configured Oracle
WebLogic Server is not healthy. This condition displays in the Health column of the
Servers page of Oracle WebLogic Server Administration Console.
You can use WLST to deploy SOA composite applications to a managed Oracle
WebLogic Server without starting an Oracle WebLogic Administration Server. See
Section 43.7.5, "How to Manage SOA Composite Applications with the WLST Utility"
for details.
43-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4327
A valid proxy setting is necessary for accessing a SOA Infrastructure (for example,
soa_server1) outside the network. If the SOA Infrastructure is within the network,
perform one of the following actions:
To change the proxy setting:
1. From the Tools menu, select Preferences > Web Browser and Proxy.
2.
Perform one of the following tasks if the SOA server is within the network:
a.
Deselect Use HTTP Proxy Server if you can directly access the SOA
Infrastructure without any proxy.
b.
In the Exceptions field, enter the hostname of the unreachable SOA server.
43.9.6.6 Releasing Locks to Resolve ADF Task Form EAR File Deployment Errors
If you deploy a SOA composite application JAR file and ADF task form EAR file, and
the SOA JAR file is deployed successfully, but while deploying the EAR file, the
following errors are displayed:
[wldeploy] weblogic.management.ManagementException: [Deployer:149163]The
domain edit lock is owned by another session in non-exclusive mode - this
deployment operation requires exclusive access to the edit lock and hence
cannot proceed. If you are using "Automatically Aquire Lock and Activate
Changes" in the console, then the lock will expire shortly so retry this
operation.
This error means you must first release the lock from Oracle WebLogic Server
Administration Console to successfully deploy the EAR file.
To release locks to resolve ADF task form EAR file deployment errors:
1. Log in to the Oracle WebLogic Server Administration Console.
2.
Below the console banner at the top of the page, click Preferences > User
Preferences.
3.
4.
Click Save and note that buttons such as Lock and Edit and Release
Configuration are visible.
Note the following description that is displayed in the Oracle WebLogic Server
Administration Console:
Automatically acquire the lock that enables configuration editing and
automatically activate changes as the user modifies, adds and deletes items
(for example, when the user clicks the 'Save' button). This feature is not
available in production mode.
This error can occur regardless of the deployment method you are using (for example,
deploying through Oracle JDeveloper or through ant scripts).
43-69
Under the scac element, increase the memory setting. For example:
<jvmarg value="-Xmx512M"/>
43-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
44
44
44-1
Instead of invoking another service component or binding component, you can specify
a response from the component or reference.
For more information, see the following:
44-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Process Initiation
44.2.2 Emulations
You create emulations to simulate the message data that your SOA composite
application receives from web service partners.
In the test code in Example 442, the loan request is initiated with an error. A fault
message is received in return from a web service partner:
Example 442
Emulations
44-3
</initiate>
<wireActions wireSource="LoanBroker/CreditRatingService" operation="process">
<emulate duration="PT0S">
<fault faultName="ser:NegativeCredit" xmlns:ser="http://services.otn.com">
<message>
<part partName="payload">
<filePath>creditRatingFault.xml</filePath>
</part>
</message>
</fault>
</emulate>
</wireActions>
</compositeTest>
Fault Message
<error xmlns="http://services.otn.com">
Invalid SSN, SSN cannot start with digit '0'.
</error>
For more information, see Section 44.4, "Creating the Contents of Test Cases."
44.2.3 Assertions
You create assertions to validate an entire XML document, a part section of a message,
a nonleaf element, or a leaf element at a point during SOA composite application
execution. Example 444 instructs Oracle SOA Suite to ensure that the content of the
customerName variable matches the content specified.
Example 444
Assertions
<expected>
<location key="input" partName="payload"
xpath="/s1:loanApplication/s1:customerName"
xmlns:s1="http://www.autoloan.com/ns/autoloan"/>
<simple>Joe Smith</simple>
</expected>
</assert>
</wireActions>
</compositeTest>
For more information, see Section 44.4, "Creating the Contents of Test Cases."
For more information about loading message files into test mode, see Section 44.4,
"Creating the Contents of Test Cases."
3.
44-5
4.
In the Application Navigator, right-click the testsuites folder and select Create
Test Suite. Figure 442 provides details.
b.
In the Structure window, right-click Test Suites and select Create Test Suite.
Figure 443 provides details.
5.
6.
Click OK.
The Create Composite Test dialog appears.
7.
Enter a test name (for this example, NoErrorSanityTest of the Fusion Order
Demo is entered) and an optional description. This description displays in the
Description column of the Test Cases page of the Unit Tests tab in Oracle
Enterprise Manager Fusion Middleware Control.
8.
Click OK.
44-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
componenttests
This folder is not used in 11g Release 1.
includes
This folder is not used in 11g Release 1.
messages
Contains message test files that you load into this directory through the test
mode user interface.
tests
Contains NoErrorSanityTest.xml.
The following subdirectories for adding test files are created beneath
OrderBookingMainTestsuite: componenttests, includes, messages,
and tests.
44-7
9.
If you want to exit test mode and return to design mode in the SOA Composite
Editor, click the last icon below NoErrorSanityTest.xml above the designer.
Figure 445 provides details.
Notes:
Do not edit the filelist.xml files that display under the subfolders
of the testsuites folder. These files are automatically created
during design time, and are used during runtime to calculate the
number of test cases.
You cannot create test suites within other test suites. However,
you can organize a test suite into subdirectories.
The Fusion Order Demo provides examples of using test suites. For more
information about the Fusion Order Demo, see Chapter 3, "Introduction to the
SOA Sample Application."
44-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Double-click the service binding component shown in Figure 447 (for this
example, named initiate).
Table 441
Field
Value
Service
Operation
Part
Value
Enter Manually
Click the Browse icon to load message data from a file. The file
is added to the messages folder in the Application Navigator.
44-9
Click OK.
44-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
You can simulate a message returned from a synchronous web service partner.
1.
2.
Beneath the testsuites folder in the Application Navigator, double-click a test case.
Figure 449 provides details.
Double-click the wire of the SOA composite application area to test. For the
example shown in Figure 4410, the wire between the LoanBroker process and the
synchronous CreditRating web service is selected.
Figure 4410
Wire Access
This displays the Wire Actions dialog shown in Figure 4411, from which you can
design emulations and assertions for the selected part of the SOA composite
application.
44-11
4.
5.
6.
7.
Table 442
Field
Value
Part
Value
Enter Manually
Click the Browse icon to load message data from a file. The file
is added to the messages folder in the Application Navigator.
Duration
44-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4412
A simulated output message from a synchronous web service partner that you
enter manually or load from a file looks as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SCA Test Modeler version 1.0 at [7/3/07 3:26 PM]. -->
<compositeTest compositeDN="CompositeTest"
xmlns="http://xmlns.oracle.com/sca/2006/test">
<about></about>
<initiate serviceName="client" operation="initiate" isAsync="true">
<message>
<part partName="payload">
<filePath>loanApplication.xml</filePath>
</part>
</message>
</initiate>
<wireActions wireSource="LoanBroker/CreditRatingService" operation="process">
<emulate duration="PT0S">
<message>
<part partName="payload">
<filePath>creditRatingResult.xml</filePath>
</part>
</message>
</emulate>
</wireActions>
</compositeTest>
Click OK.
Automating Testing of SOA Composite Applications
44-13
Note:
You can simulate a callback message returned from an asynchronous web service
partner.
1.
2.
3.
4.
Click Emulate Callback. This field is only enabled for asynchronous processes.
5.
Table 443
Field
Value
Callback Operation
Callback Message
Part
Value
Enter Manually
Click the Browse icon to load message data from a file. The file
is added to the messages folder in the Application Navigator.
Duration
44-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4413
The simulated callback message from a web service partner looks as follows. You
enter this message manually or load it from a file:
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SCA Test Modeler version 1.0 at [7/3/07 3:27 PM]. -->
<compositeTest compositeDN="CompositeTest"
xmlns="http://xmlns.oracle.com/sca/2006/test">
<about></about>
<initiate serviceName="client" operation="initiate" isAsync="true">
<message>
<part partName="payload">
<filePath>loanApplication.xml</filePath>
</part>
</message>
</initiate>
<wireActions wireSource="LoanBroker/LoanService" operation="initiate">
<emulate callbackOperation="onResult" duration="PT0S">
<message>
<part partName="payload">
<filePath>loanOffer.xml</filePath>
</part>
</message>
</emulate>
</wireActions>
</compositeTest>
44-15
<approved>true</approved>
<APR>1.9</APR>
</loanOffer>
6.
Click OK.
2.
3.
4.
5.
Table 444
Field
Value
Fault
Fault Message
Part
Value
Enter Manually
Click the Browse icon to load message data from a file. The file
is added to the messages folder in the Application Navigator.
Duration
Enter the maximum amount of time to wait for the fault message
to be delivered from the web service partner.
44-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4414
An example of a simulated fault message from a web service partner that you
enter manually or load from a file is shown in Section 44.2.2, "Emulations."
6.
Click OK.
2.
Figure 4415
44-17
3.
4.
Select the type of assertion to perform at the top of the dialog, as shown in
Table 445. If the operation supports only input messages, the Assert Input button
is enabled. If the operation supports both input and output messages, the Assert
Input and Assert Output buttons are both enabled.
Table 445
Assertion Types
Type
Description
Assert Input
Assert Output
Assert Callback
Assert Fault
5.
See the section shown in Table 446 based on the type of assertion you want to
perform.
Table 446
Assertion Types
A part section of a
document
See...
Section 44.4.5.1, "Creating Assertions on a Part Section, Nonleaf
Element, or Entire XML Document"
A nonleaf element
An entire XML
document
A leaf element
Click Browse to select the target part section, nonleaf element, or entire XML
document to assert.
The Select Assert Target dialog appears.
2.
Select a value, and click OK. For example, select a variable such as payload to
perform a part section assertion.
Figure 4416 shows this dialog. While this example shows how to perform a part
section assertion, selecting LoanBrokerRequestMessage is an example of an entire
XML document assertion and selecting loanApplication is an example of a
nonleaf assertion.
44-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4416
Table 447
Field
Value
Fault
Assert Target
Compare By
44-19
Value
Part
Value
Enter Manually
Click the Browse icon to load message data from a file. The file
is added to the messages folder in the Application Navigator.
Description
4.
Click OK.
The Wire Actions dialog shown in Figure 4418 displays your selection.
44-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4418
5.
Click OK.
2.
Select a leaf element, and click OK. For example, select loanAmount to perform an
assertion. Figure 4419 provides details.
Figure 4419
The Create Assert dialog refreshes based on your selection of an entire XML
document.
3.
44-21
Table 448
Field
Value
Fault
Callback Operation
Assert Target
Compare By
Assert Value
Enter the value you are expecting. This value is compared to the
value for the assert target.
Description
4.
Click OK.
44-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Wire Actions dialog shown in Figure 4421 displays your selection.
Figure 4421
<compositeTest compositeDN="TestFwk"
xmlns="http://xmlns.oracle.com/sca/2006/test">
<about></about>
<initiate serviceName="client" operation="initiate" isAsync="true">
<message>
<part partName="payload">
<content>
<loanApplication xmlns="http://www.autoloan.com/ns/autoloan">
<SSN>111222333</SSN>
<email>joe.smith@example.com</email>
<customerName>Joe Smith</customerName>
<loanAmount>20000</loanAmount>
<carModel>Camry</carModel>
<carYear>2007</carYear>
<creditRating>800</creditRating>
</loanApplication>
</content>
</part>
</message>
</initiate>
<componentTest componentName="LoanBroker" filePath="assert.xml"/>
44-23
</compositeTest>
The assert.xml test shown in Example 445 specifies assertions for variables and
faults.
You cannot automate the testing of business rule, human task,
Oracle Mediator, or spring service components.
Note:
<bpelTest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/sca/2006/test"
componentName="LoanBroker">
<activityActions activityName="elementAssign">
<assert comparisonMethod="number">
<description>Some other assertion.</description>
<expected>
<location key="textVar"
xmlns:loan="http://www.autoloan.com/ns/autoloan"/>
<simple>111222333</simple>
</expected>
</assert>
</activityActions>
<activityActions activityName="invokeCR">
<assert comparisonMethod="number">
<description>Make sure we got the output.</description>
<expected>
<location key="crOutput" partName="payload" xpath="/tns:rating"
xmlns:tns="http://services.otn.com"/>
<simple>560</simple>
</expected>
</assert>
</activityActions>
</bpelTest>
For more information about creating assertions on BPEL process activities, see
Section 44.5.5, "How to Create Assertions."
<bpelTest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/sca/2006/test
TestFwk.xsd"
44-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xmlns="http://xmlns.oracle.com/sca/2006/test"
componentName="LoanBroker">
<activityActions activityName="wait1">
<fastForward duration="PT1S"/>
</activityActions>
</bpelTest>
For more information about creating fast forward actions on wait activities, see
Section 44.5.6, "How to Bypass a Wait Activity."
<bpelTest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/sca/2006/test"
componentName="LoanBroker">
<assertActivityExecuted activityName="invoke" executionCount="1"/>
<assertActivityExecuted activityName="elementAssign" executionCount="1"/>
<assertActivityExecuted activityName="invokeCR" executionCount="1"/>
<assertActivityExecuted activityName="replyOutput" executionCount="1"/>
</bpelTest>
For more information about creating assert activity executions, see Section 44.5.7,
"How to Specify the Number of Times to Execute an Activity."
44-25
2.
Accept the default name or enter a different name, as shown in Figure 4422.
3.
Click OK.
The BPEL process in test mode is displayed, as shown in Figure 4423.
In the lower left section, the Structure window displays the Asserts, Fast
Forwards, and Assert Execution Counts folders. You can right-click these folders
to create assertions, fast forwards (to bypass executions of wait activities), and
assertion execution counts, respectively.
Above the designer, the following buttons are displayed:
BPEL: Click to access the BPEL process service component in design mode of
Oracle BPEL Designer (that is, in nontest mode). This button is currently
enabled in Figure 4423 because you are in test mode for the BPEL process.
Monitor: Click to configure BPEL process monitors in Oracle BPEL Designer.
BPEL process monitors can send data to Oracle BAM for analysis and
graphical display through the Oracle BAM adapter. For more information, see
Section 53.3, "Using Oracle BAM Monitor Express With BPEL Processes."
Test: This button is currently disabled because you are in test mode for the
BPEL process service component. This button is enabled when you click the
BPEL button to enter design mode in Oracle BPEL Designer.
44-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4423
In the Structure window, right-click the Asserts folder and select Create, or
select the Asserts folder and click the Add button.
The Assert dialog is displayed.
b.
In the Activity Name field, click the Browse icon to select an activity.
or
a.
Right-click a specific BPEL activity in the designer, and select Edit Activity
Test Data.
b.
c.
2.
Table 449
Field
Value
Assert Variable
Assert Fault
44-27
Value
Target
Compare By
If you selected Assert Variable, click the Browse icon to select the
type of variable to assert (for example:
/autoloan:loanApplication/autoloan:SSN).
If you selected Assert Fault, click the Browse icon to select the type
of fault to assert (for example, NegativeCredit).
Parts
Select the message part containing the XML document (for example,
payload).
Value
Enter Manually
Click the Browse icon to load message data from a file. The file is
added to the messages folder in the Application Navigator.
Description
3.
Click OK.
Expand the Assert folder in the Structure window to view the activities on which
you have created asserts. Figure 4424 provides details.
44-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4424
In the Structure window, right-click the Fast Forwards folder and select
Create, or select the Fast Forwards folder and click the Add button.
The Fast Forward dialog is displayed.
b.
In the Activity Name field, click the Browse icon to select the wait activity.
or
a.
Right-click a specific wait activity in the designer, and select Edit Activity Test
Data.
b.
Click the Fast Forward tab. This tab is only displayed if there are wait
activities in the BPEL process.
c.
2.
In the Duration list, specify a time period for which to bypass the wait activity (for
example, 1 second).
3.
Click OK.
44-29
4.
Expand the Fast Forwards folder in the Structure window to view the amount of
time for which to bypass the wait activity and move forward in the test scenario.
Figure 4425 provides details.
For more information about wait activities, see Section 15.4, "Creating a Wait Activity
to Set an Expiration Time."
In the Structure window, right-click the Assert Execution Counts folder and
select Create, or select the Assert Execution Counts folder and click the Add
button.
The Assert Execution Count dialog is displayed.
b.
In the Activity Name field, click the Browse icon to select the activity to
execute.
or
a.
Right-click a specific BPEL activity in the designer, and select Edit Activity
Test Data.
b.
c.
2.
44-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Click OK.
The Activity Test Data dialog looks as shown in Figure 4426.
Figure 4426
4.
Expand the Assert Execution Counts folder in the Structure window to view
execution counts assigned to activities. Figure 4427 provides details.
Figure 4427
44-31
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
For information about using the sca_test WLST command to execute a test
suite, see Section "sca_test" of Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.
For information about using the ant-sca-test.xml ant script to execute a test
suite, see Section 43.7.6.1, "How to Use ant to Automate the Testing of a SOA
Composite Application."
44-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part IX
Part IX
Advanced Topics
Chapter 48, "Using Oracle SOA Composer with Domain Value Maps"
45
Managing Large Documents and Large
Numbers of Instances
45
This chapter describes the best practices for managing large documents and metadata
and for managing environments with large numbers of instances in Oracle SOA Suite.
It also describes use cases for handling large documents, limitations on concurrent
processing of large documents, and tuning recommendations.
This chapter includes the following sections:
For more information about Oracle SOA Suite tuning and performance, see Oracle
Fusion Middleware Performance and Tuning Guide.
For information about troubleshooting Oracle SOA Suite issues, see Chapter
"Troubleshooting Oracle SOA Suite and Oracle BPM Suite" of Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
For information about using Oracle Data Integrator to perform fast bulk data
movement and handle complex data transformations, visit the following URL:
http://www.oracle.com/technetwork/middleware/data-integrator
SOAP Inline
In this use case, the binary attachments (for example, an image) are Base64-encoded as
text and then passed inline in the XML document. Table 451 provides details.
45-1
Table 451
Capabilities
Capability
Description
Security
Supported.
Supported.
Binding
45.1.1.1.2
SOAP MTOM
In this use case, the binary attachments (for example, an image) are Base64-encoded as
text and then passed as a Message Transmission Optimization Mechanism (MTOM)
document. Table 452 provides details.
Table 452
Capabilities
Capability
Description
Security
Supported.
Supported.
Binding
45.1.1.1.3
In this use case, the binary attachments (for example, an image) are Base64-encoded as
text and then passed inline in the XML document. Table 453 provides details.
Table 453
Capabilities
Capability
Description
Security
Not supported.
Supported.
Binding
45.1.1.1.4
In this use case, the binary attachments (for example, an image) are Base64-encoded as
text encoded. Table 454 provides details.
45-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 454
Capabilities
Capability
Description
Security
Not supported.
Filter/Transformation/Assig
n
Pass through.
Fanout
Supported.
Oracle B2B
Note:
45.1.1.2.1
In this use case, the binary attachments (for instance, an image) are passed end-to-end
as a stream. Table 455 provides details.
Table 455
Capabilities
Capability
Description
Security
Not supported.
Tuning
<mime:part>
<mime:content part="bin" type=image/jpeg"/>
</mime:part>
Notes:
45-3
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
Content-Description: This is the optional message description.
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: NotSure/DoesntMatter
<?xml version='1.0' ?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
. . .
<DocumentName>MyImage.gif</DocumentName>
. . .
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--MIME_boundary
Content-Type: image/gif
Content-Transfer-Encoding: binary
Content-ID: AnythingYoudLike
...binary GIF image...
--MIME_boundary--
Within the WSDL file of Oracle Mediator, perform the following steps:
a.
From the WSDL designer, open the Oracle Mediator WSDL file.
b.
c.
45-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
d.
Enter a name.
e.
Go to Source view of the WSDL and modify the WSDL input and WSDL
output with MIME multiparts.
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body parts="payload" use="literal"/>
</mime:part>
<mime:part>
<mime:content part="bin" type="application/octet-stream"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
f.
g.
45-5
</wsdl:portType>
<wsdl:binding name="PhotoCatalogBinding" type="tns:PhotoCatalog">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="addPhoto">
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body use="literal"/>
</mime:part>
<mime:part>
<mime:content part="photo"
type="image/jpeg"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
<wsdl:output>
<mime:multipartRelated>
<mime:part>
<soap:body use="literal"/>
</mime:part>
<mime:part>
<mime:content part="status" type="text/plain"/>
<mime:content part="status" type="text/xml"/>
</mime:part>
</mime:multipartRelated>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="replacePhoto">
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body parts="oldPhoto" use="literal"/>
</mime:part>
<mime:part>
<mime:content part="newPhoto"
type="image/jpeg"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
<wsdl:output>
<soap:body parts="status" use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
</wsdl:definitions>
45-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In scenarios in which one BPEL process calls a second BPEL process within the same
composite, the second BPEL process does not dehydrate the same attachment again.
In scenarios in which one BPEL process from composite 1 invokes a second BPEL
process from composite 2 and optimization is disabled, composite 1 makes a SOAP
call to composite 2. The second BPEL process does dehydrate attachments.
Properties for Streaming Attachments
To stream attachments, add the following properties in the composite.xml file. If
optimization is enabled, then a native call is used instead of a SOAP call. Example 452
provides details.
Example 452
<binding.ws
port="http://services.otn.com#wsdl.endpoint(MIMEService/MIMEService)"
xmlns:ns="http://xmlns.oracle.com/sca/1.0"
streamIncomingAttachments="true" streamOutgoingAttachments="true">
<!--Add this prop to reference bindings to make a SOAP call. -->
<property name="oracle.webservices.local.optimization">false</property>
</binding.ws>
Note:
ora:getAttachmentContent Function
<copy>
<from expression="ora:getAttachmentContent('input','bin')"/>
<to variable="initiateTaskInput" part="payload"
query="/taskservice:initiateTask/task:task/task:attachment/task:content"/>
</copy>
Example 453 copies the attachment content, which has its href stored in the
"input/bin" variable, to the content variable in Base64-encoded format.
Sending Attachment Streams
Oracle BPEL Process Manager supports sending the attachment stream to multiple
receivers. For Oracle BPEL Process Manager to send a stream to multiple receivers, it
must read the attachment stream from the database using the readBinaryFromFile
XPath function and pass the stream to the appropriate targets.
45-7
With the default configuration, Oracle Mediator can pass an attachment stream to only
one target receiver, which can be another component or a web service/adapter. The
second target cannot receive the attachment. When you define the
persistStreamAttachment property for the Oracle Mediator component, Oracle
Mediator can pass an attachment stream to multiple target receivers.
Oracle Mediator requires the persistStreamAttachment property for streaming
attachments where the source message that contains the attachment is shared by
multiple target receivers. Set this property to true in composite.xml to enable the
streaming of attachments to multiple targets. Example 454 provides details.
Example 454
component name="Mediator1">
<implementation.mediator src="Mediator1.mplan"/>
<property name="persistStreamAttachment">true</property>
</component>
<component name="Mediator">
<implementation.mediator src="Mediator.mplan"/>
<property name="passThroughAttachment">true</property>
</component>
bpel.config.transaction Property
If such composites do not execute as part of the same transaction context, the
attachment data saved by the first BPEL component in the call chain is not visible to
the other BPEL components in the call chain. In addition, they incur database locking
and timeout exceptions:
45-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
45.1.1.2.2
In this use case, the adapter streams the binary data to a database store and publishes
an href to the service engine (Oracle BPEL Process Manager or Oracle Mediator).
Table 456 provides details.
Table 456
Capabilities
Capability
Description
Security
N/A.
Filter/Transformation/Assig
n
Fanout
Supported.
Binding
Supported.
Tuning
Documentation
Use Oracle Mediator in the flow to map the attachment part from the source (Oracle
Mediator) to the target (file adapter) using an Oracle Mediator assign.
If you use Oracle BPEL Process Manager, the attachment is written to the dehydration
store, which slows down the process.
Transforming Attachments with the ora:doStreamingTranslate XPath Function
Use of the ora:doStreamingTranslate XPath function is only recommended
while transforming attachments within an Oracle BPEL Process Manager or Oracle
Mediator service component. This function expects the attachment location to be a
45-9
relative path on the server. This function cannot translate incoming attachment
streams.
For more information about this function, see Section B.2.7, "doStreamingTranslate."
45.1.1.2.3
In this use case, Oracle B2B stores the binary data to a database and publishes an href
to the service engine (Oracle BPEL Process Manager or Oracle Mediator) based on an
Oracle B2B-defined XSD. Oracle B2B protocols define the attachment. Table 457
provides details.
Table 457
Capabilities
Capability
Description
Security
N/A.
Supported.
Binding
Tuning
When attachments are inline and encoded, Oracle recommends that you not use
the file adapter to write attachments to a file.
The default mtomThreshold value is 1024 bytes and cannot be modified. If an
attachment is less than 1024 bytes, for outbound configurations, Oracle SOA Suite
sends it as an inline attachment. If the size is greater than 1024 bytes, then the
attachment is sent as an attachment part with an href attribute in the message,
and is sent as a WSDL-defined format on the wire. However, if the incoming
request (for example, from a different web services provider) has an xop href
node for small binary data (that is, size is less than 1024 bytes), Oracle SOA Suite
uses the same href attribute in the payload in the flow trace. For example:
<xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include"
href="cid:e29caf23dc8045908451fdfaafa26dce" />
45-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
As a best practice, Oracle recommends that you not use the XSLT Mapper to
propagate binary data. Instead, use an assign activity. If you must use a style sheet
to propagate binary data, it is recommended that you use the xsl:copy-of
instruction (copy-of copies everything, including attributes) or use custom
functions to copy attributes from source to target.
MTOM attachments should not be gigabytes in size. Instead, use the SOAP with
attachments streaming feature for very large attachments. For more information,
see Section 45.1.1.2.1, "SOAP with Attachments."
45.1.1.3.1
45-11
MTOM-optimized message can be a mix of one or more elements that have inline
base64 data, and one or more elements that are XOP-packaged, at any level.
Even if the service binding component is MTOM-enabled, it
does not automatically indicate that the service receives
MTOM-optimized messages. The calling service/application must
send MTOM-optimized messages over the wire to ensure the message
is received. MTOM-enabled bindings can also receive ordinary
non-MTOM messages. Therefore, when it receives one, the SOAP
requests arriving into the service can have nonoptimized inline binary
data elements that are not be persisted into the database.
Note:
Even though the content of the MTOM-optimized elements or SwA attachments have
their value replaced by an href attribute at runtime, their design-time WSDLs still
remain unaltered. You do not see these changes in Oracle JDeveloper. Their element
type definitions do not change from hexBinary, base64Binary, and so on to that of a
empty content with an href attribute.
However, this is transparent to you. For instance, when you use an assign activity to
copy across their content, the href values are copied over at runtime. Similarly, when
invoking an outbound reference such as a web service or an adapter, Oracle SOA Suite
automatically resolves the href attribute to the actual data and executes the
invocation.
In this use case, the inbound adapter splits a source document into multiple batches of
records, each of which initiates a composite instance. Table 458 provides details.
Table 458
Capabilities
Capability
Description
Security
N/A.
Filter/Transformation/Assig
n
Supported.
Fanout
Supported.
Binding
Supported.
Tuning
Documentation
45.1.1.4.2
45-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In this use case, a loop within a BPEL process reads a chunk of records at a time and
process (that is, cursor). Table 459 provides details.
Table 459
Capabilities
Capability
Description
Security
Supported.
Filter/Transformation/Assig
n
Supported.
Fanout
Supported.
Documentation
In this use case, very large XML files are streamed through Oracle SOA Suite.
Table 4510 provides details.
Table 4510
Capabilities
Capability
Description
Security
N/A.
Filter/Transformation/Assig
n
Fanout
Supported.
Binding
Documentation
45.1.1.5.2
In this use case, large XML files are passed by Oracle B2B to Oracle SOA Suite as an
SDOM. This only occurs when a large payload size is defined in the Oracle B2B user
interface. Table 4511 provides details.
Table 4511
Capabilities
Capability
Description
Security
N/A.
Supported.
Binding
45-13
Increase the JTA transaction timeout to 500 seconds in Oracle WebLogic Server
Administration Console. For instructions, see section "Resolving Connection
Timeouts" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite
and Oracle Business Process Management Suite.
In Oracle Enterprise Manager Fusion Middleware Control, set the audit level to
Off or Production at the SOA composite application level. See Section 45.1.3.2,
"Setting Audit Levels from Oracle Enterprise Manager for Large Payload
Processing" for additional information.
Uncomment the following line in setDomainEnv.sh (for Linux) or
setDomainEnv.bat (for Windows) for JAVA_OPTIONS, and restart the server. If
this line does not exist, add it. Without this setting, large payload scenarios fail
with ResourceDisabledException error for the dehydration data source.
-Dweblogic.resourcepool.max_test_wait_secs=30
Extend data files for handling large attachments. For more information, see the
Oracle Database Administrator's Guide.
If you are processing large documents and run into timeout errors, perform the
following tasks:
1.
2.
3.
Click each of the following beans, select Configuration, and increase the
timeout value:
BpelEngineBean
BpelDeliveryBean
CompositeMetaDataServiceBean
Follow the instructions in Chapter "Using the WebLogic 8.1 Thread Pool
Model" of Oracle Fusion Middleware Performance and Tuning for Oracle WebLogic
Server.
45.1.3.2 Setting Audit Levels from Oracle Enterprise Manager for Large Payload
Processing
For large payload processing, turn off audit level logging for the specific composite.
You can set the composite audit level option to Off or Production in Oracle Enterprise
Manager Fusion Middleware Control. If you set the composite audit level option to
Development, then it serializes the entire large payload into an in-memory string,
which can lead to an out-of-memory error.
For more information about setting audit levels, see Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
45.1.3.3 Using the Assign Activity in Oracle BPEL Process Manager and Oracle
Mediator
When using the assign activity in Oracle BPEL Process Manager or Oracle Mediator to
manipulate large payloads, do not assign the complete message. Instead, assign only
the part of the payload that you need.
In addition, when using the assign activity in Oracle BPEL Process Manager, Oracle
recommends using local variables instead of process variables, wherever possible.
Local variables are limited to the scope of the BPEL process. These get deleted from
memory and from the database after you close the scope. However, the life cycle of a
global variable is tied with the instance life cycle. These variables stay in memory or
remain on disk until the instance completes. Thus, local variables are preferred to
process or global variables.
ora:processXSLT('template','input','properties'?)
45-15
3.
45-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Note:
3.
In the composite.xml file, scroll to the component element that defines the
Oracle Mediator component to process large XML documents, and add the
streamResultToTempFile property. Set the property to yes as shown below.
<component name="Mediator1">
<implementation.mediator src="Mediator1.mplan"/>
<property name="streamResultToTempFile">yes</property>
</component>
4.
45-17
You can also use the following optimized translation functions while performing
transformations/translations of large payloads:
ora:doTranslateFromNative or med:doTranslateFromNative
ora:doTranslateToNative or med:doTranslateToNative
ora:doStreamingTranslate or med:doStreamingTranslate
For more information about these functions, see Appendix B, "XPath Extension
Functions" and Oracle Fusion Middleware User's Guide for Technology Adapters.
mdsCache
Cache Size
Number of threads
Tablespace
The following sections describe the parameters you must set for processing large
documents in Oracle B2B.
45.1.3.7.1
To set the Oracle Metadata Services (MDS) Repository instance cache size, the
property and value must be added to the $DOMAIN_
HOME/config/soa-infra/configuration/b2b-config.xml file, as shown in
Example 458.
Example 458
<property>
<name>b2b.mdsCache</name>
<value>200000</value>
<comment>MDS Instance cache size </comment>
</property>
45.1.3.7.2
3.
4.
45-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example 459
max-message-size Property
<name>soa_server1</name>
<max-message-size>150000000</max-message-size>
45.1.3.7.3
Number of Threads
This parameter improves the message processing capability of Oracle B2B and must be
set in the $DOMAIN_
HOME/config/soa-infra/configuration/b2b-config.xml file.
Example 4510 provides an example.
Example 4510 Number of Threads
<property>
<name>b2b.inboundProcess.threadCount</name>
<value>5</value>
<comment></comment>
</property>
<property>
<name>b2b.inboundProcess.sleepTime</name>
<value>10</value>
<comment></comment>
</property>
<property>
<name>b2b.outboundProcess.threadCount</name>
<value>5</value>
<comment></comment>
</property>
<property>
<name>b2b.outboundProcess.sleepTime</name>
<value>10</value>
<comment></comment>
</property>
<property>
<name>b2b.defaultProcess.threadCount</name>
<value>5</value>
<comment></comment>
</property>
<property>
<name>b2b.defaultProcess.sleepTime</name>
<value>10</value>
<comment></comment>
</property>
45.1.3.7.4
The Stuck Thread Max Time parameter checks the number of seconds that a thread
must continually work before the server considers the thread stuck. You must change
the following setting in the Oracle WebLogic Server Administration Console:
To configure the Stuck Thread Max Time parameter:
1. In the Domain Structure, select Environment > Servers.
2.
45-19
3.
4.
45.1.3.7.5
Tablespace
If you must store more than a 150 MB configuration in the data file, then you must
extend or add the data file to increase the tablespace size, as shown in Example 4511.
Example 4511 Extension of Data File
ALTER TABLESPACE sh_mds add DATAFILE 'sh_mds01.DBF' SIZE 100M autoextend on next
10M maxsize unlimited;
ALTER TABLESPACE sh_ias_temp add TEMPFILE 'sh_ias_temp01.DBF' SIZE 100M autoextend
on next 10M maxsize unlimited;
45-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ora:processXSLT
ora:doXSLTransformForDoc
With the ora:processXSLT function, you use the properties argument to enable
this functionality.
ora:processXSLT('template','input','properties'?)
You retrieve the value of this argument within your XSLT in a way similar to
extracting data from XSL variables. The properties argument is an XML element of
the structure shown in Example 4513. For large payload results (for example, above
10 MB), set streamResultToTempFile to yes. For small payload results in which
you do not need to write results to a temporary file, leave this property set to its
default value of no.
Example 4513 properties XML
<propertiesXMLVar>
<common:item xmlns:common="http://schemas.oracle.com/service/bpel/common">
<common:name>streamResultToTempFile</common:name>
<common:value>yes</common:value>
</common:item>
</propertiesXMLVar>
Within the XSLT, the parameters are accessible through the name of
streamResultToTempFile and its value of yes.
In Oracle BPEL Process Manager, a literal assign is performed to populate the
properties for ora:processXSLT('template','input','properties'?).
For more information on using this function, see Section B.2.52, "processXSLT."
With the ora:doXSLTransformForDoc function, you set the name and value
properties to enable this functionality.
ora:doXSLTransformForDoc ('template','input','name', 'value')
With this function, the name of streamResultToTempFile and the value of yes are
passed.
For more information on using the function, see Section B.2.11,
"doXSLTransformForDoc."
100 threads
45-21
Keep the number of incoming request messages at a proper level to ensure system
memory stability.
The above settings enable you to deploy and execute BPEL processes, which use only
while loops without the flowN activities, successfully.
Set the StatsLastN property to -1 in the System MBean Browser of Oracle Enterprise
Manager Fusion Middleware Control.
The above settings enable you to deploy and execute BPEL processes, which use the
flowN activities, successfully.
For more information, see Section 10.3.1, "Customizing the Number of Flow Activities
with the flowN Activity in BPEL 1.1" and Section "Configuring BPEL Process Service
Engine Properties" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA
Suite and Oracle Business Process Management Suite.
Note:
Note:
45-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
45.3.1 Instance and Rejected Message Deletion with the Purge Script
Deleting thousands of instances and rejected messages in Oracle Enterprise Manager
Fusion Middleware Control takes time and can result in a transaction timeout. If you
must perform this task, use the PL/SQL purge script for instance and rejected message
deletion.
For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
Disable the fetching of instance and fault count data to improve loading times for
the following pages:
45-23
These settings disable the loading of all metrics information upon page load. For
example, on the Dashboard page for the SOA Infrastructure, the values that
typically appear in the Running and Total fields in the Recent Composite
Instances section and the Instances column of the Deployed Composites section
are replaced with links. When these values are large, it can take time to load this
page and other pages with similar information.
Specify a default time period used as part of the search criteria for retrieving
recent instances and faults for display on the following pages:
For more information about setting these properties, see Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
45-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
46
Customizing SOA Composite Applications
46
This chapter describes how to customize SOA composite applications with the
customization feature available with a BPEL process service component. It describes
how to create a customizable application, customize the vertical version of the
application, and customize the customer version of the application. It also describes
how to upgrade to the next version of the application.
This chapter includes the following sections:
A customer
The core applications development team creates a base customizable composite and
delivers it to a vertical applications team that customizes it for a certain industry (for
example, telecommunications). The tailored solution is then sold to a
telecommunications customer that further customizes the composite for their specific
geographic business needs. Essentially, there is a base composite and several layers of
customized composites. At a later time in the composite life cycle, the core
applications development team creates the next version of the base composite,
triggering an upgrade cycle for the vertical applications team and the customer.
Note:
From the File menu, select New > Applications > SOA Application, and click
OK.
3.
4.
On the Create SOA Application dialog, select both Composite With BPEL Process
and the Customizable checkbox.
5.
6.
Customize the BPEL process by creating a scope activity. This action is required
because by default the BPEL process is not customizable.
Note: You can only customize the composite.xml file, .bpel file
(for Oracle BPEL Process Manager), .mplan file (for Oracle Mediator),
and .componentType file when logged into Oracle JDeveloper with
the Customization Developer role.
7.
8.
9.
Open the adf-config.xml file and select the MDS Configuration tab.
10. Click the Add icon to add the required customization classes, as shown in
Figure 461.
In real environments, the customization classes are provided by the core
applications team. When you use your own customization classes, you must add
your customization class JAR file to your project to make the classes available for
the adf-config.xml file.
46-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
11. Right-click the SOA project and select Deploy. This creates a JAR file package.
3.
setName("MyCustomizationLayer");
}
}
The Create Java Class Wizard automatically generates the following content:
package myCustomizationPackage;
import oracle.tip.tools.ide.fabric.custom.GenericSOACustomizationClass;
public class MyCustomizationClass extends GenericSOACustomizationClass {
public MyCustomizationClass(String string, String string1) {
super(string, string1);
}
public MyCustomizationClass() {
super();
}
}
4.
For the customization class to have the correct customization layer, set the
customization layer name by adding the following to the constructor without
parameters.
// set the customization layer name
setName("MyCustomizationLayer");
6.
2.
Select SOA.
3.
46-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
In the Search menu for the BPEL process at the top of the designer, select
Customization Search, as shown in Figure 462.
The search results display in the Search for Customizations tab of the Log
window at the bottom of the designer.
46.2.5 What You May Need to Know About Editing Artifacts in a Customized Composite
The source of any artifact in Oracle JDeveloper (except for new artifacts created in the
Customization Developer role) is editable in the Customization Developer role of
another application.
To edit artifacts in a customized composite:
1. Create a SOA composite application with the Customization Developer option
selected.
2.
3.
Deploy the composite to a SAR file, and import the SAR file into another new
composite.
4.
Restart Oracle JDeveloper and open the new composite using the Customization
Developer role.
5.
Go to the Source view of the composite.xml file, and from the Property
Inspector attempt to modify the passThroughHeader property value.
The property is editable.
46.2.6 What You May Need to Know About Resolving Validation Errors in Oracle
JDeveloper
In the customization role, the Oracle Metadata Services (MDS) Repository merges
customizations with the base metadata. The merging can result in an invalid XML
document against its schema. MDS Repository merging does not invoke a schema
validation to ensure that the merging always creates a valid XML document. This can
cause a problem for MDS clients that rely on the validity of the metadata to render
their metadata UI editors.
Whenever a SOA file such as composite.xml becomes invalid, you must switch to
Source view in Oracle JDeveloper to directly fix the XML source. If Source view is not
editable (for example, you have accessed Oracle JDeveloper using the Customization
Developer role), you must use the Structure window in Oracle JDeveloper to fix the
XML source.
For example, assume you created a base SOA composite application with a BPEL
process that included a customized scope. The SAR file for the base application was
then imported into a new application in which the following components were added
when accessing Oracle JDeveloper with the Customization Developer role:
An invoke activity (added to the customizable scope) for invoking the file adapter
When version two of the base SOA composite application was created, a synchronous
Oracle Mediator service component was added, which caused the routing rules to the
BPEL process service component to be updated.
The SAR file for version two of the base application was then imported into the
customized application. When the user accessed Oracle JDeveloper with the
Customization Developer role, an invalid composite error was displayed. The
composite.xml file in the Structure window showed the following invalid structure
for the sequence of service components and reference binding components.
Example 461 provides details.
Example 461
Invalid Structure
<component> </component>
<reference> </reference>
<component> </component>
The <reference> component (in this case, the outbound file adapter added when
the user accessed Oracle JDeveloper with the Customization Developer role in
version one of the base application) should have displayed last. Example 462
provides details.
Example 462
Valid Structure
<component> </component>
<component> </component>
<reference> </reference>
To resolve this error, go to the Structure window and copy and paste these components
into the correct order. This action resolves the composite validation error.
46.2.7 What You May Need to Know About Resolving a Sequence Conflict
Assume you perform the following steps.
To resolve a sequence complex:
1. Customize version 1 of a SOA composite application.
For example, while logged into Oracle JDeveloper with the Customization
Developer role, you add new activities into a customizable scope activity of the
BPEL process. The BPEL process creates a sequence activity into which the new
activities are added.
2.
3.
4.
46-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
4.
Delete the components in the sequence from which they were copied.
5.
46.2.8 What You May Need to Know About Compiling and Deploying a Customized
Application
When you deploy or compile a customized application at the core application, vertical
application, or customer level, warning messages describing unexpected ID attributes
are displayed, as shown in Example 463. You can safely ignore these messages. These
messages display because the schema definition does not include these simple-type
elements, which is expected behavior. These messages do not prevent the customized
composite from being successfully deployed.
Example 463
[scac] warning: in
/scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml(22,32):
Schema validation failed for
/scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml<Line 22,
Column 32>: XML-24535: (Error) Attribute
'http://www.w3.org/XML/1998/namespace:id' not expected.
[scac] warning: in
/scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml(23,32):
Schema validation failed for
/scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml<Line 23,
Column 32>: XML-24535: (Error) Attribute
'http://www.w3.org/XML/1998/namespace:id' not expected.
b.
or
a.
2.
3.
Create a new SOA application with a different name than the core application.
4.
From the File menu, select Import > SOA Archive Into SOA Project.
5.
Click Browse to select the composite archive JAR file created by the core
application team in Section 46.2, "Creating the Customizable Composite."
6.
In the Composite Name field, enter a different name than the core SOA project.
Do not select any SOA project. You must create a new SOA
project for the JAR file that you import.
Note:
7.
8.
From the Tools menu, select Preferences > Roles > Customization Developer.
9.
10. Select a layer and value to customize, as shown in Figure 464 (for this example,
46-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
11. In the SOA Composite Editor, double-click the BPEL process to access Oracle
BPEL Designer.
You can only edit scope activities that have been set to customizable. In the
example shown in Figure 465, the core applications team set only one scope to be
customizable. The other activities in the BPEL process are disabled and cannot be
edited.
Figure 465 One Customizable Scope
12. Right-click the SOA project in the Application Navigator and select Deploy to
The JAR file contains a merged composite that in turn acts as a base process for the
next level of customization. The JAR file can now be delivered to the customer.
You can create WSDL and XSD files while logged into Oracle
JDeveloper with the Customization Developer role. In the
Application Navigator, right-click the project name and select SOA >
Create WSDL or SOA > Create XSD.
Note:
b.
or
a.
2.
3.
Create a new SOA application with a different name than the core application or
customized application.
4.
From the File menu, select Import > SOA Archive Into SOA Project.
5.
Click Browse to select the composite archive JAR file created by the vertical
applications team in Section 46.3, "Customizing the Vertical Application."
6.
7.
From the Tools menu, select Preferences > Roles > Customization Developer.
8.
46-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
Select a layer and value to customize, as shown in Figure 466 (for this example,
the layer site and value North America are selected).
3.
4.
Deploy the composite to create the next revision of the JAR file.
5.
3.
4.
Select the project node in the Application Navigator to set the current project
context. This is important because the import command in the next step imports
the SOA archive into the selected project to upgrade the base.
46-11
5.
From the File menu in Oracle JDeveloper, import the new revision of the JAR file
created in Section 46.5.1, "How to Upgrade the Core Application Team
Composite."
6.
From the Tools menu, select Preferences > Roles > Customization Developer.
7.
8.
In the Customization Context dialog, select a layer and value to customize (for
example, select the layer industry and value Communications).
9.
Open the BPEL process to see if the new base composite can be merged with layers
for the above selected context.
10. Review the Log window for potential warnings and errors.
11. If required, fix errors and warnings by modifying the process. This edits the layers
46-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
47
Working with Domain Value Maps
47
This chapter describes how to create and use domain value maps to map the terms
used by different domains to describe the same entity, allowing you to map values
used by one domain for specific fields to the values used by other domains for the
same fields. This chapter also describes the XPath functions used for domain value
lookups.
This chapter includes the following sections:
Section 47.5, "Creating a Domain Value Map Use Case for a Hierarchical Lookup"
Section 47.6, "Creating a Domain Value Map Use Case For Multiple Values"
Point-to-Point Mapping
CityCode
CityName
BELG_MN_STLouis
BelgradeStLouis
BELG_NC
BelgradeNorthCarolina
CityName
BO
Boston
NP
Northport
KN_USA
KensingtonUSA
KN_CAN
KensingtonCanada
Domain value map values are static. You specify the domain value map values at
design time using Oracle JDeveloper, and then at runtime the application performs a
lookup for the values in the domain value maps. For information about editing
domain value maps at runtime with Oracle SOA Composer, see Chapter 48, "Using
Oracle SOA Composer with Domain Value Maps."
To dynamically integrate values between applications, you can
use the cross referencing feature of Oracle SOA Suite. For information
about cross references, see Chapter 49, "Working with Cross
References."
Note:
Country (Qualifier)
CityCode
CityName
USA
BO
Boston
USA
BELG_NC
Belgrade
USA
BELG_MN_Streams
Belgrade
USA
NP
Northport
USA
KN
Kensington
Canada
KN
Kensington
A domain value map can contain multiple qualifier domains. For example, as shown
in Table 473, the mappings are also qualified with a state name.
47-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 473
Country
(Qualifier)
State (Qualifier)
CityCode
CityName
USA
Massachusetts
BO
Boston
USA
North Carolina
BELG
Belgrade
USA
Minnesota
BELG
Belgrade
USA
Alabama
NP
Northport
USA
Kansas
KN
Kensington
Canada
Prince Edward
Island
KN
Kensington
Qualifiers are used only to qualify the mappings. Therefore, the qualifier values cannot
be looked up.
In this example, the State qualifier has a qualifier order of 1 and the Country
qualifier has a qualifier order of 2. As shown in Figure 471, the lookup mechanism
sets the higher order qualifier State to the exact lookup value Arkansas and uses
Canada|"" for the lower order qualifier Country.
Figure 471 Hierarchical Lookup Example
Level of
Generalization
Step 3
Step 2
Step 1
Level of
Customization
If no match is found, the lookup mechanism sets the higher order qualifier State to a
value of "" and sets the next higher qualifier Country to an exact value of Canada. If
no match is found, the lookup mechanism sets the value of the previous higher order
qualifier Country to a value of "". One matching row is found where CityCode is
KN_USA and Kensington is returned as a value.
State
Country
Short Value
Lookup Result
Arkansas
CANADA|" "
KN_USA
No Match
" "
CANADA
KN_USA
No Match
" "
" "
KN_USA
Kensington
Payment Term
Discount
Percentage
Discount
Period
Net Credit
Period
GoldCustomerPaymentTerm
10
20
30
SilverCustomerPaymentTerm
20
30
RegularPaymentTerm
20
30
Expand the SOA Tier node, and then select the Transformations category.
3.
In the Items list, select Domain Value Map(DVM) and click OK.
The Create Domain Value Map(DVM) File dialog appears.
4.
In the File Name field, enter a unique and descriptive name for the domain value
map file. The file name must have an extension of .dvm.
5.
In the Description field, enter a description for the domain value map. This field is
optional.
47-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
In the Domain Name field, enter a name for each domain. These names are the
column names for the domain value map, and each represents a fields in a
different domain.
Domain names must be of the type NCName (non-colonized
name), which is a valid XML element name with no colons. Each
domain name must be unique in a domain value map. You can add
more domains later.
Note:
7.
In the Domain Value field, enter a value corresponding to each domain. For
example, enter BO for a CityCode domain and Boston for a CityName domain,
as shown in Figure 472.
8.
Click OK.
The Domain Value Map Editor appears with the new domain value map
displayed.
All .dvm files are based on the schema definition (XSD) file shown in Example 471.
Example 471
47-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
type="xsd:boolean"
use="optional"/>
<xsd:attribute name="order" use="optional"
type="xsd:positiveInteger"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="rows" minOccurs="0">
<xsd:annotation>
<xsd:documentation>This represents all the DVM Rows.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="row" minOccurs="1" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
Each DVM row of values
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="cell" minOccurs="2" maxOccurs="unbounded"
type="xsd:string">
<xsd:annotation>
<xsd:documentation>This is the value for this row and for
each column in the same order as defined in Columns.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" use="required" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:annotation>
<xsd:documentation>This Schema is used to validate the DVM Document got for
creation and
update of a DVM.
</xsd:documentation>
</xsd:annotation>
</xsd:schema>
be included in the lookups at runtime or if it is only used to qualify the mapping. Note
that domain (column) names must be of the type NCName (non-colonized name),
which is a valid XML element name with no colons.
To add a domain to a domain value map:
1. If the map file is not open in the Domain Value Map Editor, double-click the DVM
file in the Application Navigator.
2.
In the Map Table, click Add and then select Add Domain.
The Create Domain dialog appears.
3.
4.
In the Qualifier field, select True to set this column as a qualifier. Otherwise, select
False.
Tip: For more information about qualifier domains and qualifier
order, see Section 47.1.1.1, "Qualifier Domains" and Section 47.1.1.2,
"Qualifier Hierarchies.".
5.
In the Qualifier Order field, enter a number indicating the priority of the qualifier
domain.
This field is enabled only if you selected True in the Qualifier field.
6.
Click OK.
A new column appears in the Map Table.
47-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Change any of the fields on the dialog, and then click OK.
Domain names must be of the type NCName (non-colonized
name), which is a valid XML element name with no colons.
Note:
3.
Repeat the above steps to create additional rows. When you are done making
changes, click Save All on the Oracle JDeveloper toolbar.
3.
Modify any of the fields on the dialog, and then click OK.
47.4.1.1 dvm:lookupValue
The dvm:lookupValue function returns a string by looking up the value for the
target column in a domain value map, where the source column contains the given
source value.
Example 472
dvm:lookupValue('cityMap.dvm','CityCodes','BO', 'CityNames',
'CouldNotBeFound')
Example 474
47-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
dvm:lookupValue (cityMap.dvm,CityCodes,BO,CityNames,
CouldNotBeFound, State, Massachusetts)
Arguments
SourceValue - The source value (an XPath expression bound to the source
document of the XSLT transformation).
DefaultValue - If the value is not found, then the default value is returned.
47.4.1.2 dvm:lookupValue1M
The dvm:lookupValue1M function returns an XML document fragment containing
values for multiple target columns of a domain value map, where the value for the
source column is equal to the source value. Example 476 provides details.
Example 476
Arguments
SourceValue - The source value (an XPath expression bound to the source
document of the XSLT transformation).
TargetColumnName - The name of the target columns. At least one column name
should be specified. The question mark symbol (?) indicates that you can specify
multiple target column names.
dvm:lookupValue1M ('cityMap.dvm','CityCode','BO','CityName',
'CityNickName')
<CityName>Boston</CityName>
<CityNickName>BeanTown</CityNickName>
In the XSLT Mapper, expand the trees in the Source and Target panes.
3.
In the Component Palette, click the down arrow, and then select Advanced.
4.
5.
Drag and drop lookupValue1M onto the line that connects the source to the target.
A dvm:lookupValue1M icon appears on the connecting line.
6.
47-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
Specify values for the following fields in the Edit Function lookupValue1M
dialog:
a.
In the dvmLocation field, enter the location URI of the domain value map file
or click Browse to the right of the dvmLocation field to select a domain value
map file. You can select an already deployed domain value map from the
metadata service (MDS) and also from the shared location in MDS. This can be
done by selecting the Resource Palette.
b.
In the sourceColumnName field, enter the name of the domain value map
column that is associated with the source element value, or click Browse to
select a column name from the columns defined for the domain value map
you previously selected.
c.
In the sourceValue field, enter a value or press Ctrl-Space to use the XPath
Building Assistant. Press the up and down arrow keys to locate an object in
the list, and press Enter to select an item.
d.
In the targetColumnName field, enter the name of the domain value map
column that is associated with the target element value, or click Browse to
select the name from the columns defined for the domain value map you
previously selected.
e.
Click Add to add another column as the target column and then enter the
name of the column.
8.
Click OK.
The XSLT Mapper appears with the lookupValue1M function icon.
9.
For more information about selecting deployed domain value maps, see Section 43.7.3,
"How to Deploy and Use Shared Data Across Multiple SOA Composite Applications
in Oracle JDeveloper."
3.
This expression, also shown in Figure 4710, looks up a domain value map for the
city name equivalent of a city code. The value of the city code depends on the
value specified at runtime.
47-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4710
47.5 Creating a Domain Value Map Use Case for a Hierarchical Lookup
This section provides a tutorial for using domain value maps in a SOA composite. This
use case demonstrates the hierarchical lookup feature of domain value maps. The
hierarchical lookup use case consists of the following steps:
1.
2.
The ReadOrders adapter service sends the file data to a Mediator named
ProcessOrders.
3.
The ProcessOrders Mediator then transforms the message to the structure required
by the adapter reference. During transformation, Mediator looks up the
UnitsOfMeasure domain value map for an equivalent value of the Common
domain.
4.
5.
To download the sample files mentioned in this section, see the Oracle SOA Suite
samples page.
In the New Gallery, expand the General node, and select the Applications
category.
3.
4.
In the Application Name field, enter Hierarchical and then click Next.
The Name your project page appears.
5.
6.
In the Composite Template list, select Empty Composite and then click Finish.
The Application Navigator of Oracle JDeveloper is populated with the new
application and the project, and the SOA Composite Editor contains a blank
composite.
7.
2.
In the New Gallery dialog, expand the SOA Tier node, and then select the
Transformations category.
3.
In the Items list, select Domain Value Map(DVM) and click OK.
The Create Domain Value Map(DVM) File dialog appears.
4.
5.
6.
In the Domain Value field corresponding to the Siebel domain, enter Ea.
7.
In the Domain Value field corresponding to the Common domain, enter Each.
8.
Click OK.
The Domain Value Map Editor appears.
9.
47-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Siebel
Common
TradingPartner
StandardCode
EC
Each
E-RN
Each
A.C.Networks
RN
EO
Each
ABC Inc
RN
OAG
16. From the File menu, select Save All and close the Domain Value Map Editor.
Oracle Mediator may process the same file twice when run
against Oracle Real Application Clusters (Oracle RAC) planned
outages. This is because a file adapter is a non-XA compliant adapter.
Therefore, when it participates in a global transaction, it may not
follow the XA interface specification of processing each file only once.
Note:
2.
3.
4.
In the Service Name field, enter ReadOrders and then click Next.
The Operation page appears.
5.
In the Operation Type field, select Read File and then click Next.
The File Directories page appears.
6.
In the Directory for Incoming Files (physical path) field, enter the directory from
which you want to read the files.
7.
Click Next.
The File Filtering page appears.
8.
In the Include Files with Name Pattern field, enter *.xml and then click Next.
The File Polling page appears.
9.
Change the Polling Frequency field value to 10 seconds and then click Next.
The Messages page appears.
Figure 4712 shows the ReadOrders service in the SOA Composite Editor.
47-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4712
Drag and drop a Mediator icon from the Component Palette to the Components
section of the SOA Composite Editor.
The Create Mediator dialog appears.
2.
3.
4.
Click OK.
A Mediator with name ProcessOrders is created.
5.
Figure 4713
6.
2.
3.
Click Next.
The Service Name page appears.
4.
5.
Click Next.
The Operation page appears.
6.
7.
Click Next.
The File Configuration page appears.
8.
In the Directory for Outgoing Files (physical path) field, enter the name of the
directory in which you want to write the files.
9.
listOfOrder.
12. Click OK.
13. Click Next.
47-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4715
2.
3.
4.
5.
Drag and drop the imp1:listOfOrder source element onto the imp1:listOfOrder
target element.
The Auto Map Preferences dialog appears.
6.
From the During Auto Map options, deselect Match Elements Considering their
Ancestor Names.
7.
Click OK.
The listOfOrder_To_listOfOrder.xsl file appears, as shown in Figure 4716.
Figure 4716
8.
9.
10. Drag and drop lookupValue on the line connecting the unitsOfMeasure elements,
/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:unitOfMeasure
17. To the right of the targetColumnName field, click Search.
/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:standard.
24. Click Add to insert another qualifierColumnName row.
47-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:tp.
The Edit Function-lookupValue dialog appears, as shown in Figure 4718.
Figure 4718
29. From the File menu, select Save All and close the listOfOrder_To_listOfOrder.xsl
For detailed information about these steps, see Section 43.7.1, "How to Deploy a Single
SOA Composite in Oracle JDeveloper."
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure.
For detailed information about these steps, see Section 43.7.1, "How to Deploy a Single
SOA Composite in Oracle JDeveloper."
47.6 Creating a Domain Value Map Use Case For Multiple Values
This section provides a tutorial demonstrating how to create a domain value map with
multiple values to look up. This use case demonstrates the integration scenario for
using a domain value map lookup between two endpoints to look up multiple values.
For example, if the inbound value is State, then the outbound values are Shortname of
State, Language, and Capital. The multivalue lookup use case consists of the following
steps:
1.
2.
The readFile adapter service sends the file data to an Oracle Mediator named
LookupMultiplevaluesMediator.
3.
4.
5.
To download the sample files mentioned in this section, see Oracle SOA Suite
samples page.
47-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
In the New Gallery, expand the General node, and select the Applications
category.
3.
4.
In the Application Name field, enter Multivalue and then click Next.
The Name your project page appears.
5.
6.
From the Composite Template list, select Empty Composite and then click Finish.
The Application Navigator of Oracle JDeveloper is populated with the new
application and project, and the SOA Composite Editor contains a blank
composite.
7.
In the Application Navigator, right-click the Multivalue project and select New.
2.
In the New Gallery dialog, expand the SOA Tier node, and then select the
Transformations category.
3.
In the Items list, select Domain Value Map(DVM) and click OK.
The Create Domain Value Map(DVM) File dialog appears.
4.
5.
6.
7.
In the Domain Value field corresponding to the Shortname domain, enter KA.
8.
9.
Longname
Shortname
Language
Capital
Karnataka
KA
Kannada
Bangalore
Tamilnadu
TN
Tamil
Chennai
Andhrapradesh
AP
Telugu
Hyderbad
Kerala
KL
Malayalam
Trivandram
13. From the File menu, select Save All and close the Domain Value Map Editor.
Note:
47-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
1.
2.
3.
4.
In the Service Name field, enter readFile and then click Next.
The Adapter Interface page appears.
5.
Click Define from operation and schema (specified later) and then click Next.
The Operation page appears.
6.
In the Operation Type field, select Read File and then click Next.
The File Directories page appears.
7.
In the Directory for Incoming Files (physical path) field, enter the directory from
which you want to read the files.
8.
Click Next.
The File Filtering page appears.
9.
In the Include Files with Name Pattern field, enter *.xml and then click Next.
The File Polling page appears.
10. Change the Polling Frequency field value to 1 second and then click Next.
Figure 4721 shows the readFile service in the SOA Composite Editor.
Drag and drop a Mediator icon from the Component Palette to the Components
section of the SOA Composite Editor.
The Create Mediator dialog appears.
2.
3.
4.
Click OK.
An Oracle Mediator with the name LookupMultiplevaluesMediator is created.
5.
6.
47-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
Click Next.
The Service Name page appears.
4.
In the Service Name field, enter writeFile and then click Next.
The Adapter Interface page appears.
5.
Click Define from operation and schema (specified later) and then click Next.
The Operation page appears.
6.
Click Next.
The Operation page appears.
7.
8.
Click Next.
The File Configuration page appears.
9.
In the Directory for Outgoing Files (physical path) field, enter the name of the
directory where you want to write the files.
10. In the File Naming Convention field, enter multivalue_%SEQ%.xml and click
Next.
The Messages page appears.
11. Click Search.
Root-Element.
13. Click OK.
14. Click Next.
Figure 4723 shows the writeFile reference in the SOA Composite Editor.
2.
3.
4.
5.
47-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
From the During Auto Map options list, deselect Match Elements Considering
their Ancestor Names.
7.
Click OK.
The Input_To_Output_with_multiple_values_lookup.xsl file appears in the XSLT
Mapper, as shown in Figure 4725.
Figure 4725
8.
9.
10. Drag and drop lookupValue1M in the center panel, as shown in Figure 4726.
Figure 4726
/imp1:Root-Element/imp1:Details/imp1:Longname.
17. To the right of the targetColumnName field, click Search.
24. From the File menu, select Save All and close the Input_To_Output_with_
multiple_values_lookup.xsl file.
47-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For detailed information about these steps, see Section 43.7.1, "How to Deploy a Single
SOA Composite in Oracle JDeveloper."
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure.
In Oracle Enterprise Manager Fusion Middleware Control, you can click Multivalue to
see the project dashboard.
To view the detailed execution trail, click the instance ID in the instance column. The
Flow Trace page appears.
47-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
48
48
For more information about domain value maps, see Chapter 47, "Working with
Domain Value Maps."
The Oracle SOA Composer Login page appears, as shown in Figure 482.
Figure 482 Oracle SOA Composer Login Page
2.
3.
48-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click Login.
After you log in to Oracle SOA Composer, the Oracle SOA Composer home page
appears, as shown in Figure 483:
Figure 483 Oracle SOA Composer Home Page
You must have the SOADesigner application role to access Oracle SOA Composer
metadata. By default, all users with Oracle Enterprise Manager Fusion Middleware
Control administrator privileges have this role. If you log in to Oracle SOA Composer
without this role, you see the following message:
Currently logged in user is not authorized to modify SOA metadata.
For information about adding the SOADesigner application role to users without
administrator privileges, see Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
You can also select a document from the My Edits option that displays recently
opened documents.
Alternatively, you can search for a domain value map by
entering the name of the composite application containing the domain
value map file in the Search composite field and then clicking the
Search icon to the right of the field.
Note:
2.
Select a domain value map and click Open, or just double-click a domain value
map to open it.
The selected domain value map opens in view mode.
To get a direct link to the selected domain value map, click Bookmarkable Link. The
Info button provides more information on the selected domain value map.
48-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
and commit them as described in Section 48.4.1, "How to Save Domain Value Maps at
Runtime" and Section 48.5.1, "How to Commit Changes at Runtime."
2.
2.
3.
2.
3.
48-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Detecting Conflicts
However, if you still want to edit the domain value map, you can click Yes and make
the modifications.
If the other user makes changes to the domain value map and commits the changes,
you receive a notification message while trying to commit your changes.
If you click Yes and commit your changes, then the changes made by the other user are
overwritten by your changes.
Detecting Conflicts
48-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
49
Working with Cross References
49
This chapter describes how to use the cross referencing feature of Oracle SOA Suite to
associate identifiers for equivalent entities created in different applications. It includes
a reference of the XRef functions you can use to populate, view, and maintain entries
in the cross reference tables.
This chapter includes the following sections:
Section 49.8, "Creating and Running the Cross Reference Use Case"
Note:
When you create or update objects in one application, you may also want to propagate
the changes to other applications. For example, when a new customer is created in an
SAP application, you may want to create an entry for the same customer in your
Oracle E-Business Suite application named EBS. However, the applications that you
are integrating may be using different entities to represent the same information. For
example, for each new customer in an SAP application, a new row is inserted in its
Customer database with a unique identifier such as SAP_001. When the same
information is propagated to an Oracle E-Business Suite application and a Siebel
application, the new row should be inserted with different identifiers such as EBS_
1001 and SBL001. In such cases, you need some type of functionality to map these
Working with Cross References 49-1
identifiers with each other so that they can be interpreted by different applications to
be referring to the same entity. This can be done by using cross references.
SAP
EBS
SBL
SAP_001
EBS_1001
SBL001
SAP_002
EBS_1002
SBL002
The identifier mapping is also required when information about a customer is updated
in one application and the changes must be propagated to other applications. You can
integrate different identifiers by using a common value integration pattern, which
maps to all identifiers in a cross reference table. For example, you can add one more
column named Common to the cross reference table shown in Table 491. The updated
cross reference table then appears, as shown in Table 492.
Table 492
SAP
EBS
SBL
Common
SAP_001
EBS_1001
SBL001
CM001
SAP_002
EBS_1002
SBL002
CM002
Figure 491 shows how you can use common value integration patterns to map
identifiers in different applications.
Figure 491 Common Value Integration Pattern Example
Transform SAP
system value to
Common value
SAP
System
Common
View
Transform
Common value
to Siebel System
Transform Siebel
System to
Common value
Cross
Reference
Database
Siebel
System
Transform Common
value to Oracle
E-Business Suite
System value
Transform Oracle
E-Business Suite
System value to
Common value
49-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Oracle
E-Business
Suite System
A cross reference table consists of two parts: metadata and actual data. The metadata is
saved as the .xref file created in Oracle JDeveloper, and is stored in the Metadata
Services (MDS) repository as an XML file. By default, the actual data is stored in the
XREF_DATA table of the database in the SOA Infrastructure database schema. You can
also generate a custom database table for each cross reference entity. The database
table depends on the metadata of the cross reference entity.
Consider the following two cross reference entities:
ORDER with cross reference columns SIEBEL, COMMON, and EBS, as shown in
Table 493
CUSTOMER with cross reference columns EBS, COMMON, and PORTAL, as shown in
Table 494
Table 493
ORDER Table
Column Name
SIEBEL
COMMON
EBS
Column Value
SBL_101
COM_100
EBS_002
COM_110
EBS_012
Column Value
Table 494
CUSTOMER Table
Column Name
EBS
COMMON
PORTAL
Column Value
EBS_201
COM_200
P2002
If you chose to save all the runtime data in one generic table, then the data is stored in
the XREF_DATA table, as shown in Table 495.
Table 495
XREF_DATA Table
XREF_
XREF_TABLE_ COLUMN_
NAME
NAME
ROW_NUMBER VALUE
IS_DELETED
ORDER
SIEBEL
100012345
SBL_101
ORDER
COMMON
100012345
COM_100
ORDER
EBS
100012345
EBS_002
ORDER
COMMON
110012345
COM_110
ORDER
EBS
110012345
EBS_012
CUSTOMER
EBS
200212345
EBS_201
CUSTOMER
COMMON
200212345
COM_200
CUSTOMER
PORTAL
200212345
P2002
The process of adding, removing, and modifying the columns of the cross
reference entities is simple.
The process of creating and deleting cross reference entities from an application is
straightforward.
A large number of rows are generated in the database because each cross reference
cell is mapped to a different row in the database. This reduces the performance of
the queries.
In the generic table, the data for the columns XREF_TABLE_NAME and XREF_
COLUMN_NAME is repeated across a large number of rows.
To overcome these problems, you can generate a custom database table for each cross
reference entity. The custom database tables depend on the metadata of the cross
reference entities. For example, for the XREF_ORDER table and XREF_CUSTOMER table,
you can generate the custom database tables shown in Table 496 and Table 497.
Table 496
XREF_ORDER Table
ROW_ID
SIEBEL
COMMON
EBS
100012345
SBL_101
COM_100
EBS_002
COM_110
EBS_012
110012345
Table 497
XREF_CUSTOMER Table
ROW_ID
EBS
COMMON
PORTAL
200212345
EBS_201
COM_200
P2002
This approach requires you to execute Data Definition Language (DDL) scripts to
generate the custom database tables. For more information about custom database
tables, see Section 49.4.3, "How to Create Custom Database Tables."
2.
3.
Select SOA Tier from the Categories section, and then select Transformations.
4.
5.
Click OK.
The Create Cross Reference(XREF) File dialog is displayed.
6.
In the File Name field, specify the name of the cross reference file. For example,
specify Customer.
A cross reference name is used to uniquely identify a cross reference table. Two
cross reference tables cannot have same name in the cross reference repository. The
cross reference file name is the name of the cross reference table with an extension
of .xref.
7.
In the Description field, enter a description for the cross reference. For example:
Cross reference of Customer identifiers.
8.
9.
Click OK.
The Cross Reference Editor is displayed, as shown in Figure 493. You can use this
editor to modify the cross reference.
49-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Table Name field is editable and you can change the name of the custom
table. The custom database table name should be prefixed with xref_. If you do
not prefix your table name with xref_, then while generating the table, you
receive the following error message:
Table name should begin with xref_ and cannot be xref_data or
xref_deleted_data which are reserved table names for XREF runtime.
2.
3.
Select the Generate Drop DDL checkbox to drop the table and associated indexes,
if a table with the same name already exists. If you select this option and click
Run, then the Running Drop DDL Warning dialog is displayed with the following
message:
Running the Drop DDL will remove the table and indexes, do you want to
continue?
4.
5.
49-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Enter all the required details and click OK. The Connection list of the Run Table
DDL dialog is now populated.
Create the database table in the soainfra schema of the
database.
Note:
7.
Click OK on the Run Table DDL dialog to run the DDL script.
The Table DDL Run Results dialog displays the execution status of your DDL
scripts.
For custom database tables, two additional attributes, namely mode and dbtable, are
added to the schema definition mentioned in Section 49.4.2, "What Happens When
You Create a Cross Reference." They are added for the table element in the following
way:
<attribute name="mode" type="string" default="generic" />
<attribute name="dbtable" type="string" default="xref_data"/>
3.
The XSLT Mapper is displayed when you create an XSL file to transform data from one
XML schema to another. Figure 497 shows how you can select the cross reference
functions in the XSLT Mapper.
49-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A cross reference table must be populated at runtime before using it. By default, the
data is stored in the XREF_DATA table under the SOA Infrastructure database schema.
You can use the xref:populateXRefRow function to populate a cross reference
column with a single value and the xref:populateXRefRow1M function to populate
a cross reference column with multiple values.
You can also store the data in a different database schema by
configuring a data source in the following way:
Note:
EBS
Common
SBL
E100
100
SBL_001
Note:
xref:populateXRefRow Function
Parameters
Table 499
Mode
Description
Exception Reasons
ADD
xref:populateXRefRow("customers.xref"
,"EBS","EBS100", "Common","CM001",
"ADD")
LINK
49-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Exception Reasons
UPDATE
Note:
Mode
Reference Value
Value to be Added
Result
ADD
Absent
Absent
Success
Present
Absent
Exception
Present
Present
Exception
Absent
Absent
Exception
Present
Absent
Success
Present
Present
Exception
Absent
Absent
Exception
Present
Absent
Exception
Present
Present
Success
LINK
UPDATE
The table is populated as shown in Table 4911. Since thread one is committed first,
thread two returns "CM001" to the caller.
Table 4911
EBS
Common
EBS100
CM001
SBL
xref:populateLookupXRefRow Function
Parameters
Note:
Table 4912
Mode
Reference Value
Value to be Added
Result
ADD
Absent
Absent
Success
Present
Absent
Exception
Present
Present
Exception
Absent
Absent
Exception
Present
Absent
Success
Present
Present
Exception
LINK
49-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Usage Notes
When using a custom table approach, you must add the primary constraint on the
columns that must be unique in the cross-reference table. Using Table 4911 as an
example, the SQL statement would be similar to the following:
alter table xref_customer_data add constraint xref_vnx_data_pk
primary key (common, ebs);
Populate the primary constraint columns first and then populate the remaining
columns in subsequent calls.
This function should not be used for inserting cross references for primary objects,
since this could mask data inconsistency issues. Only use the function for
secondary objects to a main dependent object. For example, do not use the
function to determine whether an account already exists when creating customer
accounts; but do use it if the addresses in those customer accounts are being
synchronized.
SAP
EBS
SBL
SAP_001
EBS_1001
SBL001
EBS_1002
SBL002
SAP_0011
SAP_002
xref:populateXRefRow1M Function
Parameters
Table 4914
Mode
Description
Exception Reasons
ADD
xref:populateXRefRow1M("customers.xref","
EBS","EBS_1002", "SAP","SAP_0011","ADD")
Adds the reference value EBS_1002 in the
reference column EBS and the value SAP_0011
in the SAP column.
LINK
xref:populateXRefRow1M("customers.xref","
EBS","EBS_1002", "SAP","SAP_002","LINK")
Links the value SAP_002 in the SAP column to
the EBS_1002 value in the EBS column.
Mode
Reference Value
Value to be Added
Result
ADD
Absent
Absent
Success
Present
Absent
Exception
Present
Present
Exception
Absent
Absent
Exception
Present
Absent
Success
Present
Present
Exception
LINK
3.
4.
49-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
Drag and drop the populateXRefRow function to the line that connects the source
object to the target object.
A populateXRefRow icon appears on the connecting line.
6.
7.
Specify the following values for the fields in the Edit Function populateXRefRow
dialog:
a.
In the xrefLocation field, enter the location URI of the cross reference file.
Click Browse to the right of the xrefLocation field to select the cross reference
file. You can select an already-deployed cross reference from MDS and also
from a shared location in MDS using the Resource Palette.
b.
c.
d.
In the columnName field, enter the name of the cross reference column.
Click the Browse icon to the right of the columnName field to select a column
name from the columns defined for the cross reference you previously
selected.
e.
In the value field, you can manually enter a value or press Ctrl-Space to
launch the XPath Building Assistant.
f.
In the mode field, enter a mode in which you want to populate the cross
reference table column. For example, enter ADD.
You can also click Browse to select a mode. The Select Populate Mode dialog is
displayed from which you can select a mode.
8.
Click OK.
A populated Edit Function populateXRefRow dialog is shown in Figure 499.
xref:lookupXRef Function
Parameters
49-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Exception Reasons
At runtime, an exception can occur for the following reasons:
The cross reference table with the given name is not found.
xref:lookupXRefRow1M Function
Parameters
Order Table
Siebel
Billing1
Billing2
100
101
102
110
111
112
xref:lookupPopulatedColumns Method
<column name="BILLING1">101</column>
<column name="BILLING2">102</column>
In this case, both the columns, Billing1 and Billing2, are populated.
For 1:M mapping, the
xref:lookupPopulatedColumns("Order","Siebel","110","false")
method returns the values shown in Example 498.
Example 498
xref:lookupPopulatedColumns
<column name="BILLING2">111</column>
<column name="BILLING2">112</column>
The cross reference table with the given name is not found.
xref:LookupPopulatedColumns Function
xref:LookupPopulatedColumns(xrefTableName as String,xrefColumnName as
String,xrefValue as String,needAnException as boolean)as node-set
Parameters
Exception Reasons
An exception can occur for the following reasons:
The cross reference table with the given name is not found.
49-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
5.
Drag and drop the lookupXRef function to the line that connects the source object
to the target object.
A lookupXRef icon appears on the connecting line.
6.
Figure 4910
7.
Specify the following values for the fields in the Edit Function lookupXRef
dialog:
a.
In the xrefLocation field, enter the location URI of the cross reference file.
Click Browse to the right of the xrefLocation field to select the cross reference
file. You can select an already deployed cross reference from MDS and also
from a shared location in MDS by using the Resource Palette.
b.
c.
d.
In the columnName field, enter the name of the cross reference column.
Click Browse to the right of the columnName field to select a column name
from the columns defined for the cross reference you previously selected.
e.
8.
Click Browse to the right of needException field. The Need Exception dialog
is displayed. Select Yes to raise an exception if no value is found. Otherwise,
select No.
Click OK.
A populated Edit Function lookupXRef dialog is shown in Figure 4911.
Parameters
xrefColumnName: The name of the column that contains the value to be deleted.
49-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Exception Reasons
An exception can occur for the following reasons:
The cross reference table with the given name is not found.
3.
4.
5.
Drag and drop the markForDelete function to the line that connects the source
object to the target object.
A markForDelete icon appears on the connecting line.
6.
Figure 4912
7.
Specify the following values for the fields in the Edit Function markForDelete
dialog:
a.
In the xrefLocation field, enter the location URI of the cross reference file.
Click the Search icon to the right of the xrefLocation field to select the cross
reference file. You can select an already deployed cross reference from MDS
and also from a shared location in MDS by using the Resource Palette.
b.
In the columnName field, enter the name of cross reference table column.
Click the Search icon to the right of the columnName field to select a column
name from the columns defined for the cross reference you previously
selected.
c.
In the Value field, manually enter a value or press Ctrl-Space to launch the
XPath Building Assistant. Press the up and down keys to locate an object in
the list and press Enter to select that object.
8.
Click OK.
49-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4914
To download the sample files mentioned in this section, see the Oracle SOA Suite
samples page.
49.8.1.1 Task 1: How to Configure the Oracle Database and Database Adapter
To configure the Oracle database and database adapter:
1.
You need the SCOTT database account with password TIGER for this use case. You
must ensure that the SCOTT account is unlocked.
You can log in as SYSDBA and then run the setup_user.sql script available in
the XrefOrderApp1M/sql directory to unlock the account.
2.
3.
4.
5.
6.
<property>
<name>xADataSourceName</name>
<value>jdbc/DBConnection1</value>
</property>
This sample uses eis/DB/DBConnection1 to poll the SAP table for new
messages and to connect to the procedure that simulates Oracle EBS and Siebel
instances.
7.
Package the ra.xml and weblogic-ra.xml files as a RAR file and deploy the
RAR file by using Oracle WebLogic Server Administration Console.
8.
Create a data source using the Oracle WebLogic Server Administration Console
with the following values:
jndi-name=jdbc/DBConnection1
user=scott
password=tiger
url=jdbc:oracle:thin:@host:port:service
9.
connection-factory
factory-class=oracle.jdbc.pool.OracleDataSource
Create a data source using the Oracle WebLogic Server Administration Console
with the following values:
jndi-name=jdbc/xref
user=scott
password=tiger
url=jdbc:oracle:thin:@host:port:service
connection-factory
factory-class=oracle.jdbc.pool.OracleDataSource
2.
In the New Gallery, expand the General node, and select the Applications
category.
3.
4.
In the Application Name field, enter XrefCustApp, and then click Next.
The Name your SOA project page appears.
5.
49-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
From the Composite Template list, select Empty Composite and then click Finish.
The Application Navigator of Oracle JDeveloper is updated with the new
application and project and the SOA Composite Editor contains a blank
composite.
7.
In the Application Navigator, right-click the XrefCustApp project and select New.
2.
In the New Gallery dialog, expand the SOA Tier node, and then select the
Transformations category.
3.
4.
5.
6.
Click OK.
The Cross Reference Editor is displayed.
7.
Click Add.
A new row is added.
8.
Enter SBL_78 as the end system name in the newly added row.
9.
Figure 4915
10. From the File menu, select Save All and close the Cross Reference Editor.
3.
Click Next.
The Service Name page is displayed.
4.
5.
Click Next.
The Service Connection page is displayed.
6.
7.
8.
Click Next.
The Operation Type page is displayed.
9.
Select Poll for New or Changed Records in a Table and click Next.
The Select Table page is displayed.
49-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4916 shows the Logical Delete page of the Adapter Configuration wizard.
Figure 4916
2.
3.
Click Next.
The Service Name page is displayed.
4.
5.
Click Next.
The Service Connection page is displayed.
6.
7.
8.
Click Next.
The Operation Type page is displayed.
9.
49-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4918
Figure 4920 shows the EBS reference in the SOA Composite Editor.
Figure 4920 EBS Reference in SOA Composite Editor
After completing this task, the SOA Composite Editor appears, as shown in
Figure 4921.
Figure 4921 SBL Reference in SOA Composite Editor
49.8.1.6 Task 6: How to Create the Logger File Adapter External Reference
To create the Logger file adapter external reference:
1.
2.
3.
Click Next.
The Service Name page is displayed.
4.
49-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
5.
Click Next.
The Operation page is displayed.
6.
7.
Click Next.
The File Configuration page is displayed.
8.
In the Directory for Outgoing Files (physical path) field, enter the name of the
directory in which you want to write the files.
9.
In the File Naming Convention field, enter output.xml and click Next.
The Messages page is displayed.
Figure 4922 shows the Logger reference in the SOA Composite Editor.
Figure 4922
1.
Drag and drop a Mediator icon from the Component Palette to the Components
section of the SOA Composite Editor.
The Create Mediator dialog is displayed.
2.
3.
Click OK.
An Oracle Mediator with name Mediator1 is created.
4.
5.
6.
Drag and drop another Mediator icon from the Component Palette to the
Components section of the SOA Composite Editor.
The Create Mediator dialog is displayed.
7.
8.
9.
To the right of the WSDL File field, click Find Existing WSDLs.
10. Navigate to and then select the Common.wsdl file. The Common.wsdl file is
49.8.1.8 Task 8: How to Specify Routing Rules for an Oracle Mediator Service
Component
You must specify routing rules for the following operations:
Insert
49-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Update
UpdateID
Delete
2.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
3.
Select Service.
The Target Services dialog is displayed.
4.
5.
6.
7.
8.
Click OK.
9.
element.
The Auto Map Preferences dialog is displayed.
13. From the During Auto Map options, deselect Match Elements Considering their
Ancestor Names.
14. Click OK.
SAP_TO_COMMON_INSERT.xsl Transformation
column name.
22. In the referenceValue column, enter
/top:Sap01Collection/top:Sap01/top:id.
23. In the columnName field, enter "Common" or click Search to select the column
name.
24. In the value field, enter oraext:generate-guid().
25. In the mode field, enter "Add" or click Search to select this mode.
INSERT.xsl file.
The Routing Rules section appears, as shown in Figure 4926.
49-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4926
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
8.
9.
column name.
20. In the referenceValue column, enter
/top:Sap01Collection/top:Sap01/top:id.
21. In the columnName field, enter "COMMON" or click Search to select the column
name.
22. In the needException field, enter true() or click Search to select this mode.
UPDATE.xsl file.
The Routing Rules section appears, as shown in Figure 4928.
Figure 4928 Insert Operation and Update Operation
Perform the following tasks to create routing rules for an updateID operation:
49-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
8.
9.
column name.
20. In the referenceValue column, enter
/top:Sap01Collection/top:Sap01/top:refId.
21. In the columnName field, enter "SAP_01" or click Search to select the column
name.
22. In the value field, enter /top:Sap01Collection/top:Sap01/top:Id.
23. In the mode field, enter "UPDATE" or click Search to select this mode.
24. Drag and drop the lookupXRef function from the Component Palette to the line
column name.
29. In the referenceValue column, enter the following:
xref:populateXRefRow("customer.xref","SAP_
01",/top:Sap01Collection/top:Sap01/top:refId,"SAP_
01",/top:Sap01Collection/top:Sap01/top:id,"UPDATE").
30. In the columnName field, enter "COMMON" or click Search to select the column
name.
31. In the needException field, enter false() or click Search to select this mode.
49-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4930
UPDATEID.xsl file.
The Routing Rules section appears, as shown in Figure 4931.
Figure 4931
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
7.
Click OK.
8.
9.
name.
30. In the value field, enter /top:Sap01Collection/top:Sap01/top:Id.
49-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
SAP_TO_COMMON_DELETE.xsl
32. From the File menu, select Save All and close the SAP_TO_COMMON_
DELETE.xsl file.
The Routing Rules section appears, as shown in Figure 4934.
49.8.1.9 Task 9: How to Specify Routing Rules for the Common Oracle Mediator
You must specify routing rules for the following operations of the Common Oracle
Mediator:
Insert
Delete
Update
UpdateID
2.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
3.
Select Service.
The Target Services dialog is displayed.
4.
5.
6.
7.
8.
Click OK.
A COMMON_TO_SBL_INSERT.xsl file is displayed.
49-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
COMMON_TO_SBL_INSERT.xsl Transformation
11. From the File menu, select Save All and close the COMMON_TO_SBL_
INSERT.xsl file.
12. In the Synchronous Reply section, click Browse for target service operations.
connecting line.
22. Double-click the populateXRefRow icon.
xrefLocation: "customer.xref"
referenceColumnName: "Common"
referenceValue:
$initial.Customers/inp1:Customers/inp1:Customer/inp1:Id
columnName: "SBL_78"
value: /db:OutputParameters/db:X_APP_ID
mode: "LINK"
25. From the File menu, select Save All and close the SBL_TO_COMMON_
INSERT.xsl file.
26. In the Synchronous Reply section, click the Assign Values icon.
routing rules.
49-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4938 shows the insert operation section with SBL and EBS target services.
Figure 4938
Perform the following tasks to create the routing rules for a delete operation.
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
A COMMON_TO_SBL_DELETE.xsl file is displayed.
8.
9.
Click OK.
The transformation is created, as shown in Figure 4939.
10. Drag and drop the lookupXRef function from the Component Palette to the line
xrefLocation: "customer.xref"
referenceColumnName: "Common"
referenceValue: /inp1:Customers/inp1:Customer/inp1:Id
columnName: "SBL_78"
needException: false()
DELETE.xsl file.
15. In the Synchronous Reply section, click Browse for target service operations.
connecting line.
24. Double-click the markForDelete icon.
xrefLocation: "customer.xref"
columnName: "SBL_78"
49-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
value: /db:OutputParameters/db:X_APP_ID
DELETE.xsl file.
28. In the Synchronous Reply section, click the Assign Values icon.
Figure 4941 Delete Operation with SBL and EBS Target Service
Perform the following tasks to create routing rules for the update operation.
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
A COMMON_TO_SBL_UPDATE.xsl file is displayed.
8.
9.
Click OK.
The transformation is created, as shown in Figure 4939.
10. Drag and drop the lookupXRef function from the Component Palette to the line
49-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xrefLocation: "customer.xref"
referenceColumnName: "Common"
referenceValue: /inp1:Customers/inp1:Customer/inp1:Id
columnName: "SBL_78"
needException: true()
UPDATE.xsl file.
15. In the Synchronous Reply section, click Browse for target service operations.
UPDATE.xsl file.
24. In the Synchronous Reply section, click the Assign Values icon.
routing rules.
Figure 4943 shows the update operation section with SBL and EBS target
services.
Figure 4943 Update Operation with SBL and EBS Target Service
Perform the following tasks to create routing rules for the UpdateID operation.
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
49-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
5.
6.
7.
Click OK.
The COMMON_TO_SBL_UPDATEID.xsl file is displayed.
8.
9.
Click OK.
The transformation is created, as shown in Figure 4939.
10. Drag and drop the lookupXRef function from the Component Palette to the line
xrefLocation: customer.xref
referenceColumnName: Common
referenceValue: /inp1:Customers/inp1:Customer/inp1:Id
columnName: SBL_78
needException: false()
UPDATEID.xsl file.
15. In the Synchronous Reply section, click Browse for target service operations.
connecting line.
xrefLocation: customer.xref
referenceColumnName: Common
referenceValue:
$initial.Customers/inp1:Customers/inp1:Customer/inp1:Id
columnName: SBL_78
value: /db:OutputParameters/db:X_APP_ID
mode: UPDATE
UPDATEID.xsl file.
28. In the Synchronous Reply section, click the Assign Values icon.
49-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
37. Repeat Step 1 through Step 36 to specify another target service named EBS and
For detailed information about these steps, see Section 43.7.1, "How to Deploy a Single
SOA Composite in Oracle JDeveloper."
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure and port_number is the port running the service.
To download the sample files mentioned in this section, see the Oracle SOA Suite
samples page.
49.9.1.1 Task 1: How to Configure the Oracle Database and Database Adapter
To configure the Oracle database and database adapter:
1.
You need the SCOTT database account with password TIGER for this use case. You
must ensure that the SCOTT account is unlocked.
You can log in as SYSDBA and then run the setup_user.sql script available in
the XrefOrderApp1M/sql folder to unlock the account.
2.
3.
49-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
5.
6.
This sample uses eis/DB/DBConnection1 to poll the SAP table for new
messages and to connect to the procedure that simulates Oracle EBS and Siebel
instances.
7.
Package the ra.xml and weblogic-ra.xml files as a RAR file and deploy the
RAR file by using Oracle WebLogic Server Administration Console.
8.
Create a data source using the Oracle WebLogic Server Administration Console
with the following values:
jndi-name=jdbc/DBConnection1
user=scott
password=tiger
url=jdbc:oracle:thin:@host:port:service
9.
connection-factory
factory-class=oracle.jdbc.pool.OracleDataSource
Create a data source using the Oracle WebLogic Server Administration Console
with the following values:
jndi-name=jdbc/xref
user=scott
password=tiger
url=jdbc:oracle:thin:@host:port:service
connection-factory
factory-class=oracle.jdbc.pool.OracleDataSource
2.
In the New Gallery, expand the General node, and select the Applications
category.
3.
4.
In the Application Name field, enter XRefOrderApp, and then click Next.
The Name your project page appears.
5.
6.
In the Composite Template list, select Empty Composite and then click Finish.
The Application Navigator of Oracle JDeveloper is updated with the new
application and project and the SOA Composite Editor contains a blank project.
7.
2.
In the New Gallery dialog, expand the SOA Tier node, and then select the
Transformations category.
3.
4.
5.
6.
Click OK.
The Cross Reference Editor is displayed.
7.
Click Add.
A new row is added.
8.
49-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4947
9.
From the File menu, select Save All and close the Cross Reference Editor.
2.
3.
Click Next.
The Service Name page is displayed.
4.
5.
Click Next.
The Service Connection page is displayed.
6.
7.
8.
Click Next.
The Operation Type page is displayed.
9.
Select Poll for New or Changed Records in a Table and click Next.
The Select Table page is displayed.
Figure 4916 shows the Logical Delete page of the Adapter Configuration wizard.
23. Click Next.
49-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
Click Next.
The Service Name page is displayed.
4.
5.
Click Next.
The Service Connection page is displayed.
6.
7.
8.
Click Next.
The Operation Type page is displayed.
9.
49-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4951 shows the EBS reference in the SOA Composite Editor.
Figure 4951
2.
3.
Click Next.
The Service Name page is displayed.
4.
5.
Click Next.
The Adapter Interface page is displayed.
6.
7.
8.
Click Next.
The File Configuration page is displayed.
9.
In the Directory for Outgoing Files (physical path) field, enter the name of the
directory in which you want to write the files.
10. In the File Naming Convention field, enter output.xml and click Next.
Figure 4952 shows the Logger reference in the SOA Composite Editor.
Figure 4952 Logger Reference in SOA Composite Editor
Drag and drop a Mediator icon from the Component Palette to the Components
swimlane.
The Create Mediator dialog is displayed.
2.
3.
Click OK.
An Oracle Mediator with name Mediator2 is created.
4.
49-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4953
5.
6.
Drag and drop a Mediator icon from the Component Palette to the Components
section of the SOA Composite Editor.
The Create Mediator dialog is displayed.
7.
8.
9.
To the right of the WSDL File field, click Find Existing WSDLs.
10. Navigate to and then select the Common.wsdl file. The Common.wsdl file is
49.9.1.8 Task 8: How to Specify Routing Rules for an Oracle Mediator Component
You must specify routing rules for following operations:
Insert
Update
2.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
3.
Select Service.
The Target Services dialog is displayed.
4.
5.
6.
7.
8.
Click OK.
9.
column name.
22. In the referenceValue column, enter
/top:Sap05Collection/top:Sap05/top:id.
23. In the columnName field, enter "Common" or click Search to select the column
name.
24. In the value field, enter orcl:generate-guid().
25. In the mode field, enter "Add" or click Search to select this mode.
49-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
INSERT.xsl file.
The Routing Rules section appears, as shown in Figure 4956.
Figure 4956
Perform the following tasks to create routing rules for the update operation.
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
8.
9.
column name.
20. In the referenceValue column, enter
/top:Sap05Collection/top:Sap05/top:id.
21. In the columnName field, enter "COMMON" or click Search to select the column
name.
22. In the needException field, enter true() or click Search to select this mode.
49-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 4957
UPDATE.xsl file.
The Routing Rules section appears, as shown in Figure 4958.
Figure 4958
49.9.1.9 Task 9: How to Specify Routing Rules for the Common Oracle Mediator
You must specify routing rules for the following operations of the Common Oracle
Mediator:
Insert
Update
1.
2.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
3.
Select Service.
The Target Services dialog is displayed.
4.
5.
6.
7.
8.
Click OK.
A COMMON_TO_EBS_INSERT.xsl file is displayed.
9.
Drag and drop the inp1:Order source element to the db:InputParameters target
element.
The Auto Map Preferences dialog is displayed.
10. Set the value of the db:X_APP_INSTANCE node on the right side to EBS_i75.
Click OK.
The transformation is created, as shown in Figure 4959.
Figure 4959 COMMON_TO_EBS_INSERT.xsl Transformation
11. From the File menu, select Save All and close the COMMON_TO_EBS_
INSERT.xsl file.
12. In the Synchronous Reply section, click Browse for target service operations.
49-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
connecting line.
22. Double-click the populateXRefRow icon.
xrefLocation: order.xref
referenceColumnName: Common
referenceValue:
$initial.Customers/inp1:Customers/inp1:Order/inp1:Id
columnName: EBS_75
value: /db:OutputParameters/db:X_APP_ID
mode: LINK
EBS_TO_COMMON_INSERT.xsl Transformation
25. From the File menu, select Save All and close the EBS_TO_COMMON_
INSERT.xsl file.
26. In the Synchronous Reply section, click the Assign Values icon.
Perform the following tasks to create routing rules for the update operation.
1.
In the Routing Rules section, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2.
Select Service.
The Target Services dialog is displayed.
3.
4.
5.
6.
7.
Click OK.
The COMMON_TO_EBS_UPDATE.xsl file is displayed.
8.
Drag and drop the inp1:Orders source element to the db:InputParameters target
element.
The Auto Map Preferences dialog is displayed.
9.
Click OK.
The transformation is created, as shown in Figure 4939.
10. Drag and drop the lookupXRef function from the Component Palette to the line
49-72 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xrefLocation: order.xref
referenceColumnName: Common
referenceValue: /inp1:Customers/inp1:Order/inp1:Id
columnName: EBS_i75
needException: true()
UPDATE.xsl file.
15. In the Synchronous Reply section, click Browse for target service operations.
UPDATE.xsl file.
24. In the Synchronous Reply section, click the Assign Values icon.
For detailed information about these steps, see Section 43.7.1, "How to Deploy a Single
SOA Composite in Oracle JDeveloper."
49-74 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
50
Defining Composite Sensors
50
This chapter describes how to define composite sensors that provide a method for
implementing trackable fields on messages in a SOA composite application. It
describes how to define sensors on binding components and on service components
that have subscribed to business events. Restrictions are also described.
This chapter includes the following sections:
For information about activity, fault, and variable sensors in a BPEL process, see
Chapter 18, "Using Oracle BPEL Process Manager Sensors."
Functions can only be used with the payload. For example, XPath functions such
as concat() and others cannot be used with properties.
Any composite sensor that uses expressions always captures values as strings.
This action makes the search possible only with the like comparison operator.
Also, even if the value is a number, you cannot use other logical operators such as
<, >, =, and any combination of these.
Composite sensors only support two types of sensor actions: Enterprise Manager
and JMS.
Header-based sensors are only supported for web service bindings.
Sensor actions for Oracle B2B, service data objects (SDOs), web services invocation
framework (WSIF), and Oracle Business Activity Monitoring bindings are not
supported.
Sensor values can only be one of the following types.
1.
2.
STRING
NUMBER
DATE
DATE_TIME
When creating an XPath expression for filtering, all functions that return a node
set must be explicitly cast as a string:
xpath20:upper-case(string($in.request/inp1:updateOrderStatus/inp1:orderStatus)
) = "PENDING"
50-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
b.
Note:
Figure 502 Composite Sensors Dialog for the Selected Service Component
c.
Select the binding component or service component, and click the Add icon.
or
a.
Click the Composite Sensor icon above the SOA Composite Editor, as shown
in Figure 503.
The Composite Sensors dialog for the SOA composite application appears, as
shown in Figure 504. This option displays all the service and reference
binding components and service components with subscribed business events
in the SOA composite application.
50-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
b.
If you selected a service component that has a business event subscription, the
Create Composite Sensor dialog appears as shown in Figure 506.
Figure 506 Create Composite Sensor Dialog for a Service Component
2.
Table 501
Name
Description
Name
Enter a name for the composite sensor. You must enter a name to enable
the Edit icon of the Expression field.
Service
Displays the name of the service. This field is only displayed if you are
creating a composite sensor for a service binding component. This field
cannot be edited.
Service sensors monitor the messages that the service receives from the
external world or from another composite application.
Reference
Displays the name of the reference. This field is only displayed if you are
creating a composite sensor for a reference binding component. This field
cannot be edited.
Reference sensors monitor the messages that the reference sends to the
external world or to another composite application.
Operation
Select the operation for the port type of the service or reference. This field
only displays for service or reference binding components.
Event
Displays the name of the service component. This field is only displayed if
you are creating a composite sensor for a service component. This field
cannot be edited.
Event sensors track composite instances initiated through a business
event. You can create multiple sensors per business event.
Event Type
Displays the Subscribe business event type. This field cannot be edited.
The publish business event type is not supported.
50-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Expression
Click the Edit icon to invoke a dropdown list for selecting the type of
expression to create:
Filter
Click the Edit icon to invoke the Expression Builder dialog to create an
XPath filter for the expression. You must first create an expression to
enable this field.
For example, you may create an expression for tracking purchase order
amounts over 10,000:
$in.inDict/tns:inDict/ns2:KeyValueOfstringstring/ns2:Value >
10000.00
Composite Sensor Displays the supported sensor actions. This feature enables you to store
Actions
runtime sensor data. You can select both Enterprise Manager and either
JMS Queue or JMS Topic.
Enterprise Manager
Select to make runtime sensor data searchable in the Instances tab of
a SOA composite application in Oracle Enterprise Manager Fusion
Middleware Control. This selection is the same as the
DBSensorAction selection of previous releases.
Note: When Enterprise Manager is selected, sensor data is sent to the
trackable fields tables. When it is not selected, data is not sent.
However, in both cases, Oracle Enterprise Manager Fusion
Middleware Control still displays the fields that enable you to search
for composite instances based on that sensor.
For more information, see Oracle Fusion Middleware Administrator's
Guide for Oracle SOA Suite and Oracle Business Process Management
Suite.
JMS Queue
Select to store composite sensor data (XML payload) in a JMS queue.
You must specify the JMS connection factory and queue name.
JMS Topic
Select to store composite sensor data (XML payload) in a JMS topic.
You must specify the JMS connection factory and topic name.
Notes: The JMS Queue and JMS Topic selections enable the composite
sensor data (XML payload) to be used by other consumers, including
Oracle Business Activity Monitoring (BAM) and Oracle Complex Event
Processing (CEP). Both selections use the native JMS support provided
with Oracle WebLogic Server, and not the Oracle SOA Suite JMS adapter
described in Oracle Fusion Middleware User's Guide for Technology Adapters.
You can view JMS messages in the Oracle WebLogic Server
Administration Console.
For information about using sensor data with Oracle BAM, see Chapter 53,
"Integrating Oracle BAM with SOA Composite Applications."
3.
For a service component, a composite sensor icon also displays in the upper right
corner, as shown in Figure 508.
Figure 508 Sensor Icon on Service Component
4.
Place your cursor over the composite sensor icon to display details about the
composite sensor.
50-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
2.
To add a property:
1. Select a normalized message header property to track.
Figure 5011 Properties
2.
50.2.2 What You May Need to Know About Duplicate Composite Sensor Names
Note the following details when using duplicate names for composite sensors.
If you create composite sensors with duplicate names, the entire contents of their
definitions are compared. Duplicate names are permitted where one or more
additional parameters are different (for example, either different configuration
types or different expressions, filters, operation names, and so on). Something
must be different in the definitions for duplicate names to be permitted.
If you have duplicate sensor definitions, only the last executed sensor value is
persisted. Therefore, you can use this type of configuration for mutually exclusive
paths (for example, a composite can be invoked through service 1 or service 2).
Therefore, you can define the same sensor name on both the services. However, if
you define the same names for service 1 and reference 1, only the sensor value
from reference 1 (the last executed sensor) is stored.
You typically use multiple sensors with the same name to point to the same logical
entity extracted from different sources (for example, Oracle Enterprise Manager
Fusion Middleware Control displays the final sensor value). Therefore, it would be
confusing if the same sensor name is used to extract an email value and a social
security value from different sources.
Sensor actions apply to all occurrences of the same sensor name. This situation
means the sensor actions on the most recently defined sensor with the same name
take precedence.
50-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For the scenario shown in sensor.xml in Example 501, the following occurs:
The first two sensors named Service1 are identical. In addition, the
configuration type for both is serviceConfig (composite sensors defined on a
service binding component). Therefore, the sensors become one entry (the second
one is ignored).
The third sensor named Service1 has a different configuration type of
eventConfig (a composite sensor defined on a business event). Therefore, this
sensor is represented with a separate entry.
The two sensors named PurchaseOrder Id have different configuration types
(eventConfig and serviceConfig). Therefore, they are represented with
separate entries.
The two sensors named PurchaseOrder have the same configuration type
(eventConfig), but different expressions. Therefore, they are represented with
separate entries.
Example 501
<sensors xmlns="http://xmlns.oracle.com/bpel/sensor">
<sensor sensorName="Service1" kind="service" target="undefined" filter="">
<serviceConfig service="OrderPublisher_ep"
expression="$in.property.tracking.ecid" operation="execute"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
<sensor sensorName="Service1" kind="service" target="undefined" filter="">
<serviceConfig service="OrderPublisher_ep"
expression="$in.property.tracking.ecid" operation="execute"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
<sensor sensorName="Service1" kind="event" target="undefined" filter=""
xmlns:po="http://www.mycompany.com/ns/order">
<eventConfig component="EventMediator"
expression="$in/po:PurchaseOrder/po:OrderID"
event="{http://mycompany.com/events/orders}OrderReceivedEvent"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
<sensor sensorName="Event1" kind="event" target="undefined" filter="">
<eventConfig component="EventMediator" actionType="Subscribe"
expression="$in.property.tracking.ecid"
event="{http://mycompany.com/events/orders}OrderReceivedEvent"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
<sensor sensorName="PurchaseOrder Id" kind="event" target="undefined" filter=""
xmlns:po="http://www.mycompany.com/ns/order">
<eventConfig component="EventMediator"
expression="$in/po:PurchaseOrder/po:OrderID"
event="{http://mycompany.com/events/orders}OrderReceivedEvent"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
<sensor sensorName="PurchaseOrder Id" kind="service" target="undefined"
filter="">
<serviceConfig service="OrderPublisher_ep"
expression="$in.property.tracking.ecid" operation="execute"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
<sensor sensorName="PurchaseOrder" kind="event" target="undefined" filter=""
xmlns:po="http://www.mycompany.com/ns/order">
<eventConfig component="EventMediator" expression="$in/po:PurchaseOrder"
event="{http://mycompany.com/events/orders}OrderReceivedEvent"
50-11
outputDataType="PurchaseOrder"
outputNamespace="http://mycompany.com/events/orders"/>
</sensor>
<sensor sensorName="PurchaseOrder" kind="event" target="undefined" filter=""
xmlns:po="http://www.mycompany.com/ns/order">
<eventConfig component="EventMediator"
expression="$in/po:PurchaseOrder/po:OrderID"
event="{http://mycompany.com/events/orders}OrderReceivedEvent"
outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
</sensor>
</sensor>
</sensors>
Composite sensor data displays in the flow trace of a SOA composite application.
Composite sensor data can be searched for on the Instances page of a SOA
composite application.
Composite sensors can be searched for on the Instances page of the SOA
Infrastructure.
For more information about searching for composite sensors in Oracle Enterprise
Manager Fusion Middleware Control, see Section "Monitoring and Deleting SOA
Composite Application Instances at the SOA Infrastructure Level" and Section
"Monitoring and Deleting SOA Composite Application Instances from the Application
Home Page" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and
Oracle Business Process Management Suite.
50-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
51
Using Two-Layer Business Process
Management (BPM)
51
This chapter describes how to use two-layer Business Process Management (BPM).
Two-layer BPM enables you to create dynamic business processes whose execution,
rather than being predetermined at design time, depends on elements of the context in
which the process executes. Such elements can include, for example, the type of
customer, the geographical location, or the channel.
To illustrate further, assume you have an application that performs multichannel
banking using various processes. In this scenario, the execution of each process
depends on the channel for each particular process instance.
This chapter includes the following sections:
Phase l
Layer l
Phase ll
Task
1.1
Layer ll
Phase lll
Task
3.1
Task
1.2
Task
2.2
Task
1.3
Task
2.3
Task
3.2
In Figure 511, the phase I activity of the business process can delegate its work to one
of the corresponding layer II processes: Task 1.1, Task 1.2, or Task 1.3.
The two-layer BPM functionality enables you to create the key element (namely, the
phase activity) declaratively.
By using the design time and runtime functionality of Oracle Business Rules, you can
add more channels dynamically without having to redeploy the business process.
Design time at runtime enables you to add rules (columns) to the dynamic routing
decision table at runtime. Then, during runtime, business process instances consider
those new rules and eventually route the requests to a different channel.
The design time at runtime functionality of Oracle Business Rules also enables you to
modify the endpoint reference of a service that is invoked from a phase activity,
pointing that reference to a different service.
You can use the design time at runtime functionality of Oracle
Business Rules through Oracle SOA Composer and the Oracle
Business Rules SDK.
Note:
For information about using Oracle SOA Composer and the Oracle
Business Rules SDK, see:
Oracle Fusion Middleware Java API Reference for Oracle Business Rules
Step
Information
51-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Information
Note:
3.
In the Input and Output Variables section, select the Add icon to add input and
output variables.
4.
Select Add Input Variable. The dialog for selecting a variable appears.
5.
6.
Click OK. The Phase dialog is displayed with the phaseIn variable populated.
7.
From the Input and Output Variables icon, select Add Output Variable. The
dialog for selecting a variable appears.
8.
9.
Click OK. The Phase dialog is displayed with the input and output variable names
populated.
10. Click OK. The Oracle BPEL Designer displays the BPEL process.
11. From the File menu, select Save All.
12. Close the BPEL process.
13. Click the composite.xml link about the Oracle BPEL Designer. The SOA
Artifact
Description
BPEL scope
At the location where the user dropped the phase activity in the BPEL
process, a new BPEL scope is created and inserted into the BPEL process.
The scope has the name of the phase activity. Within the scope, several
standard BPEL activities are created. The most important ones are one
invoke activity to an Oracle Mediator and one receive activity from the
Oracle Mediator.
Oracle Mediator
component
51-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Oracle Business
Rules component
Fact Type Model: The data model used for modeling rules. The rule
dictionary is populated with a fact type model that corresponds to
the input of the phase activity with some fixed data model that is
required as part of the contract between the Oracle Mediator and
Oracle Business Rules service components.
Ruleset: A container of rules used as a grouping mechanism for rules.
A ruleset can be exposed as a service. One ruleset is created within
the rule dictionary.
Decision Table: From an Oracle Business Rules engine perspective, a
decision table is a collection of rules with the same fact type model
elements in the condition and action part of the rules so that the rules
can be visualized in a tabular format. The new decision table is
created within the ruleset.
Decision Service: A decision service is created that exposes the
ruleset as a service of the Oracle Business Rules service component.
The service interface is used by the Oracle Mediator to evaluate the
decision table.
Note:
51.2.4 What You May Need to Know About Creating a Phase Activity
When creating a phase activity, you must know the following:
Rules that you must either configure or create in the decision service. This is based
on data from the payload that you use to evaluate a rule.
For each rule created in the decision service, you must know the corresponding
endpoint URL that must be invoked when a rule evaluates to true. This endpoint
URL is used by the Oracle Mediator to invoke the service in layer 2.
For information on specifying endpoints, see Section 51.4.3, "Creating and Editing
the Dynamic Routing Decision Table."
No transformation, assignment, or validation can be
performed on a payload.
Note:
You can leave the information for the action attribute serviceBindingInfo empty while
modeling the level-2 process phases and complete it after the level-1 process is being
deployed using Oracle SOA Composer.
Once you have created and edited the Dynamic Routing Decision Table, the new
level-1 phase activity appears in the BPEL process in Oracle JDeveloper, as illustrated
in Figure 514.
51-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
51.3.2 What Happens When You Create the Dynamic Routing Decision Table
By creating the Dynamic Routing Decision Table, you are configuring the decision
service to dynamically evaluate the conditions applied to the incoming payload and
give the corresponding routing rules to the Oracle Mediator. The Oracle Mediator then
executes these rules when invoking the service in layer 2.
More specifically, here is what happens at design time when you create the Dynamic
Routing Decision Table:
The rule dictionary is populated with a data model that reflects the data model of
the phase input; that is, the XML schema of the phase input is imported into the
rule dictionary.
2.
a.
Design the SOA composite as described in Section 51.4.1, "Designing the SOA
Composite."
b.
c.
d.
Add assign activities to the BPEL process model as described in Section 51.4.4,
"Adding Assign Activities to the BPEL Process Model."
Click OK. The Create Generic Application wizard displays the first screen.
3.
In the Application Name field, enter BPELPhaseActivity and then click Next.
The second page of the Create Generic Application wizard appears.
4.
5.
In the Project Technologies tab, from the Available section, select SOA and move
it to the Selected section.
6.
Click Next. The third page of the Create Generic Application wizard appears.
7.
From the Composite Template list, select Composite With BPEL Process, and
click Finish.
The Create BPEL Process dialog appears.
8.
9.
10. Import the schema file (for this example, named CustomerData.xsd) into the
project xsd folder. An XML schema definition (XSD) specifies the types of elements
and attributes that may appear in an XML document, their relationship to each
other, the types of data they may contain, and other things.
a.
b.
To the right of the URL field, click the Browse Resources icon.
The SOA Resource Browser appears.
d.
Select File System and, in the Location section, search for the schema file (for
this example, named CustomerData.xsd) in the artifacts/schema folder, then
click OK.
e.
In the Import Schema dialog, ensure the schema file (for this example, named
CustomerData.xsd) now appears in the URL field and the Copy to Project
option is selected, and then click OK.
51-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Localize Files dialog prompts you to import the schema file and any
dependent files.
f.
Deselect the option Maintain original directory structure for imported files
and click OK to import the files.
The Type Chooser dialog appears.
g.
Expand Project Schema Files > schema_file (for this example, named
CustomerData.xsd) > Customer and then click OK, as shown in Figure 516.
11. After importing the schema file, open the CustomerRouterBPELProcess BPEL
process.
To create variables:
Note:
1.
2.
3.
4.
5.
Click the Browse Elements icon. The Type Chooser dialog appears.
6.
Select Project Schema Files > schema_file (for this example, named
CustomerData.xsd) > Customer, and then click OK. The Create Variable dialog
appears with the element name populated.
7.
Click OK. The Variables dialog is displayed with the variable name populated.
8.
Click the Create icon in the Variables dialog. The Create Variable dialog appears.
9.
CustomerData.xsd) > Customer, and then click OK. The Create Variable dialog
appears with the element name populated.
13. Click OK. The Variables dialog appears with the input and output variable names
populated.
14. Click OK. The variables have been created and the CustomerRouterBPELProcess
3.
From the Inputs and Outputs Variables icon, select Add Input Variable. The Add
Input Variable dialog appears.
4.
Select Process > Variables > variable_name (for this example, named phaseIn),
and then click OK. The Phase dialog is displayed with the variable populated.
5.
From the Inputs and Outputs Variables icon, select Add Output Variable. The
Add Output Variable dialog appears.
6.
Select Process > Variables > variable_name (for this example, named
OutputPhaseVar).
7.
Click OK. The Phase dialog displays the input and output variable names.
8.
9.
51-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Click the Edit Dynamic Rules button. The Oracle Business Rules Designer page
appears.
3.
Under Rulesets, click Ruleset_1. The Ruleset_1 page with an empty Routing Table
appears, as shown in Figure 517.
51-11
4.
In DecisionTable_1, click the Add icon, then Action > Assert New. The Actions
section of the table appears.
5.
Drag and drop an Assign activity from the Component Palette into the process
model between the receiveInput activity and the Phase activity. The Assign
activity is added to the process model.
3.
4.
5.
6.
7.
Select the source section. For this example, Variables > Process > Variables >
inputVariable > payload > ns1:Customer is selected.
8.
Select the target section. For this example, Variables > Process > Variables >
inputVariable > payload > ns1:Customer is selected.
9.
Drag the source node to the target node (for example, drag the source
ns1:Customer node to the target ns1:Customer node).
The input copy rule is recorded at the bottom of the Edit Assign dialog, as shown
in Table 513.
Table 513
From
To
inputVariable/payload//ns1:Customer
InputPhaseVar///payload/ns1:Customer
process model between the Phase activity and the replyOutput activity. The new
Assign activity is added to the process model.
12. Double-click the Assign activity. The Assign dialog appears.
13. In the Name field in the General tab, enter AssignOutput.
14. Select the Copy Rules tab.
15. Select the source section. For this example, Variables > Process > Variables >
From
To
OutputPhaseVar///ns1:Customer/ns1:status
outputVariable/payload//client:processRespo
nse/client:result
18. Click OK. The CustomerRouterBPELProcess BPEL process appears after the input
51-13
51-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
52
Integrating the Spring Framework in SOA
Composite Applications
52
This chapter describes how to use the spring framework to integrate components that
use Java interfaces into SOA composite applications. Oracle SOA Suite uses the spring
framework functionality provided by the WebLogic Service Component Architecture
(SCA) of Oracle WebLogic Server. This chapter also describes how to integrate
components that use Java interfaces with components that use WSDL files in the same
SOA composite application. It also describes using Java Architecture for XML Binding
(JAXB) and the EclipseLink O/X-Mapper (OXM) to map Java classes to XML data.
This chapter includes the following sections:
Section 52.4, "Defining Custom Spring Beans Through a Global Spring Context"
Section 52.6, "Spring Service Component Integration in the Fusion Order Demo"
Section 52.8, "Configuring Groovy and Aspectj Classes with the Spring Service
Component"
Section 52.9, "Troubleshooting Spring Errors"
For more information about the WebLogic SCA functionality used by Oracle SOA
Suite, see Oracle Fusion Middleware Developing WebLogic SCA Applications for Oracle
WebLogic Server.
For samples about how to use the spring framework, see the Oracle SOA Suite
samples site.
52-1
Integration of Java and WSDL-Based Components in the Same SOA Composite Application
collection of POJOs plus a spring SCA context file that wires the classes with SCA
services and references.
You can use the spring framework to create service components and wire them within
a SOA composite application using its dependency injection capabilities. SCA can
extend spring framework capabilities as follows:
Publish spring beans as SCA component services that can be accessed by other
SCA components or by remote clients
Provide spring beans for service references wired to services of other components
As with all service components, spring components have a componentType file. The
interfaces defined in the componentType file use the interface.java definition to
identify their service and reference interfaces.
Services are implemented by beans and are targeted in the spring context file.
References are supplied by the runtime as implicit (or virtual) beans in the spring
context file.
You can also integrate Enterprise JavaBeans (EJB) with SOA composite applications
through use of Java interfaces (with no requirement for SDO parameters). For
information, see Chapter 38, "Integrating Enterprise JavaBeans with SOA Composite
Applications."
52-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Integration of Java and WSDL-Based Components in the Same SOA Composite Application
Note:
For example, assume you have a Java interface for a service, as shown in
Example 521.
Example 521
The componentType file for the spring framework lists the PortfolioService
service and the StockQuote service with the interface.java definitions.
Example 523 provides details.
Example 523
componentType File
<componentType xmlns="http://xmlns.oracle.com/sca/1.0">
<service name="PortfolioService ">
<interface.java interface="com.bigbank.PortfolioService"/>
</service>
<reference name="StockService">
<interface.java interface="com.bigbank.StockQuote"/>
</reference>
</componentType>
The implementation class implements the service interface and provides a setter for
the reference interface. Example 524 provides details.
52-3
Integration of Java and WSDL-Based Components in the Same SOA Composite Application
Example 524
The spring context file calls out the services and references and binds them to the
implementation. Example 525 provides details.
Example 525
<beans ...>
<sca:service name="PortfolioService" type="com.bigbank.PortfolioService"
target="impl">
</sca:service>
<sca:reference name="StockService" type="com.bigbank.StockQuote">
</sca:reference>
<bean id ="impl" class ="com.bigbank.PortfolioServiceImpl">
<property name="stockService" ref="StockService"/>
</bean>
</beans>
The composite.xml file of the composite defines the components and references.
Example 526 provides details.
Example 526
<composite ...>
<import location="PortfolioService.wsdl" />
<service name="PortfolioService">
<interface.wsdl
interface="http://bigbank.com/#wsdl.interface(PortfolioService)" />
<binding.ws
port="http://bigbank.com/#wsdl.endpoint(PortfolioService/PortfolioServicePort)"/>
</service>
<wire>
<source.uri>PortfolioService</source.uri>
<target.uri>PortfolioComp/PortfolioService</target.uri>
</wire>
<component name="PortfolioComp">
<implementation.spring src="spring-context.xml"/>
</component>
<wire>
<source.uri>PortfolioService/StockService</source.uri>
<target.uri>StockService</target.uri>
</wire>
<reference name="StockService">
<interface.java interface="com.bigbank.StockQuote"/>
<binding.ejb uri="StockService#com.bigbank.StockQuote"/>
</reference>
52-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</composite>
<sca:service name="StockService"
type="oracle.integration.platform.blocks.java.callback.StockService"
target="impl" />
<sca:reference name="StockServiceCallback"
type="oracle.integration.platform.blocks.java.callback.StockServiceReply" />
Oracle SOA Suite automatically creates a single service (in the spring
componentType file) as shown in Example 528:
Example 528
Single Service
<service name="StockService">
<interface.java
interface="oracle.integration.platform.blocks.java.callback.StockService"
callbackInterface="oracle.integration.platform.blocks.java.callback.StockServiceRe
ply"/>
</service>
52-5
For an overview of spring service component integration in the Fusion Order Demo,
see Section 52.6, "Spring Service Component Integration in the Fusion Order Demo."
In the Name field, enter a name for the spring service component. The name
becomes both the component name and the spring context file name. Figure 522
provides details.
You can also select Use Existing Context and click Browse to select an existing
spring file. For example, you may want to import a spring context that was created
in Oracle JDeveloper, but outside of Oracle SOA Suite. If you browse and select a
spring context from another project, it is copied to the SOA project.
52-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Click OK.
A spring icon is displayed in the SOA Composite Editor.
4.
Double-click the icon to display the contents of the spring context in the spring
editor.
<?xml version="1.0" encoding="windows-1252" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:jee="http://www.springframework.org/schema/jee"
xmlns:lang="http://www.springframework.org/schema/lang"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:sca="http://xmlns.oracle.com/weblogic/weblogic-sca"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/util
http://www.springframework.org/schema/util/spring-util-2.5.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
http://www.springframework.org/schema/jee
http://www.springframework.org/schema/jee/spring-jee-2.5.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang-2.5.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
http://www.springframework.org/schema/tool
http://www.springframework.org/schema/tool/spring-tool-2.5.xsd
http://xmlns.oracle.com/weblogic/weblogic-sca META-INF/weblogic-sca.xsd">
<!--Spring Bean defintions go here-->
</beans>
5.
From the Component Palette, select Weblogic SCA from the dropdown list.
The list is refreshed to display the selections shown in Figure 523.
6.
7.
Complete the fields shown in Table 521 to define the target bean and Java
interface.
52-7
Table 521
Field
Description
name
Enter a name.
target
Enter the target bean. This action enables you to expose the bean
as a service.
Note: Ensure that this target exists. There is no validation
support that checks for the existence of this target.
type
When complete, the Insert Service dialog looks as shown in Figure 524.
Figure 524 Insert Service Dialog
8.
Click OK.
The target bean becomes the service interface in the spring context.
<?xml version="1.0" encoding="windows-1252" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:jee="http://www.springframework.org/schema/jee"
xmlns:lang="http://www.springframework.org/schema/lang"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:sca="http://xmlns.oracle.com/weblogic/weblogic-sca"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/util
http://www.springframework.org/schema/util/spring-util-2.5.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
http://www.springframework.org/schema/jee
http://www.springframework.org/schema/jee/spring-jee-2.5.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang-2.5.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
http://www.springframework.org/schema/tool
http://www.springframework.org/schema/tool/spring-tool-2.5.xsd
http://xmlns.oracle.com/weblogic/weblogic-sca META-INF/weblogic-sca.xsd">
<!--Spring Bean defintions go here-->
<sca:service name="scaserv1" target="ep"
type="oracle.mypackage.myinterface"/>
</beans>
52-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If you close the spring editor and return to the SOA Composite Editor, you see
that a handle has been added to the left side of the spring service component, as
shown in Figure 525.
Figure 525 Service Handle
9.
10. Drag a Reference icon from the list shown in Figure 523 into the spring editor.
Field
Description
name
Enter a name.
type
When complete, the spring context displays the service and reference in the spring
editor.
<?xml version="1.0" encoding="windows-1252" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:jee="http://www.springframework.org/schema/jee"
xmlns:lang="http://www.springframework.org/schema/lang"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:sca="http://xmlns.oracle.com/weblogic/weblogic-sca"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/util
http://www.springframework.org/schema/util/spring-util-2.5.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
http://www.springframework.org/schema/jee
http://www.springframework.org/schema/jee/spring-jee-2.5.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang-2.5.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
http://www.springframework.org/schema/tool
http://www.springframework.org/schema/tool/spring-tool-2.5.xsd
http://xmlns.oracle.com/weblogic/weblogic-sca META-INF/weblogic-sca.xsd">
<!--Spring Bean defintions go here-->
<sca:service name="scaserv1" target="ep"
52-9
type="oracle.mypackage.myinterface"/>
<sca:reference name="scaref1" type="external.bean.myInterface"/>
</beans>
12. Close the spring context file, as shown in Figure 526.
Figure 526 Spring Context File
A handle is added to the right side of the spring service component, as shown in
Figure 527.
Figure 527 Reference Handle
13. Drag the left handle into the Exposed Services swimlane to create a service
You are prompted to select to expose the service as either a web service or as an
EJB service, as shown in Figure 529.
52-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
EJB: This exposes the EJB service through a Java interface; this selection does
not require the use of a WSDL file.
Web Service: This exposes the web service through a SOAP WSDL interface.
If you select this option, a WSDL is generated from the Java Interface for
compatibility with the spring service component.
14. Select to expose this service as either an EJB or web service. A service is
automatically created in the Exposed Services swimlane and wired to the spring
service component (for this example, EJB is selected). Figure 5210 provides
details.
Figure 5210
15. Double-click the EJB service to display the automatically completed configuration,
as shown in Figure 5211. The configuration details were created from the values
you entered in the Insert Service dialog in Step 7.
52-11
16. Replace the default JNDI name that was automatically generated with the name
the External References swimlane and wired to the spring service component (for
this example, EJB is selected). Figure 5212 provides details.
Figure 5212 EJB Reference Binding Component Wired to the Spring Service
Component
52-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 5213
21. Close the dialog and return to the SOA Composite Editor, as shown in
Figure 5214.
Figure 5214
22. Place the cursor over both the right handle of the service (as shown in
Figure 5215) and the left handle of the spring service component (as shown in
Figure 5216). The Java interface is displayed.
Figure 5215
52-13
23. Perform the same action on the right handle of the spring service component and
the left handle of the reference binding component to display its Java interface.
24. If you want to view the interfaces for the spring service component in the
componentType file, select this file in the Application Navigator. The interfaces
for both components are defined by interface.java.
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SOA Modeler version 1.0 at [2/27/10 1:13 PM]. -->
<componentType
xmlns="http://xmlns.oracle.com/sca/1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ui="http://xmlns.oracle.com/soa/designer/">
<service name="scaserv1">
<interface.java interface="oracle.mypackage.myinterface"/>
</service>
<reference name="scaref1">
<interface.java interface="external.bean.myInterface"/>
</reference>
</componentType>
25. In the Application Navigator, select the composite.xml file to display similar
details.
<service name="scaserv1">
<interface.java interface="oracle.mypackage.myinterface"/>
<binding.ejb uri="scaserv1_ejb_ep" ejb-version="EJB3"/>
</service>
<component name="MySpring">
<implementation.spring src="MySpring.xml"/>
</component>
<reference name="scaref1">
<interface.java interface="external.bean.myInterface"/>
<binding.ejb uri="scaref1_ejb_ep" ejb-version="EJB3"/>
</reference>
<wire>
<source.uri>orderprocessor_client_ep</source.uri>
<target.uri>OrderProcessor/orderprocessor_client</target.uri>
</wire>
<wire>
<source.uri>scaserv1</source.uri>
<target.uri>MySpring/scaserv1</target.uri>
</wire>
<wire>
<source.uri>MySpring/scaref1</source.uri>
<target.uri>scaref1</target.uri>
</wire>
</composite>
26. If you wire the right handle of the spring service component to an XML-based
52-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Drag the right handle of the spring service component to the Oracle Mediator,
as shown in Figure 5217.
Figure 5217
b.
Figure 5218
52-15
c.
Place the cursor over both the right handle of the spring service component (as
shown in Figure 5220) and the left handle of the Oracle Mediator (as shown
in Figure 5221) to display the compatible interface.
d.
52-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about integrating components that use Java interfaces with
components that use WSDL files in the same SOA composite application, see
Section 52.6, "Spring Service Component Integration in the Fusion Order Demo."
Notes:
52.3.2 What You May Need to Know About Java Class Errors During Java-to-WSDL
Conversions
When a Java-to-WSDL conversion fails because of a bad Java class and you modify the
Java code to correct the problem, you must restart Oracle JDeveloper. Not doing so
results in a Java-to-WSDL conversion failure because the new class is not reloaded.
52.4.1 How to Define Custom Spring Beans Through a Global Spring Context
To define custom spring beans through a global spring context:
1. Add the custom spring bean definitions into the following file:
SOA_HOME/soa/modules/oracle.soa.ext_11.1.1/classes/
springse-extension-global-beans.xml
2.
Add the corresponding classes in either the lib directory (as a JAR file) or the
classes directory (as extracted files of the JAR file).
SOA_HOME/soa/modules/oracle.soa.ext_11.1.1/lib | classes
For more information, see the readme.txt file located in the following directory:
SOA_HOME/soa/modules/oracle.soa.ext_11.1.1
Note:
beans.
52-17
loggerBean: For providing context-aware logging messages. You can define the
logger handler and configure the logging level for the handler in Oracle Enterprise
Manager Fusion Middleware Control. The logger is named
oracle.integration.platform.blocks.java.beans.impl. For more
information, see Section "Configuring Log Files" of Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management
Suite.
The predefined spring beans are automatically injected into the spring service
component. However, you must explicitly integrate the predefined spring beans into a
SOA composite application by providing a reference to the bean in the spring context
file.
For an example of how to reference loggerBean and headerHelperBean in a
spring context file, see Section 52.5.4, "How to Reference Predefined Spring Beans in
the Spring Context File."
IHeaderHelperBean.java Interface
package oracle.soa.platform.component.spring.beans;
/**
* Interface for getting and setting header properties.
* These properties will be set on the normalized message - and passed on
* to the respective reference that the local reference is wired to on
* composite level.
* <br/>
* To use this bean from within your context, declare property
* with ref="headerHelperBean". E.g.
* <property name="headerHelper" ref="<b>headerHelperBean</b>"/>
*/
public interface IHeaderHelperBean
{
/**
* Get a property from the normalized message header. Note that these
* properties are defined, and are the same ones, one can get/set via
* mediator or bpel process
* @param pKey the property key, case sensitive
* @return the value, or null in case not found
*/
public String getHeaderProperty (String pKey);
/**
* Set a property on the normalized message header. Note that these
* properties are defined, and are the same ones, one can get/set via
* mediator or bpel process
* @param pKey the property key, case sensitive
* @param pValue the value to be set
52-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
*/
public void setHeaderProperty (String pKey, String pValue);
}
52-19
/**
* Logger bean interface, messages will be logged as
* [<composite instance id>/<component instance id>] <message>
* <br/>
* To use this bean from within your context, declare property
* with ref="loggerBean". E.g.
* <property name="logger" ref="<b>loggerBean</b>"/>
*/
public interface ILoggerBean
{
/**
* Log a message, with Level.INFO
* @param message
*/
public void log (String message);
/**
* Log a message with desired level
* @param pLevel the log level
* @param message the message to log
*/
public void log (Level pLevel, String message);
/**
* Log a throwable with the desired level
* @param level the level to log with
* @param message the message
* @param th the exception (throwable) to log
*/
public void log (Level level, String message, Throwable th);
}
52.5.4 How to Reference Predefined Spring Beans in the Spring Context File
You create references to the predefined beans in the spring context file.
To reference predefined spring beans in the spring context file:
1. Open the spring context file in Source view in Oracle JDeveloper.
2.
52-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<sca:service name="IInternalPartnerSupplier"
target="InternalPartnerSupplierMediator"
type="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
<!-- expose the InternalPartnerSupplierMediator + Mock as service
<service name="IInternalPartnerSupplierSimple">
<interface.java
interface="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
</service>
-->
<sca:service name="IInternalPartnerSupplierSimple"
target="InternalPartnerSupplierMediatorSimple"
type="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
<!-- the partner supplier mediator bean with the mock ep -->
<bean id="InternalPartnerSupplierMediatorSimple"
class="com.otn.sample.fod.soa.internalsupplier.InternalSupplierMediator"
scope="prototype">
<!-- inject the external partner supplier bean -->
<property name="externalPartnerSupplier"
ref="IExternalPartnerSupplierServiceMock"/>
<!-- inject the quoteWriter -->
<property name="quoteWriter" ref="WriteQuoteRequest"/>
<!-- context aware logger, globally available bean [ps3] -->
<property name="logger" ref="loggerBean"/>
<!-- headerHelper bean -->
<property name="headerHelper" ref="headerHelperBean"/>
</bean>
<!-- the partner supplier mediator bean with the ejb -->
<bean id="InternalPartnerSupplierMediator"
class="com.otn.sample.fod.soa.internalsupplier.InternalSupplierMediator"
scope="prototype">
<!-- inject the external partner supplier bean -->
<property name="externalPartnerSupplier"
ref="IExternalPartnerSupplierService"/>
<!-- inject the quoteWriter -->
<property name="quoteWriter" ref="WriteQuoteRequest"/>
<!-- context aware logger, globally available bean [ps3] -->
<property name="logger" ref="loggerBean"/>
<!-- headerHelper bean -->
<property name="headerHelper" ref="headerHelperBean"/>
</bean>
. . .
. . .
This syntax is included in the spring context file of the Partner Supplier Composite
application of the Fusion Order Demo. For more information about the Fusion
Order Demo, see Section 52.6, "Spring Service Component Integration in the
Fusion Order Demo."
52-21
52-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
External
References
target
InternalPartnerSupplierMediator
IExternalPartnerSupplier
Service (implements the
EJB interface)
(sca:service)
(sca:reference)
Inject the quote writer
property name=
quoteWriter
IExternalPartnerSupplierService
(EJB)
WriteQuoteRequest
(sca:reference)
WriteQuoteRequest
(file)
Bean
IInternalPartner- target
SupplierSimple
Quotes >
3000
(sca:service)
InternalPartnerSupplierMediatorSimple
IExternalPartnerSupplierServiceMock
(implements the EJB interface)
52-23
throws InternalSupplierException;
}
52-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
-->
<sca:service name="IInternalPartnerSupplier"
target="InternalPartnerSupplierMediator"
type="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
<!-- expose the InternalPartnerSupplierMediator + Mock as service
<service name="IInternalPartnerSupplierSimple">
<interface.java
interface="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
</service>
-->
<sca:service name="IInternalPartnerSupplierSimple"
target="InternalPartnerSupplierMediatorSimple"
type="com.otn.sample.fod.soa.internalsupplier.IInternalPartnerSupplier"/>
<!-- the partner supplier mediator bean with the mock ep -->
<bean id="InternalPartnerSupplierMediatorSimple"
class="com.otn.sample.fod.soa.internalsupplier.InternalSupplierMediator"
scope="prototype">
<!-- inject the external partner supplier bean -->
<property name="externalPartnerSupplier"
ref="IExternalPartnerSupplierServiceMock"/>
<!-- inject the quoteWriter -->
<property name="quoteWriter" ref="WriteQuoteRequest"/>
<!-- context aware logger, globally available bean [ps3] -->
<property name="logger" ref="loggerBean"/>
<!-- headerHelper bean -->
<property name="headerHelper" ref="headerHelperBean"/>
</bean>
<!-- the partner supplier mediator bean with the ejb -->
<bean id="InternalPartnerSupplierMediator"
class="com.otn.sample.fod.soa.internalsupplier.InternalSupplierMediator"
scope="prototype">
<!-- inject the external partner supplier bean -->
<property name="externalPartnerSupplier"
ref="IExternalPartnerSupplierService"/>
<!-- inject the quoteWriter -->
<property name="quoteWriter" ref="WriteQuoteRequest"/>
<!-- context aware logger, globally available bean [ps3] -->
<property name="logger" ref="loggerBean"/>
<!-- headerHelper bean -->
<property name="headerHelper" ref="headerHelperBean"/>
</bean>
<!-- mock bean for the IExternalPartnerSupplierService -->
<bean id="IExternalPartnerSupplierServiceMock"
class="com.otn.sample.fod.soa.externalps.test.MockExternalPartnerSupplierTest"/>
<!-Use a reference from the outside world based on the
IExternalPartnerSupplierService interface.
The below is specified on the SpringPartnerSupplierMediator.componentType and wired to an external EJB binding.
52-25
<reference name="IExternalPartnerSupplierService">
<interface.java
interface="com.otn.sample.fod.soa.externalps.IExternalPartnerSupplierService"/>
</reference>
-->
<sca:reference name="IExternalPartnerSupplierService"
type="com.otn.sample.fod.soa.externalps.IExternalPartnerSupplierService"/>
<!-<reference name="WriteQuoteRequest">
<interface.java
interface="writequoterequest.partnersuppliercomposite.weblogicfusionorderdemo.file
.adapter.pcbpel.com.oracle.xmlns.Write_ptt"/>
</reference>
-->
<sca:reference
type="writequoterequest.partnersuppliercomposite.weblogicfusionorderdemo.file.adap
ter.pcbpel.com.oracle.xmlns.Write_ptt"
name="WriteQuoteRequest"/>
</beans>
For information on downloading and installing the Fusion Order Demo and using the
Partner Supplier Composite, see Section 3.2, "Setting Up the Fusion Order Demo
Application."
After download, see the following Fusion Order Demo directory for Java code samples
used by the Partner Supplier Composite:
CompositeServices\PartnerSupplierComposite\src\com\otn\sample\fod\soa
2.
Create an EJB binding reference based on the Java interface class and the JNDI
name. Figure 5225 provides an example.
52-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 5225
3.
Wire the EJB reference to the spring service component, as shown in Figure 5226.
Figure 5226
A new reference is created in the spring context file. Figure 5227 provides details.
Figure 5227
4.
Enable spring to inject the reference into the class by declaring a public member of
type IExternalPartnerSupplierService. Figure 5228 provides details.
52-27
5.
For design information about external metadata for JAXB mappings, visit the
following URL:
http://wiki.eclipse.org/EclipseLink/DesignDocs/277920
For information about JAXB OXM and the OXM mapping file
(eclipselink-oxm.xsd), visit the following URLs:
52-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
http://wiki.eclipse.org/EclipseLink/FAQ/WhatIsMOXy
http://wiki.eclipse.org/EclipseLink/Examples/MOXy
http://wiki.eclipse.org/Category:XML
You can also map Java classes to XML data when integrating an EJB with SOA
composite applications. For more information, see Chapter 38, "Integrating Enterprise
JavaBeans with SOA Composite Applications."
When you cannot add the JAXB annotations into the Java source and must specify
them separately
When scenarios are not covered by JAXB (for example, with top level elements like
method return types or parameter types)
The external JAXB annotations can be specified either directly in the EXM file or
included in the separate TopLink JAXB mapping OXM file that can be referred to from
the EXM file.
The EXM file name must match the Java class name and reside in the same package
location. For example, if the Java class is named
pack1.pack2.myJavaInterface.class, the EXM file must be named
pack1/pack2/myJavaInterface.exm.
Oracle SOA Suite design time supports placing the EXM file in either the source path
(SCA-INF/src) or the class path (SCA-INF/classes or a JAR in SCA-INF/lib).
Placing the EXM file in the source path (SCA-INF/src) enables you to edit the EXM
using Oracle JDeveloper (files in the class path do not appear in the Application
Navigator in Oracle JDeveloper). When project compilation is complete, the EXM file
(and any XML files that it imports) is copied to the class path (SCA-INF/classes) for
deployment. If the EXM file is in the source path, it must still be in the same
corresponding directory structure.
If you place the EXM (and OXM) files in SCA-INF/src, ensure that your Oracle
JDeveloper project is configured so that SCA-INF/src is the default source directory
(right-click the project name, and select Project Properties > Java Source Paths). EXM
files can also be found in JAR files that are in the project's class path.
When you drag and drop a Java interface (Enterprise JavaBeans) to a BPEL process,
Oracle SOA Suite checks to see if the EXM file exists. If it does, it is passed to the web
services java2wsdl API.
After the WSDL file is generated, an informational message is displayed. If an EXM
file was used, the message displayed takes the following format:
The WSDL file {0} was generated based on the JAVA class {1} using extended mapping
file {2}
52-29
The EXM schema file for external mapping metadata for the data binding framework
is available at the following URL:
http://www.oracle.com/technology/weblogic/weblogic-wsee-databinding/1.1
/weblogic-wsee-databinding.xsd
The data defines the attributes of a particular Java web service endpoint. This schema
defines three types of XML constructs:
When a construct is the direct analog of a JAX-WS, JSR-181, or JAXB annotation, the
comment in the schema contains a notation such as:
Corresponding Java annotation: javax.jws.WebParam.Mode
52-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
52.8 Configuring Groovy and Aspectj Classes with the Spring Service
Component
If you configure a Groovy or Aspectj class in the spring configuration file, you must
follow these conventions:
Using a relative file path is not possible because the SCA package is not treated as
a regular JAR file for the class loader. For example, the following classpath
protocol indicates to find the Groovy file from the class path.
script-source="classpath:service/GroovyGreeter.groovy"
Add Groovy and Aspectj files in any of the following directories when using the
classpath protocol. No other directories are possible.
SCA-INF/classes
SCA-INF/lib
If your build scripts are configured to clean the classes directory, either put the
Groovy files in the SCA-INF/lib directory or design your build scripts to prevent
cleaning.
Add spring extension JAR file libraries for Groovy or Aspectj to the class path of
the managed servers setDomainENV.sh or setDomainENV.bat file and restart
the server. This ensures that deployment is successful. The restart is required
because spring uses Java reflection to instantiate aspect-oriented programming
(AOP). The use of reflection restricts the search for classes to the system class
loader. Any changes to the system class loader require a server restart.
Ensure that you deploy the JAR file containing the class into the SCA-INF/lib
directory or the classes into the SCA-INF/classes directory of the SAR file.
52-31
52-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part X
Part X
53
53
This chapter describes how to integrate Oracle Business Activity Monitoring (Oracle
BAM) Adapter with SOA composite applications in Oracle JDeveloper to capture
BPEL process metrics using activity monitors, and monitoring objects such as
counters, business indicators, and intervals. It explains how to use Oracle BAM
Monitor Express to track Key Performance Indicators (KPIs) and describes in detail the
Monitor Express data objects that capture data about deployed BPEL processes.
Information about integrating BPEL sensors with Oracle BAM sensor actions to
publish event-based data is also provided.
This chapter includes the following sections:
Section 53.3, "Using Oracle BAM Monitor Express With BPEL Processes"
Section 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action"
Section 53.8, "Integrating SOA Applications and Oracle BAM Using Enterprise
Message Resources"
The Oracle BAM Adapter transfers data from BPEL process monitors to
automatically generated Oracle BAM data objects. See Section 53.3, "Using Oracle
BAM Monitor Express With BPEL Processes" for more information.
The Oracle BAM Adapter can be used as a reference binding component in a SOA
composite application. For example, Oracle Mediator can send data to Oracle
BAM using the Oracle BAM Adapter. See Section 53.5, "Using Oracle BAM
Adapter in a SOA Composite Application" for more information.
The Oracle BAM Adapter can also be used as a partner link in a Business Process
Execution Language (BPEL) process to send data to Oracle BAM as a step in the
process. See Section 53.6, "Using Oracle BAM Adapter in a BPEL Process" for more
information.
Oracle BAM sensor actions (which use Oracle BAM Adapter) can be included
within a BPEL process to publish event-based data to the Oracle BAM data objects.
See Section 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action" for
more information.
JMS sensor actions on BPEL sensors can feed data to Oracle BAM, and circumvent
Oracle BAM Adapter. See Section 53.8, "Integrating SOA Applications and Oracle
BAM Using Enterprise Message Resources" for more information.
JMS sensor actions at the SOA composite application level can feed data to Oracle
BAM. See Chapter 50, "Defining Composite Sensors" for more information.
53-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Activity Monitors and Monitoring Objects are used to capture BPEL process metrics,
which are sent to Oracle BAM Server, and then used for analysis and graphic display.
All of the connection, design, and deployment configuration is accomplished in Oracle
JDeveloper.
Monitor Express ships with sample dashboards to demonstrate solutions you can
build on top of the automatically deployed data objects. You can also build custom
dashboards on the data objects generated by Monitor Express using Oracle BAM
Active Studio or with Oracle BAM data controls in an ADF application.
Using the BPEL Designer Monitor view in Oracle JDeveloper, you can create the
following types of monitors on a BPEL process:
Activity Monitors capture running time data for BPEL process activities, scopes,
and human tasks. Activity Monitors can help identify bottlenecks in the BPEL
process. See Section 53.3.2, "How to Configure Activity Monitors" for more
information.
Counter monitoring objects capture the date and time when a particular BPEL
activity event is encountered within the BPEL process. Counters may be useful for
reporting the number of times a particular activity is executed over a period. See
Section 53.3.4, "How to Configure Counters" for more information.
Interval monitoring objects capture the amount of time for the process to go from
one BPEL activity event to another. Interval monitoring objects can help identify
bottlenecks in the BPEL process. See Section 53.3.5, "How to Configure Intervals"
for more information.
When the SOA composite application is deployed, the Oracle BAM data objects
corresponding to the BPEL process monitors are created or updated automatically.
Related Documentation
Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring
While in Monitor view, the Structure window displays the Monitoring Objects folder.
You can expand the folder to expose the Business Indicators, Intervals, and Counters
folders.
53-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
2.
The All Activities option captures start and end time data for every activity in
the BPEL process, including individual activities, scopes, and human tasks. An
activity starts when the activation event for the activity is begun, and it ends
when the completion event is finished.
The Scopes and Human Tasks Only option captures start and end time data
for every scope and human task defined in the BPEL process. A scope starts
when the first activity activation event within the scope is begun, and it ends
when the final activity completion event within the scope is finished. A
human task activity starts when the activation event for the human task
activity is begun, and it ends when the completion event in the human task
activity is finished.
The Human Tasks Only option captures start and end time data for every
human task activity defined in the BPEL process.
The BPEL Process Only option captures start and end time data for the BPEL
process.
You can disable Activity Monitors by deselecting the Enable Activity Monitoring
checkbox.
3.
Click OK.
If Activity Monitors are enabled, data is sent to Oracle BAM data objects at
runtime. See Section 53.3.10, "What You Need To Know About Monitor Express
Data Objects" for more information about Oracle BAM data objects for monitoring
objects.
Alternatively, you can use the Monitoring Objects menu, located at the top left
corner of the BPEL Designer window, to create monitoring objects.
As another alternative, you can open a context menu for each Monitoring Objects
type folder in the Structure window to create a monitoring object.
2.
To enable the BPEL process monitoring objects at run time, verify that the Enable
Monitoring checkbox, located at the top left corner of the BPEL Designer Monitor
view, is selected. Figure 532 provides details.
53-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When checked, the Enable Monitoring option in BPEL Designer enables all of the
monitors and sensors in all BPEL processes in the current SOA composite
application. It overrides any monitoring object-level enable flags.
When the Enable Monitoring option is not checked, a property called
enableProcessSensors is added to composite.xml with the value false.
That property disables all monitors and sensors in all BPEL processes in the
current SOA composite application.
The Enabled checkbox enables or disables this particular monitoring object. If it is not
enabled, the Counter is not evaluated during the BPEL process, therefore no data is
sent to Oracle BAM.
To attach a snapshot of a Counter to a BPEL activity, click the Add icon in the Counter
dialog. Then select an activity from the list.
Next, choose an evaluation event (an event within the activity), by clicking the
browsing icon.
The Evaluation Event Chooser dialog opens to let you select one or more evaluation
events.
The Counter and its snapshot are represented in the Structure window.
53-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Enabled checkbox enables or disables this particular monitoring object. If it is not
enabled, the Interval is not evaluated during the BPEL process, therefore no data is
sent to Oracle BAM.
The Start Activity defines the beginning of the Interval. Select a Start Activity from
the list, and a single selection in the Evaluation Events list.
End Activity defines the end of the Interval. Select an End Activity from the list, and a
single selection in the Evaluation Events list.
You can select Associated References if a Business Indicator has been previously
defined in the BPEL process. Selecting an associated indicator automatically provides
two snapshots on the selected Business Indicator. This captures the Business Indicator
metrics at the start and at the end of the Interval.
Note: If you plan to include an associated indicator snapshot in the
Interval, it is not recommended to use the main or receiveInput
activities at the Activate evaluation event as the start or end points,
because the variables in the XPath expression might not yet be
populated.
On execution, the Interval start and end times are sent to Oracle BAM as a new record
in a data object. See Section 53.3.10, "What You Need To Know About Monitor Express
Data Objects" for information about the Oracle BAM data objects.
An empty Interval, one in which the start and end activities and evaluation events are
the same, is valid, and it can label Business Indicator snapshots. The Interval can
uniquely identify multiple snapshots for a single Business Indicator. Instead of
configuring snapshots in the Business Indicator dialog, you can create an empty
Interval for each snapshot you want to create for a Business Indicator, and select the
Business Indicators indicator reference in each Interval.
53-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Enabled checkbox enables or disables this particular monitoring object. If it is not
enabled, the configured expression in the Business Indicator is not evaluated during
the BPEL process, therefore no data is sent to Oracle BAM.
Metrics are defined to evaluate an expression or variable when the events specified in
the Business Indicator are encountered in the BPEL process.
Click the green plus icon to configure a metric. Metrics have a name, data type, and
XPath expression.
You can enter an expression directly in the XPath field, or click Edit to open the Metric
configuration dialog, then click Edit to use the Expression Builder.
53-11
Snapshots associate the Business Indicator with activities in the BPEL process. The
snapshot tells the BPEL process at what point to evaluate the Business Indicator
metrics. To create a snapshot, click the green plus icon.
Note:
Evaluation Events indicate at what point during the activity to evaluate the Business
Indicator metrics. Select a Snapshot in the table and click Edit to select one or more
evaluation events. You can pick multiple evaluation events within the BPEL activity on
which to evaluate the metric.
Configuring a snapshot on the main or receiveInput
activities at the Activate evaluation event is not recommended
because the variables in the XPath expression might not yet be
populated.
Note:
When the configuration is saved, a Business Indicator icon is displayed in the top right
corner of the associated activity in the BPEL process diagram.
53-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Business Indicator is also represented in the Structure window with its metrics
and snapshots.
2.
3.
Select one or more monitoring objects in the dialog and click OK. Press Shift-click
to select multiple monitoring objects.
53-13
4.
53-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
53-15
Table 531
Property
Default
Description
dataObjectsFolder
/Samples/Monitor
Express/
adapterConnectionFactoryJNDI eis/bam/rmi
batch
true
deploymentProtocol
http
53-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Default
Description
ignoreErrors
true
53.3.9 What You Need to Know About Using the Monitor Express Dashboard
Oracle BAM provides a sample dashboard that you can use to monitor your BPEL
process out of the box.
The Monitor Express dashboard and data object samples allow users to enable Oracle
BAM for your SOA composite applications in relatively few steps from within Oracle
JDeveloper. The ready-to-use dashboards provide a single integrated view to track Key
Performance Indicators (KPIs) in real-time and promote operational efficiency. The
rich user experience for monitoring is delivered by BPEL Monitor instrumentation in
Oracle JDeveloper.
The data objects are located in the Samples/Monitors/ data object directory in
Oracle BAM Architect, and the sample reports are located in the Shared
Reports/Samples/Monitor Express/ folder in Oracle BAM Active Viewer.
If the samples are not installed on your system, the installation script and instructions
are located in the SOA_ORACLE_HOME/bam/samples/bam/monitorexpress
directory.
53.3.10 What You Need To Know About Monitor Express Data Objects
Oracle BAM data objects are deployed automatically when a SOA composite
application containing enabled BPEL process monitors is deployed. Preseeded sample
data objects are present in the Samples/Monitor Express/ directory.
You can use these data objects to construct Oracle BAM dashboards. See Oracle Fusion
Middleware User's Guide for Oracle Business Activity Monitoring for information about
creating dashboards in Oracle BAM Active Studio.
You can add columns and indexes to the data objects using Oracle BAM Architect. The
custom columns and indexes you add in Oracle BAM Architect are preserved when a
revised SOA composite application containing changes to BPEL process monitor
configuration is deployed. See Chapter 55, "Defining and Managing Oracle BAM Data
Objects" for information about adding columns and indexes.
If a data object already exists in the configured location at deployment time, it is used
as is, or updated with the appropriate additional columns to accommodate messages
from the BPEL process monitors.
53-17
Oracle BAM data objects cannot be changed if they are in use. If there are Oracle BAM
dashboards open against BPEL process monitor data objects, and the data objects
require changes upon deployment, the data object updates fail.
Note:
names.
Oracle BAM Adapter Configuration
BPEL process monitors use Oracle BAM Adapter to convey messages to Oracle BAM
Server. At deployment time, if Oracle BAM Server is unreachable, deployment fails. If
Oracle BAM Server is unreachable at runtime, the retry behavior is determined by the
Oracle BAM Adapter configuration. See Section 53.2, "Configuring Oracle BAM
Adapter" and "Configuring Oracle BAM Adapter" in Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
for more information.
See the following sections for a detailed description of the data objects and
troubleshooting information.
Column Name
Description
COMPOSITE_INSTANCE_ID
COMPONENT_INSTANCE_ID
DOMAIN_NAME
COMPOSITE_NAME
COMPOSITE_REVISION
COMPOSITE_LABEL
COMPONENT_TYPE
COMPONENT_NAME
53-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
COMPONENT_START_TIME
COMPONENT_END_TIME
COMPONENT_FAULT_FLAG
FAULT_NAME
COMPONENT_RUNNING_FLAG
COMPONENT_RUNNING_TIME_IN_SEC
COMPONENT_RUNNING_TIME_IN_MIN
COMPONENT_COMPLETED_NO_FAULT_FLAG
COMPONENT_INCOMPLETE_FLAG
ECID
Column Name
Description
COMPOSITE_INSTANCE_ID
COMPONENT_INSTANCE_ID
DOMAIN_NAME
COMPOSITE_NAME
COMPOSITE_REVISION
COMPOSITE_LABEL
COMPONENT_TYPE
53-19
Description
COMPONENT_NAME
COMPONENT_START_TIME
COMPONENT_END_TIME
COMPONENT_FAULT_FLAG
FAULT_NAME
COUNTER_NAME
SUBCOMPONENT_ID
SUBCOMPONENT_TYPE
SUBCOMPONENT_NAME
EVALUATION_EVENT
The event within the life cycle of the BPEL activity (activate,
for example) at which the data is captured.
SNAPSHOT_TIME
Column Name
Description
COMPOSITE_INSTANCE_ID
COMPONENT_INSTANCE_ID
DOMAIN_NAME
COMPOSITE_NAME
COMPOSITE_REVISION
COMPOSITE_LABEL
COMPONENT_TYPE
COMPONENT_NAME
COMPONENT_START_TIME
53-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
COMPONENT_END_TIME
COMPONENT_FAULT_FLAG
FAULT_NAME
INTERVAL_NAME
INTERVAL_TYPE
INTERVAL_START_TIME
INTERVAL_END_TIME
START_SUBCOMPONENT_ID
START_SUBCOMPONENT_TYPE
START_SUBCOMPONENT_NAME
START_EVALUATION_EVENT
END_SUBCOMPONENT_ID
END_SUBCOMPONENT_TYPE
END_SUBCOMPONENT_NAME
END_EVALUATION_EVENT
SUBCOMPONENT_CREATOR
INTERVAL_RUNNING_FLAG
53-21
Table 535
Column Name
Description
COMPOSITE_INSTANCE_ID
COMPONENT_INSTANCE_ID
DOMAIN_NAME
COMPOSITE_NAME
COMPOSITE_REVISION
COMPOSITE_LABEL
COMPONENT_TYPE
COMPONENT_NAME
COMPONENT_START_TIME
COMPONENT_END_TIME
COMPONENT_FAULT_FLAG
FAULT_NAME
BI_NAME
SNAPSHOT_TIME
SUBCOMPONENT_ID
53-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
SUBCOMPONENT_TYPE
SUBCOMPONENT_NAME
EVALUATION_EVENT
INTERVAL_NAME
INTERVAL_START_FLAG
INTERVAL_END_FLAG
LATEST
METRIC_NAME
53.3.10.5 Troubleshooting
This section contains Monitor Express troubleshooting information.
53.3.10.5.1
In Oracle BAM Server data objects, older data can be purged with an alert rule, so that
the data object does not grow too large.
53-23
See Chapter 60, "Creating Oracle BAM Alerts" for general information alerts, and see
Section F.3.8, "Delete rows from a Data Object" for information about configuring the
delete action.
53.3.10.5.2
Note:
3.
From the Items list, select BAM Connection, and click OK.
The BAM Connection wizard opens.
4.
5.
6.
Click Next.
7.
Enter the connection information about the Oracle BAM Server host described in
Table 536.
Table 536
Field
Description
Enter the name of the host on which the Oracle BAM Report
Server and web applications are installed. In most cases, the
Oracle BAM web applications host and Oracle BAM Server host
are the same.
Enter the name of the host on which the Oracle BAM Server is
installed.
User Name
Password
53-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
HTTP Port
Enter the port number or accept the default value of 9001. This is
the HTTP port for the Oracle BAM web applications host.
JNDI Port
Enter the port number or accept the default value of 9001. The
JNDI port is for the Oracle BAM report cache, which is part of
the Oracle BAM Server.
Use HTTPS
8.
Click Next.
9.
Test the connection by clicking Test Connection. If the connection was successful,
the following message appears:
Testing HTTP connection ... success.
Testing Data Object browsing ... success.
Testing JNDI connection ... success.
3 of 3 tests successful.
3.
4.
Select a Data Object using the BAM Data Object Chooser dialog box.
When you click Browse, the BAM Data Object Chooser dialog box opens
allowing you to browse the available Oracle BAM Server connections in the
BAM Data Object Explorer tree. Select a data object and click OK.
b.
53-25
Upsert inserts new data into an existing row in a data object if the row exists.
If the row does not exist a new row is created. You must select a key from the
Available column to upsert rows in a data object.
Delete removes a row from the data object. You must select a key from the
Available column to delete rows in a data object.
Update inserts new data into an existing row in a data object. You must select
a key from the Available column to update rows in a data object.
c.
Provide an appropriate display name in the Operation Name field for this
operation in your SOA composite application.
d.
5.
In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server
connection.
The JNDI name is configured in the Oracle WebLogic Server Administration
Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management
Suite for more information.
6.
Click Finish.
3.
Drag and drop BAM Adapter into the Partner Links swim lane on the right side
of the BPEL Process Designer.
4.
In the Adapter Configuration wizard, enter a display name in the Service Name
field and click Next.
53-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When the wizard completes, a Web Services Description Language (WSDL) file by
this name appears in the Application Navigator for the BPEL process or Oracle
Mediator message flow. This file includes the adapter configuration settings you
specify with this wizard.
5.
Select a Data Object using the BAM Data Object Chooser dialog box.
When you click Browse, the Data Object Chooser dialog box opens allowing
you to browse the available Oracle BAM Server connections in the BAM Data
Object Explorer tree. Select a data object and click OK.
b.
c.
Provide an appropriate display name in the Operation Name field for this
operation in your SOA composite application.
d.
6.
In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server
connection.
The JNDI name is configured in the Oracle WebLogic Server Administration
Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management
Suite for more information.
7.
Click Finish.
8.
Create a new Process Variable in the BPEL process of type Message Type, and
browse the Type Chooser dialog box to select the WDSL for the data object you
want to write to on the Oracle BAM Server.
For more information about using the Oracle BPEL Process Manager see
Chapter 4, "Getting Started with Oracle BPEL Process Manager."
9.
In the BPEL Process add an activity that you can use to map the source data to the
new variable you created.
10. In the BPEL Process add an Invoke activity to send data to the Oracle BAM
Adapter partner link you created. Add the variable you just created as the Input
Variable.
11. Save all of the project files.
53-27
Variable sensor
Restrictions: A Variable sensors variable must be defined in a standalone XSD.
This variable must not be defined inline in the WSDL file. If the variable has
message parts, then there must be only one message part.
Note:
53-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about creating sensors, see Section 18.2, "Configuring Sensors
and Sensor Actions in Oracle JDeveloper."
3.
If the Structure window is not open, select View > Structure Window to open it.
4.
53-29
5.
Table 537
Field
Description
Action Name
Enable
Sensor
Data Object
Click the Browse icon to open the BAM Data Object Chooser
dialog box to select the data object in Oracle BAM Server in
which you want to publish the sensor data.
If you have not created a connection to Oracle BAM Server to
select data objects, click the icon in the upper right corner of the
BAM Data Object Chooser dialog box.
Operation
53-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table 537 (Cont.) Create Sensor Action Dialog Box Fields and Values
Field
Description
Available Keys/Selected
Keys
Map File
Filter
Specify the JNDI name for the Oracle BAM Server connection
factory.
The JNDI name is configured in the Oracle WebLogic Server
Administration Console. See "Configuring the Oracle BAM
Adapter" in Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for
more information.
Enable Batching
53-31
Integrating SOA Applications and Oracle BAM Using Enterprise Message Resources
Notes: After you click the Create Mapping or Edit Mapping, or the
OK button on the Create Sensor Action dialog box, you must
explicitly save the BPEL file.
6.
"Oracle JCA Adapter for JMS" in Oracle Fusion Middleware User's Guide for
Technology Adapters
53-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
54
54
This chapter describes how to create and use Oracle Business Activity Monitoring
(Oracle BAM) data controls, which are binding components in the Oracle ADF Model
with support for Active Data Services. It describes how to add Oracle BAM Server
connections in Oracle JDeveloper and create projects and web pages that use Oracle
BAM data controls. Information is also included about how to use parameters to create
Oracle BAM data control queries for displaying data in flat lists or in trees and charts
using groups and aggregates of data.
For more comprehensive information about using Oracle ADF Model data binding
and Active Data Services, refer to Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
This chapter includes the following sections:
Section 54.2, "Creating Projects That Can Use Oracle BAM Data Controls"
Section 54.4, "Exposing Oracle BAM with Oracle ADF Data Controls"
For general information about Oracle ADF data controls, and information about ADS
(active data services), see Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
54.2 Creating Projects That Can Use Oracle BAM Data Controls
Oracle BAM data control must to be hosted by a valid ADF web application. Also, a
limited set of ADF Faces components support active data, therefore a limited set of
ADF Faces components can make use of the main functionality of an Oracle BAM data
control. Refer to Oracle JDeveloper ADF documentation for information about creating
ADF web applications, including a list of components that support active data.
An Oracle BAM data control can still be used by view components that do not support
active data.
Oracle BAM data control requires that the project contain the ADF Faces and ADF
Page Flow technologies. The Fusion Web Application (ADF) template in JDeveloper
contains these technologies.
Note:
Note:
Example:
C:\jdevrc1\jdeveloper\jdev\bin>jdev
-J-Djavax.net.ssl.trustStore=C:\jdevrc1\wlserver_
10.3\server\lib\DemoTrust.jks
54.3.1 How to Modify Oracle BAM Data Control Connections to Oracle BAM Servers
Each Oracle BAM data control has an associated Oracle BAM connection. When a
connection has changed name or has been removed from the application resources,
you get an error when you attempt to use any data controls that are associated with
the connection. You can do one of the following to resolve the lost connection:
Create a new Oracle BAM connection with the same name as the connection that is
referred to by the data control. See Section 54.3, "Creating Oracle BAM Server
Connections" for more information.
54-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Update the current projects DataControls.dcx file with the name of a new or
existing Oracle BAM connection. See Section 54.3.1.1, "How to Associate a BAM
Data Control with a New Oracle BAM Connection" for more information.
54.3.1.1 How to Associate a BAM Data Control with a New Oracle BAM Connection
To change the Oracle BAM connection associated with a particular data control you
must edit the DataControls.dcx file in the current project. Change the connection
attribute of the BAMDataControl element with the name of the desired Oracle BAM
connection.
To modify the Oracle BAM connection in an Oracle BAM data control:
1. Optionally, create a new Oracle BAM connection in the application.
If you do not have a BAM connection in the Application Resources to use for this
data control, create a new one. See Section 54.3, "Creating Oracle BAM Server
Connections" for more information.
2.
Locate the DataControls.dcx file in the project, and open it for editing.
The DataControls.dcx file is located in the Application Sources directory under the
node named for the project.
Each project in a ADF application has a DataControl.dcx file associated with it.
Each DataControls.dcx file may have one or more data control definitions. If the
current project does not contain the definition for the data control you want to
modify, look through the other projects in the current application to locate it.
3.
In the Source view, locate the appropriate data control definition, and locate the
BAMDataControl element within it.
In the source view find the AdapterDataControl block with the id that matches the
display name of your data control.
4.
Change the connection attribute to the name of the new Oracle BAM
connection.
5.
Right-click the Oracle BAM data object for which you want to create a data
control, and select Create Data Control from the context menu.
3.
Complete the BAM Data Control wizard to create the data control query.
See Section 54.5, "Creating Oracle BAM Data Control Queries" for more
information.
54-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
54.4.2 What Happens in Your Project When You Create an Oracle BAM Data Control
When you create a data control based on an Oracle BAM data object, the data control
contains a representation of a query on all of the selected fields that is constructed
based on the groupings, aggregates, filters, parameters, and additional calculated
fields that you configure using the BAM Data Control wizard in JDeveloper.
For the data control to work directly with the service and the bindings, JDeveloper
creates the following metadata XML files:
Structure definition files for every structured object that this service exposes
JDeveloper also adds the icons to the Data Controls panel that you can use to create
data bound UI components.
54.4.2.1 How an Oracle BAM Data Control Appears in the Data Controls Panel
The Data Controls panel lists all the data controls that have been created for the
applications business services and exposes all the queries that are available for
binding to UI components. The panel is a direct representation of the structure of the
data to be returned by the data control. By editing the data control, you can change the
elements displayed in the panel.
Figure 541 Data Controls Panel in Oracle JDeveloper
Select the Connect to BAM using ADF credentials checkbox to connect to Oracle
BAM Server at runtime using the credentials in the ADF application containing the
Oracle BAM data control. This feature takes advantage of row-level security provided
by Oracle BAM Server by using the ADF application users identity to display only the
data that the user is permitted to see.
54-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
To use this feature, both Oracle BAM Server and the ADF server must use the same
credential store. When this feature is disabled (unchecked) the runtime connects to
Oracle BAM Server using the credentials provided in the Oracle BAM connection,
specified in Oracle JDeveloper or Oracle Enterprise Manager Fusion Middleware
Control.
For more information about row-level security, see Section 55.6, "Creating Security
Filters."
2.
3.
Table 541
Java Type
java.lang.Integer
Integer
java.lang.String
String
java.util.Date
DateTime, Timestamp
java.lang.Boolean
Boolean
java.lang.BigDecimal
Decimal
jave.lang.Double
Float
Field*
*The Field parameter type is used in charts for specifying groups at runtime. This
parameter type allows the user to choose which field in the data object to group
by. See the following topics for more information:
4.
To provide a default value for the parameter when loading the data control query,
select Enable Default Value and choose a default value.
To enter a default value for the parameter, select one of the available defaults, or
select the first option and enter a value in the field.
54-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
One of the many ways that can be done is by using an ADF parameter form. For more
information, see Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle
Application Development Framework.
The new default field name appears in the list of calculations. You can rename it
later, after entering a valid expression.
2.
To enter an expression, choose an expression from the expressions list, and click
Insert Expr.
Complete the expression in the right-hand box, and click Validate to check the
syntax of your expression.
There are several preformed expressions available. See Oracle Fusion Middleware
Users Guide for Oracle Business Activity Monitoring for examples and more
information about each expression.
3.
4.
To use a data object field in a calculation, select the field from the field list, and
click Insert Field.
54-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Note:
54-11
To change the operator (default ALL), select the header, and click Edit. For the
following operator options, data is returned when:
3.
AT LEAST ONE. At least one and maybe more of the included entries are
true.
NOT ALL. Some or none of the included entries are true, but not all of the
included entries are true.
3.
4.
is not equal to returns rows containing all values except specified value.
is less than returns rows containing values less than specified value.
is less than or equal to returns rows containing values less than or equal to
specified value.
is greater than returns rows containing values greater than specified value.
is greater than or equal to returns rows containing values greater than or
equal to specified value.
54-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
is like returns rows containing values that match a string pattern. Include an
underscore (_) as a wildcard for a single character in a string and a percent
symbol (%) as a wildcard for one character or more. Wildcard characters can
be combined, for example, %mm _00 would return all columns (35mm 200,
35mm 400, 35mm 800). Do not enter any spaces in the expression since spaces
are treated as characters in the data match.
is not like returns rows containing values that do not match a string pattern.
is null returns rows containing values where the column is null. If you select
this comparison, your filter configuration is complete. Click OK to create the
filter. For numeric data types, nulls are not returned for filters returning values
equal to zero. In other words, zeroes are not treated as null values. A null
represents missing data in the field.
is not null returns rows containing values where the column is not null. If you
select this comparison, your filter configuration is complete. Click OK to
create the filter. For numeric data types, nulls are not returned for filters
returning values equal to zero. In other words, zeroes are not treated as null
values. A null represents missing data in the field.
is in list returns rows containing values included in a list. To build a list, click
Edit. Type a value in the field and click Add to add it to the list. Add as many
values as needed. Click Browse to choose values currently present in the Data
Object. Click Remove to remove a value. Click OK to close the dialog.
is not in list returns rows containing values not included in the list. To build a
list, click Edit. Type a value in the field and click Add to add it to the list. Add
as many values as needed. Click Browse to choose values currently present in
the Data Object. Click Remove to remove a value. Click OK to close the
dialog.
is within a time interval returns rows containing values that occur within the
specified time interval. Configure the time interval using the provided lists.
Select a Type, enter a multiplier in the field and select a Unit.
When filtering on a datetime or timestamp field, you can enable Active Now
to keep the displayed time interval current as time passes. Configure the
Active Now Interval to specify how often to refresh the display. See
Section 54.5.6.4, "Using Active Now" for more information.
is within the current time period returns rows containing values that occur
within the current specified time unit. Select a Unit from the list.
When filtering on a datetime or timestamp field, you can enable Active Now
to keep the displayed time period current as time passes. See Section 54.5.6.4,
"Using Active Now" for more information.
is within a time period returns rows containing values that occur within the
specified time period. Configure the time period using the provided lists.
Enter a value in the Offset field, select a Unit, and select a Type.
When filtering on a datetime or timestamp field, you can enable Active Now
to keep the displayed time period current as time passes. See Section 54.5.6.4,
"Using Active Now" for more information.
5.
54-13
is null
is not null
is in list
is not in list
54.5.6.3.1
Click Browse to see a list of values present in the data object. Select a value from
the list. Up to 50 values display in the list. The field can be left blank to create a
filter on a blank string.
Note: If there are more than 50 values in the field, not all of the
values are shown in the Browse list. Your Oracle Business Activity
Monitoring administrator can configure the number of rows to display
in the list. See the Oracle Business Activity Monitoring Installation Guide
for more information.
Field. Total
Comparison. is equal to
Value. Calculation
This filter yields only those rows where the value in the Total column is equal to twice
the value in the Quantity column.
54.5.6.3.3 Comparison With a Field If you select Field, select a field from the last list to
compare with the field selected in the Field list.
54.5.6.3.4 Comparison with a Parameter If you select Parameter, select a parameter from
the list at the right. Creating a filter using a parameter allows the user to change the
filter values at runtime.
The list contains the parameters you created in the Parameters step of the Create
Oracle BAM Data Control wizard. For more information about creating parameters see
Section 54.5.2, "How to Create Parameters."
view is updated with the data within the defined time interval in the filter. Older data
is removed from the view and newer data is added as time passes.
Active Now is available when you choose one of the following comparison
expressions:
To change the display order in which the groups are presented in a graph, select a
sorting option from the Sorting list for any selected field.
3.
If a datetime field is selected in the Fields list, several options are enabled for
configuring Time Groups on the right side of the wizard page.
See Section 54.5.7.1, "How to Configure Time Groups and Time Series" for more
information.
54-15
Select Continuous Time Series to display empty groups for time intervals where
no data is available.
There may be time gaps where the data object did not have entries. The
Continuous Time Series feature adds groups to the result whose values are zero, so
that when the results are shown on the graph, the x axis represents a smooth time
series.
Continuous Time Series is valid only if you have chosen a single datetime field to
group by. Continuous Time Series is not supported if any additional group fields
are selected.
3.
4.
Use Time Series displays the data from the first datetime data point available
in the data object to the last in the configured time interval.
Use Time Groups displays data grouped into a set number of time intervals.
For example, if you select Month from the time unit list, all data from January
from all years where data is available are grouped in one data point on the
chart.
Year displays groups for all of the years where data is available.
Day of Year displays groups representing the 365 possible days in a year.
Day of Week displays seven groups representing the days of the week.
5.
Enter a quantity of the time unit to group by. For example, entering a 2 next to the
Month time unit displays the groups in two month increments (January and
February are grouped as one data point on the chart).
6.
54-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The valid Summary Functions for the data type of that field are enabled.
2.
Note:
2.
a.
b.
c.
Right click project, select New, select JSF under the Web Tier category, and
select ADF Task Flow in Items list.
54-17
3.
4.
Drag and drop an accessor node from the Data Controls panel to the JSF page
editor.
5.
6.
Save all, and in the Oracle JDeveloper toolbar, click Run Project.
The application must be deployed using MDS (Metadata Data Services). To enable
MDS:
a.
b.
54-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<mds-config xmlns="http://xmlns.oracle.com/mds/config"
version="11.1.1.000">
<persistence-config>
<metadata-store-usages>
<metadata-store-usage default-cust-store="true"
deploy-target="true" id="myRepos">
</metadata-store-usage>
</metadata-store-usages>
</persistence-config>
</mds-config>
</adf-mds-config>
c.
2.
b.
c.
In the right pane, select Application Deployment and select ADF ->
Configure ADF Connections in the menu.
d.
e.
Enter the Connection Type to be the same as the one defined in Oracle
JDeveloper.
f.
g.
Select the new connection and click the Edit icon, specify the appropriate
values for all connection parameters in the dialog, and click OK.
The Oracle BAM Web Tier is the location where report server is running. The
valid values for BAM Webtier Protocol are http and https.
You must enter the same Connection Name as the Oracle BAM connection
that was configured for design time (see Section 53.4, "Creating a Design Time
Connection to an Oracle BAM Server").
Using Oracle BAM Data Control
54-19
h.
54-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
55
55
Data objects can also be accessed and updated by Oracle BAM alerts. See Chapter 60,
"Creating Oracle BAM Alerts" for more information.
WARNING: Do not read or manipulate data directly in the
database. All access to data must be done using Oracle BAM
Architect or the Oracle BAM Active Data Cache API.
Section 55.2.6, "What You May Need to Know About System Data Objects"
Section 55.2.7, "What You May Need to Know About Oracle Data Integrator Data
Objects"
3.
Enter the path to the location in the folder tree in which to store the data object.
Click Browse to use the Select a Folder dialog.
5.
6.
If this data object is loaded from an External Data Source (EDS) select the External
Data Source checkbox and configure the following:
55-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Select an External Data Source from the list. EDS definitions are configured on
the External Data Sources screen. See Chapter 58, "Creating External Data
Sources" for more information.
Select the External Table Name.
Only the tables that belong to the user are shown when a data
object is created on an EDS.
Note:
Add columns to the data object using the Add a field or Add one or more lookup
fields options.
See Section 55.2.2, "How to Add Columns to a Data Object" and Section 55.2.3,
"How to Add Lookup Columns to a Data Object" for more information.
8.
Click Create Data Object when you are finished adding columns or lookup
columns.
Specify the column name, data type, maximum size (scale for decimal columns),
whether it is nullable, whether it is public, and tip text.
If you are adding a column in a data object based on an External Data Source you
must also supply the External field name.
The data types include:
Decimal. Numbers including decimal points with scale number defined. The
number is stored as a string which uses a character for each digit in the value.
The Oracle BAM Decimal data type is stored as a NUMBER (38, X) in the
Oracle database. The first argument, 38, is the precision, and this is
hard-coded. The second argument, X, is the scale, and you can adjust this
value. The scale value cannot be greater than 38.
Keep adding columns using Add a field and Add one or more lookup fields until
all the required columns are listed. Click Remove to remove a column in the data
object.
3.
3.
Select the lookup columns from the data object. You can select one or more
columns by holding down the Shift or Control key when selecting. Selecting
multiple columns creates multiple lookup columns in the data object. These are the
columns you want to return.
4.
5.
Select the column to match from the current data object. You must have previously
created other columns in this data object so that you have a column to select.
6.
Click Add.
The matched column names are displayed in the list. You can click Remove to
remove any matched pairs you create.
7.
You can repeat steps 4 through 6 to create multiple matched columns. This is also
known as a composite key.
8.
55-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Supported:
Table 1 (with no lookups to any other tables)
Table 1 > Lookup > Table 2
Not supported:
Table 1 > Lookup > Table 2 > Lookup > Table 3
Operator
Function
+ (plus sign)
Add
- (minus sign)
Subtract
* (asterisk)
Multiply
/ (slash)
Divide
% (percent sign)
Modulus
() (parentheses)
Logical AND
Logical NOT
|| (double pipe)
Logical OR
For example
if ((CallbackClientTime == NULL) ||
(ReceiveInputTime == NULL)) then (-1) else
(CallbackClientTime-ReceiveInputTime)
Equality
= (equal sign)
Assignment
Column names containing any special characters, such as the operators listed in
Table 551 double quotation marks, or spaces, must be surrounded with curly braces
Defining and Managing Oracle BAM Data Objects 55-5
{}. If column names contain only numbers, letters and underscores and begin with a
letter or underscore they do not need curly braces. For example, if the column name is
Sales+Costs, the correct way to enter this in a calculation is {Sales+Costs}.
Double quotation marks must be escaped with another set of double quotation marks
if used inside double quotation marks. For example, Length("""Hello World, ""
I said").
WARNING: If you enter a calculated column with incorrect syntax
in a data object, you could lose the data object definition.
55.2.6 What You May Need to Know About System Data Objects
The System data objects folder contains data objects used to run Oracle Business
Activity Monitoring. You should not make any changes to these data objects, except
for the following:
Custom Parameters lets you define global parameters for Action Buttons.
Action Form Templates lets you define HTML forms for Action Form views.
Chart Themes lets you add or change color themes for view formatting.
Matrix Themes lets you add or change color themes for the Matrix view.
Util Templates lets you define templates that are used by Action Form views to
transform content.
For more information about matrix and color themes, Action Buttons, and Action
Forms see Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring.
55.2.7 What You May Need to Know About Oracle Data Integrator Data Objects
If you install the integration files for Oracle BAM and Oracle Data Integrator, three
data objects are created in Oracle BAM Architect: Context, Scenarios and Variables in
the /System/ODI/ folder. These data objects should not be deleted from Oracle BAM
Architect, and their configuration should not be changed.
55-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The general information for the data object is displayed in the right frame.
3.
Click Permissions.
4.
5.
Click the Restrict access to Data Object to certain users or groups checkbox.
The list of users and groups and permissions is displayed.
6.
7.
You can set permissions for the entire list by clicking the buttons at the top of the
list.
The permissions are Read, Update, and Delete. You can set permissions for
individual users or groups in the list by clicking the checkbox in the permission
column that is next to the user or group name.
Delete and Update permissions are not effective unless a user
is also granted the Read permission.
Note:
Members of the Administrator role have all permissions to all data objects, and
their permissions cannot be edited.
8.
After indicating the permissions with selected checkboxes, click Save changes.
A message is displayed to confirm that your changes are saved.
9.
Type the Windows group name in the field. The group must previously exist as a
domain group.
3.
Click OK.
The group is added to the list.
In Oracle BAM Architect for a data object, click Permissions and then click Copy from.
Select the data object that contains the permissions to copy and click OK. You can edit
the copied permissions and click Save changes.
To copy permissions from another data object:
1. Select Data Objects from the Oracle BAM Architect function list.
2.
3.
Click Permissions.
4.
5.
Select the data object that contains the permissions to copy and click OK.
6.
If the data object previously had no permissions assigned, select the Restrict
access to Data Object checkbox.
7.
You can edit the copied permissions or add a group to the list.
8.
Last modified. Date and time the data object was last modified.
Data Object ID. The ID used to identify the data object. This is based on the
name although the ID is used throughout the system so that you can edit the
name without affecting any dependencies.
55-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
3.
Click Layout.
The layout information is displayed in the right frame. It contains the following
information:
External name. External column name from the External Data Source (only
appears in data objects based on External Data Sources).
Click Contents.
The first 100 rows of the data object display in the right frame.
(To change this default, update the Architect_Content_PageSize property.
See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite for information.)
Oracle BAM Architect displays the total number of rows in the data object and the
number of rows that are available for viewing. For better server performance, the
number of rows shown in Oracle BAM Architect is limited by configuration
properties.
When internal data objects are displayed in No row number mode (default), you
can view all of the records in the data object using the navigation tools.
When internal data objects are displayed in Show row numbers mode, you can
view a limited number of records. This number is 64000 by default, and can be
changed by modifying the ADCMaxViewsetRowCount property in
BAMServerConfig.xml.
When external data objects are displayed in either mode, you can view a limited
number of records. This number is 64000 by default, and can be changed by
modifying the Import_Maxsize property in BAMServerConfig.xml.
3.
4.
3.
55-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click Permissions.
3.
4.
Select the Restrict access to Data Object to certain users or groups checkbox.
The list of users and groups and permissions is displayed.
5.
6.
You can set permissions for the entire list by clicking the column headers at the top
of the list.
55-11
The permissions are Read, Update, and Delete. You can set permissions for
individual users or groups in the list by selecting the checkbox in the permission
column that is next to the user or group name.
Delete and Update permissions are not effective unless a user
is also granted the Read permission.
Note:
7.
After indicating the permissions with selected checkboxes, click Save changes.
A message is displayed to confirm that your changes are saved.
8.
1.
2.
Type the Windows group name in the field. The group must previously exist as a
domain group.
3.
Click OK.
The group is added to the list.
Click Move.
3.
4.
5.
6.
Click Continue.
Click Rename.
3.
4.
Click Continue.
55-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
To delete a folder:
1. Select the folder to delete.
2.
Click Delete.
A message is displayed to confirm deletion of the folder and all of its contents.
3.
Click OK.
The folder is deleted.
4.
Click Continue.
3.
4.
5.
55-13
Match column in Security Data Object. Select the column to match in the security
data object.
Match column in this Data Object. Select the name of the column to match in this
data object.
6.
Click Add.
7.
Select the OR or AND condition when multiple security filters are created on a
data object.
By default the security filters are applied with an OR condition, meaning that if
there is a match in one security data object, then the user or group identified can
access the data object. The AND condition requires that the user or group be
identified in all of the security data objects to access the data object protected by
the filters.
If there are more than two security filters, you cannot use both
AND and OR. You must either use AND or OR for all of the filters.
Note:
Region
Sales
John Smith
$55,000
Bob Wright
$43,000
Betty Reid
$38,000
Region ID
DomainName\jsmith
DomainName\jsmith
DomainName\bwright
DomainName\breid
When the bwright account views a report that accesses the data object with a security
filter applied based on Region ID and Region, it is only able to access information for
jsmith and bwright. It is not able to view the breid information because it is not able to
55-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating Dimensions
view data for the same region. However, the jsmith account is set up to view data in
both region 1 and 2.
Select Data Objects from the Oracle BAM Architect function list.
2.
3.
4.
5.
Select the data object that contains the security filters to copy and click OK.
6.
You can make changes to the security filters by viewing the filter details and
clicking Edit.
7.
Click Save.
Hierarchy
Sales
Category
Brand
Description
55-15
Creating Dimensions
2.
3.
Select Dimensions.
4.
5.
6.
7.
8.
Click Save.
9.
Click Continue.
The new dimension is listed. You must still define a hierarchy for the columns.
Sales remains in the Dimension Field list, and you click Category, Brand, and
Description to arrange them in a general to more specific order. The order that you
click the columns is the order that they are listed in the Hierarchy Field list.
Arrange the more general grouping column at the top of the Hierarchy Fields list
and the most granular column at the bottom of the Hierarchy Fields list.
14. Click Save.
15. Click Continue.
The new hierarchy is listed. You can edit or remove hierarchies and dimensions by
clicking the links. You can also continue defining multiple hierarchies for the
dimension or add new dimensions to the data object.
Select the time date data type column. If you are editing existing time levels, click
Edit Time Levels.
The Time Levels Definition dialog opens.
3.
55-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Creating Indexes
Week of the Year. Numbers for each week starting with January 1st.
Day of the Year. Numbers for each day of the year starting with January 1st.
4.
Day of the Week. Numbers for each day of the week, starting from Sunday to
Saturday.
3.
Select Rename/Move.
4.
Enter the new name, tip text, and description for the data object.
5.
3.
Select Rename/Move.
4.
Click Browse to enter the new location for the data object.
5.
55-17
If the data object has an index for the columns requested, the information is found
without having to look at all the data. Indexes are most useful for locating rows by
values in columns, aggregating data, and sorting data.
3.
Select Indexes.
4.
5.
6.
7.
Click OK.
The index is added and is named after the columns it contains. You can create
multiple indexes. To remove an index you created, click Remove Index next to the
Index name.
3.
Click Clear.
55-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
Click Delete.
55-19
55-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
56
Creating Oracle BAM Enterprise Message
Sources
56
This chapter describes how to create and use Enterprise Message Sources (EMS) in the
Oracle Business Activity Monitoring (Oracle BAM) Architect application. It explains
how to use XML formatting configuration parameters, specify date and time patterns
and locale information, handle errors in EMS payloads, and use Java Message Service
(JMS) resources hosted on remote providers.
This chapter includes the following sections:
Section 56.5, "Use Case: Creating an EMS Against Oracle Streams AQ JMS
Provider"
Tibco JMS
Apache ActiveMQ
See Section 56.4, "Using Foreign JMS Providers" for more information.
Map message
The following XML formatting options are supported for Text message transformation:
Pre-processing
Message specification
To view the existing EMS definitions, select Enterprise Message Sources from the
Oracle BAM Architect function list.
Figure 561 Oracle BAM Architect Function List
Click Create.
56-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Using Table 561 as a guide, enter the appropriate values in each of the fields.
Examples given are for connecting to Messaging for Oracle WebLogic Server.
Caution: A single or double quotation mark in an Oracle BAM object
name, such as a data object, report, or EMS name, causes a runtime
error. Do not include single or double quotation marks in an Oracle
BAM object name.
4.
If you are using TextMessage type, configure the appropriate parameters in the
XML Formatting sections, using Table 562 as a guide.
5.
6.
2001-10-26T21:32:52
2001-10-26T21:32:52+02:00
2001-10-26T19:32:52Z
2001-10-26T19:32:52+00:00
-2001-10-26T21:32:52
2001-10-26T21:32:52.12679
Map fields from the source message to the selected data object in the Source to
Data Object Field Mapping section.
a.
b.
c.
Enter the source tag or attribute name in the Tag/Attr name field.
d.
Select the target data object field from the Data Object Field list.
56-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Configure how errors in EMS payloads should be handled in the Faults section.
For information about the options, see Section 56.2.4, "How to Configure EMS
Error Handling."
8.
Table 561
Parameter
Description
Name
Topic/Queue
ConnectionFactory Name
Topic/Queue Name
Description
JNDI Username
JNDI Password
TextMessage or MapMessage.
If TextMessage is selected, XML is used to specify the contents of
the payload, and an additional set of XML Formatting
configuration parameters must be completed. See Table 562 for
more information.
Message Selector (Optional) A single name-value pair (currently only one name-value pair is
supported) that allows an application to have a JMS provider
select, or filter, messages on its behalf using application-specific
criteria. When this parameter is set, the application-defined
message property value must match the specified criteria for it
to receive messages. To set message property values, use
stringProperty() method on the Message interface.
he name value pair format should be name=value, for example,
message=mymessage. The equals sign (=) is the name-value
pair separator.
Data Object Name
Operation
56-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Batching
Transaction
Table 562
Parameter
Description
Pre-Processing
Message Batching
Column Value
Note:
Note: When you explicitly select the HH:mm:ss datetime format, the
default value 1/1/1970 is inserted for the date, EMS ignores the date
value.
When you explicitly select only the date (excluding the hour, minute,
and second) as the datetime format, then the date is inserted with its
hour, minute, and second set to 12:00:00 AM. EMS ignores the time
value.
56-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Optionally, you can enter the locale information in the Language, Country, and
Variant fields.
Table 563
Symbol Meaning
Presentation
Example
Era
Text
AD
Year
Number
2003
Month
Text or Number
July; Jul; 07
Number
27
Number
Number
189
Day in a month
Number
10
Number
Day in week
Text
Tuesday; Tue
AM/PM marker
Text
AM
Hour (0-23)
Number
Hour (1-24)
Number
24
Number
Number
12
Minute in an hour
Number
30
Second in a minute
Number
55
Millisecond (0-999)
Number
978
Time zone
Time zone
-0800
Delimiter
The examples in Table 564 show how date and time patterns are interpreted in the
United States locale. The date and time used in all of the examples are 2001-07-04
12:08:56 local time in the U.S. Pacific Time time zone.
Table 564
Result
"h:mm a"
12:08 PM
"K:mm a, z"
02001.July.04 AD 12:08 PM
"yyMMddHHmmssZ"
010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ"
2001-07-04T12:08:56.235-0700
Handling of hierarchical data. The Data Flow does not handle hierarchical data.
The XSLT can flatten the received XML into a single record with repeating fields.
Handling of message queues that contain messages of multiple types in a single
queue. The Data Flow requires that all records from the Message Receiver be of the
same schema. The EMS output can be defined as a combined superset of the
message schemas that are received, and the XSL transformation can identify each
message type and map it to the superset schema as appropriate.
Handling of XML that, while not expressing hierarchical data, does contain
needed data at multiple levels in the XML. EMS formatting can only read from one
level with the XML. The XSL transformation can identify the data needed at
various levels in the input XML and output it all in new XML that contains all of
the data combined at one level.
2.
3.
Type or paste the XSL markup for the transformation for the XML in this field. You
might want to write the XSL markup in another editing tool and then copy and
paste the code into this dialog.
56-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
In the Sample XML to transform field, type sample XML to test the
transformation against. The sample XML is not saved in this dialog and is not
displayed if you close and open this dialog.
5.
6.
1.
You can select both options to log and write faulted messages.
2.
If you selected Log faulted messages, select Include payloads to include the
payloads with the error messages in the log.
3.
If you selected Write faulted messages, select To Data Objects to insert the
messages in a data object, or select To JMS Queue/Topic to write the messages to
JMS. Then use Table 565 to provide additional information for the option you
selected.
56-11
Table 565
Option
Parameter
Description
To Data Objects
To JMS Queue/Topic
weblogic.jndi.WLInitialContextFactor
y
JNDI Service Provider URL
Topic/Queue Connection
factory Name
Topic/Queue Name
JNDI Username
56-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Parameter
Description
JNDI Password
For example:
EMS MyInsertEMS, failed to process the payload: <testems><test>abcd</test1> with
the following exception:
The end-tag for element type "test" must end with a '>' delimiter.
Use caution while designing the fault handling when the error message is pushed to a
JMS topic or queue. If this topic or queue is in turn configured for another (or the
same) EMS, then that EMS pulls the same message again, which fails recursively.
Although Oracle BAM has taken care of the message by encoding that message with a
CDATA, there might be other issues such as SQL exceptions that might fail recursively.
Use the links displayed at the top of the EMS definition page (the pane on the right
side of the browser window) to perform operations on the EMS.
56-13
56-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
committed in ADC, and Total Messages Lost counters. These values are accumulated
since last start or reset.
Total Messages Lost is calculated by subtracting Total Messages committed in ADC
from Total Messages Received.
Click Refresh to see these latest counter values.
Click Reset to set counter values to zero.
Make the JMS and JNDI client library of the foreign provider available to
applications deployed on Oracle WebLogic Server.
Identify the JMS and JNDI client Java Archive (JAR) files of the foreign provider
and place them in the DOMAIN_HOME/lib directory.
2.
3.
Create JMS resources (that is, connection factories and destinations) for the foreign
JMS server.
Inside the Foreign Server link, select the Destination tab and create links for
Remote ConnectionFactory
Local JNDI names configured for these destinations must be used while
configuring EMS to consume messages from these destinations.
4.
56-15
local WL server JNDI tree, so that applications deployed on the server (like Oracle
BAM EMS) can look them up, just like any other collocated Oracle WebLogic
Server JMS resource. Oracle WebLogic Server takes care of communicating with
the appropriate foreign JMS provider at runtime.
2.
3.
4.
5.
Login as sysdba
sqlplus sys as sysdba
2.
Enter the password for the system dba account when prompted.
3.
Create and execute the following scripts in the following order (see Example 561,
Example 562, and Example 563 for the contents of the scripts).
@<SCRIPT_PATH>/usertabletopiccreation.sql
@<SCRIPT_PATH>/createtable.sql
@<SCRIPT_PATH>/createtrigger.sql
b.
c.
d.
Example 561
Contents of usertabletopiccreation.sql
56-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Contents of createtable.sql
connect MyChannelDemoUser/MyChannelDemoPassword;
CREATE TABLE EMP ( EMPNO NUMBER(4), ENAME VARCHAR2(10), JOB VARCHAR2(9), MGR
NUMBER(4), HIREDATE DATE, SAL NUMBER(7,2), COMM NUMBER(7,2), DEPTNO NUMBER(2) );
quit;
Example 563
Contents of createtrigger.sql
connect MyChannelDemoUser/MyChannelDemoPassword;
create or replace
trigger employee AFTER INSERT OR Update ON EMP
FOR each row
declare
xml_complete varchar2(1000);
v_enqueue_options dbms_aq.enqueue_options_t;
v_message_properties dbms_aq.message_properties_t;
v_msgid raw(16);
temp sys.aq$_jms_text_message;
v_recipients
dbms_aq.aq$_recipient_list_t;
Begin
temp:=sys.aq$_jms_text_message.construct;
xml_complete :=
'<?xml version="1.0"?>' ||
'<row>' ||
'<EMPNO>' || :new.EMPNO || '</EMPNO>' ||
'<ENAME>' || :new.ENAME || '</ENAME>' ||
'<JOB>' || :new.JOB || '</JOB>' ||
'<MGR>' || :new.MGR || '</MGR>' ||
'<HIREDATE>' || :new.HIREDATE || '</HIREDATE>' ||
'<SAL>' || :new.SAL || '</SAL>' ||
'<COMM>' || :new.COMM || '</COMM>' ||
'<DEPTNO>' || :new.DEPTNO || '</DEPTNO>' ||
'</row>' ;
temp.set_text(xml_complete);
dbms_aq.enqueue(queue_name => 'MY_TOPIC',
enqueue_options => v_enqueue_options,
message_properties => v_message_properties,
payload => temp,
msgid => v_msgid );
End ;
/
quit;
56-17
2.
After logging into the console click the Data Sources link in the JDBC section, and
click New.
3.
4.
Enter a JNDI name from the data source (for example, jdbc/oracle/bamaq).
This name is used to configure the foreign JMS server.
5.
6.
Select Oracle's Driver (Thin) for Database Driver field, and click Next.
7.
8.
Enter your database SID in the Database Name field (for example, ORCL).
9.
Enter the hostname of the system where the database is installed as the Host
Name (for example, localhost).
2.
3.
a.
In the Oracle WebLogic Server Administration Console, from the home page,
go to the JMS Modules page.
b.
c.
d.
e.
b.
c.
d.
56-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
a.
b.
c.
b.
c.
Enter a name for the connection factory. This is a logical name referenced by
Oracle WebLogic Server.
d.
In the Local JNDI Name field, enter the local JNDI name that is used by The
Oracle BAM EMS to look up this connection factory (For example,
jms/BAMAQTopicCF).
e.
f.
5.
Click OK.
b.
c.
Enter a name for this destination. This is a logical name referenced by Oracle
WebLogic Server, and it has nothing to do with the destination name.
d.
In the Local JNDI Name field, enter the local JNDI name that is used by the
Oracle BAM EMS to lookup this destination (for example, jms/BAMAQTopic).
e.
In the Remote JNDI Name field, if the destination is a queue, enter the
following value:
Queues/queue_name
Click OK.
Open Oracle BAM Architect, and select Enterprise Message Sources in the
dropdown list.
2.
3.
56-19
weblogic.jndi.WLInitialContextFactory
4.
5.
6.
7.
Choose the Oracle BAM data object to send the values received from AQ-JMS
server.
8.
Complete the source-to-data object field mapping so that data from the incoming
XML can be mapped to an appropriate field in selected data object.
56-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
57
Using Oracle Data Integrator With
Oracle BAM
57
This chapter describes how to set up the integration between Oracle Business Activity
Monitoring (Oracle BAM) and Oracle Data Integrator (ODI), and create the Oracle
BAM targets in ODI. It describes in detail the Oracle BAM knowledge modules for
loading from source data stores, integration to target data stores, checking,
reverse-engineering, journalizing, and creating services.
This chapter includes the following sections:
Section 57.1, "What You May Need to Know About Integrating the Oracle Data
Integrator (ODI) With Oracle BAM"
Section 57.6, "Updating the Oracle Data Integrator External Data Source
Definition"
Section 57.7, "Launching Oracle Data Integrator Scenarios From Oracle BAM
Alerts"
Section 57.8, "Running Oracle Data Integrator Agent as a Daemon or a Microsoft
Windows Service With Oracle BAM Embedded"
Section 57.9, "Installation Files for Integrating Oracle BAM and Oracle Data
Integrator"
57.1 What You May Need to Know About Integrating the Oracle Data
Integrator (ODI) With Oracle BAM
In Oracle BAM 11g Release 1 (11.1.1.7.0), Oracle introduces new functionality to the
integration with ODI. This functionality is supported when both Oracle BAM and ODI
are installed on Oracle WebLogic Server. The following release configurations are
supported:
What You May Need to Know About Integrating the Oracle Data Integrator (ODI) With Oracle BAM
Note that, although Oracle BAM itself is supported on IBM WebSphere, this
integration with ODI is not supported on IBM WebSphere.
If you are using Oracle BAM before 11.1.1.7.0, then the ODI Agent can be either a
standalone Java application or embedded in the ODI client.
If you are using ODI 11.1.1.7.0 and Oracle BAM 11.1.1.7.0, then the ODI Agent can
also be a J2EE application.
This type of ODI Agent references a shared J2EE library to run code in the Oracle
BAM knowledge modules described in Section 57.3, "Using Oracle BAM
Knowledge Modules". This shared J2EE library, named oracle.bam.odi_
11.1.1.jar, must be deployed on the same application server as the ODI J2EE
Agent, which is part of the ODI environment. You can deploy the shared J2EE
library by running a script as explained in Section 57.2.1, "How to Install Oracle
BAM-ODI Integration Files Using the Script".
57.1.4 Tips for Using Oracle Data Integrator with Oracle BAM
When using Oracle Data Integrator with Oracle BAM, keep the following in mind:
Within the Oracle Data Integrator interface you must add quotation marks around
field names that contain spaces.
Oracle Data Integrator cannot insert data into Oracle BAM read-only fields of type
Lookup, Calculated, Auto-incrementing integer, and Timestamp. These fields are
automatically populated. Although Oracle Data Integrator enables you to select
57-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
these fields as target fields, running Oracle Data Integrator with these fields
populated throws an exception.
Do not use Oracle BAM as a staging area; for example, if Oracle BAM is used as a
source (as when using a loading knowledge module), then do not use this source
as staging area. If Oracle BAM is being used as a target (as when using an
integration knowledge module) then do not use that target as a staging area.
Oracle Data Integrator installed and the basic configuration is done (the Oracle
Data Integrator Master repository is created, repository connections are
configured, Work repositories are created and connected, and any source
topologies are configured).
If Oracle Data Integrator is installed on a separate host, then Java 1.6 must be
installed on the Oracle Data Integrator host before you can work with the Oracle
BAM and Oracle Data Integrator integration.
57.2.1 How to Install Oracle BAM-ODI Integration Files Using the Script
Use the installation script when you have Oracle Data Integrator and Oracle BAM
installed on the same system or the same network file system.
A log file called utility.log is created if there is a problem with the installation.
The file location is controlled by the utility.logging.properties file. See
Section 57.2.4, "Using the Logs" for more information.
To install the integration files:
1. Verify that Oracle BAM Server is running and reachable from the Oracle Data
Integrator host.
2.
Note:
3.
4.
If you are using Release 11g, then deploy the shared library. The shared library is
the file oracle.bam-odi_11.1.1.jar, and you deploy it by running the script
deploy_shared_lib.sh. When prompted, enter the username and password.
Optionally, you can also enter arguments for serverName and serverPort.
The script deploy_shared_lib.sh deploys the file oracle.bam.odi.jar on
the target AdminServer you specify (or localhost as default) at the specified
port (or 7001 as default)for example: deploy_shared_lib.sh weblogic
welcome1 localhost 7001.
57-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Ensure that the application server on which the Oracle BAM server resides is
running.
6.
Note:
57.2.2 What Happens When You Install Oracle BAM-ODI Integration Files Using the
Script
The script branches on the server platform type (either Oracle WebLogic Server or IBM
WebSphere) and ODI Version (either 10g or 11g) according to the values you specified
in the file bam-odi-configuration.properties in Step 3.
For information on certification questions, see Oracle Fusion Middleware Supported
System Configurations at the following URL:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
You are prompted to give Oracle BAM and ODI credentials for the creation of
Oracle BAM external data sources and other data objects. ICommand then
connects to the Oracle BAM server to create these data objects.
The Oracle BAM Jar files needed for the ODI client are copied into the directory
~user/.odi/oracledi/userlib, which is the directory designated by ODI for
external Jar files that need to be in the ODI client classpath.
The configuration file for ODI-BAM integration, BAMODIConfig.xml, is
unzipped from oracle-bam-odi-config.jar. It is then modified with the
correct value for serverPlatform and other required values. After modification
it is re-zipped into the Jar file.
The Oracle BAM knowledge modules are copied to the designated directory for
the ODI client.
The ODI client logging configuration file, ODI-logging-config.xml, is backed
up. This file is then modified by adding logging configuration for Oracle BAM.
In an existing working Oracle Data Integrator environment, you need only to copy the
Oracle BAM artifacts. To do this run the script with the PATCH command line
parameter. For example:
sh bam_odi_configuration.sh PATCH
When the script finds the command-line parameter, it copies the Oracle BAM JAR files
and knowledge modules and neither re-creates Oracle Data Integrator EDS enterprise
data sources nor modifies the odiparams.sh file.
Now you can create an Oracle BAM target in the Oracle Data Integrator Topology
Manager. See Section 57.4, "Creating the Oracle BAM Target" for instructions.
Set JAVA_HOME
2.
3.
4.
5.
Set JAVA_HOME
The environment variable JAVA_HOME must be set to Java version 1.6.x in the
environment in which an Oracle Data Integrator application is invoked. This situation
57-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
means that Java version 1.6.x must be installed on the host. To set the environment
variable:
On Microsoft Windows, go to the Control Panel, click the System icon. In the System
Properties, go to the Advanced tab, and then click the Environment Variables button.
In the Environment Variables window, create or modify a variable named JAVA_HOME
for the user (upper box), and set the value to the path for the Java installation (for
example: c:\PROGRA~1\Java\jdk1.6.0_12). Click OK. When you launch Oracle
Data Integrator, be sure to do it from a fresh command prompt, to pick up the new
environment variable.
On UNIX, follow the procedure for the shell script to create the environment variable
JAVA_HOME. This can be done in a startup script (such as .cshrc in the user's home
directory) or on the command line before invoking Oracle Data Integrator.
Create External Data Sources for Oracle Data Integrator
Create the external data sources in Oracle BAM Architect.
1.
Open Oracle BAM Architect and select the External Data Sources page.
2.
Click Create, and configure the two external data sources (ODI_Master and ODI_
Work) with the values shown in Table 571 and Table 572.
Table 571
Property
Value
ODI_Master
Driver
oracle.jdbc.driver.OracleDriver
Login
Password
Connection String
jdbc:oracle:thin:@ip_address:port_number:db_service_name
Table 572
Property
Value
ODI_Work
Driver
oracle.jdbc.driver.OracleDriver
Login
Password
Connection String
jdbc:oracle:thin:@ip_address:port_number:db_service_name
ODI_JAVA_OPTIONS Modification
On Microsoft Windows:
SET ODI_JAVA_OPTIONS=-Djava.security.policy=server.policy
-Djava.util.logging.config.file=../lib/bam_odi.logging.properties
On Linux:
SET ODI_JAVA_OPTIONS="-Djava.security.policy=server.policy
-Djava.util.logging.config.file=../lib/bam_odi.logging.properties"
Example 572
ODI_ADDITIONAL_CLASSPATH Modification
SET ODI_ADDITIONAL_CLASSPATH=../lib/weblogic/wlfullclient.jar
2.
3.
oracle-bam-common.jar
oracle-bam-etl.jar
oracle-bam-adc-ejb.jar
commons-codec-1.3.jar
xstream-1.1.3.jar
4.
5.
jps-api.jar
6.
ojdl.jar
dms.jar
57-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
8.
bam.odi.logging.properties
9.
org.jaxen_1.1.1.jar
BAMODIConfig.xml
1.
2.
3.
Table 573
Knowledge Module
Description
CKM Get Oracle BAM Metadata A check knowledge module that is used internally before
integration knowledge module steps. This check knowledge
module is the default knowledge module in Oracle BAM
technology, and it is automatically acquired by Oracle Data
Integrator. This check knowledge module creates two arrays
which are later used by Oracle BAM-specific integration
knowledge modules in the same Java session.
This knowledge module has no options.
IKM SQL to Oracle BAM
(delete)
IKM SQL to Oracle BAM (insert) An integration knowledge module that can insert rows to
Oracle BAM data objects from heterogeneous data sources.
It has the following options:
BATCH_SIZE
COMMIT_SIZE
CREATE_TARG_TABLE
DATETIME_PATTERN
LAST_BAM_TASK
LOCALE_COUNTRY
LOCALE_LANGUAGE
LOCALE_VARIANT
57-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Description
57-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Table 574 describes the parameters used in Oracle BAM knowledge modules.
Table 574
Parameter
Description
BATCH_SIZE
COMMIT_SIZE
CREATE_TARG_TABLE
Select this option to create the target data object on Oracle BAM
Server.
DATETIME_PATTERN
Description
DELETE_TEMPORARY_
OBJECTS
DROP_PURGE
Set this option to YES to not only drop the work table, but purge
it as well. When a table is dropped, it is recoverable in the
database's recycle bin. When the table is dropped and purged, it
is permanently deleted.
GET_COLUMNS
GET_FOREIGN_KEYS
GET_INDEXES
GET_PRIMARY_KEYS
KEY_CONDITION
LAST_BAM_TASK
Use this option to manage the life cycle of the Oracle BAM JDBC
connection. If this task is the last Oracle BAM task in the work
flow, it closes the JDBC connection; otherwise, it leaves the
connection open.
LOCALE_COUNTRY
The country option is a valid ISO Country Code. These codes are
the upper-case, two-letter codes as defined by ISO-3166.
This option plus LOCALE_LANGUAGE and LOCALE_VARIANT are
used to construct a Java Locale object.
LOCALE_LANGUAGE
LOCALE_VARIANT
LOG_FILE_NAME
Specify when USE_LOG is set to Yes. Specify the path and file
name of the log. Be sure to set this property value properly (that
is, choose a location where user has write permissions) before
running the reverse engineering.
57-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
NON_KEY_MATCHING
USE_LOG
3.
4.
5.
JDBC Driver: any_text_will_do; however, in 11g, you specify the JDBC driver
as oracle.jdbc.OracleDriver.
JDBC URL: instance1:hostname:port_number
The instance1 string can be any string.
The hostname value must be the same as the ServerName property value in
the BAMCommonConfig.xml file, and the port_number value must be the
same as the ServerPort property value in the BAMCommonConfig.xml file.
Do not use the Test button in this dialog, because it is not functional for the
integration between Oracle BAM and Oracle Data Integrator. After you
successfully reverse engineer the data objects in the Oracle BAM model, then
you can verify that the connection information is correct.
6.
Click OK.
7.
Create a new row which automatically introduces a row with the Context
name Global.
For that row, the Logical Schema value is initially <Undefined>. You
must select the <Undefined> text and replace it with the display name
for Oracle BAM.
Type in a display name for the Oracle BAM target such as BAM_TARGET as
the name of a new Logical Schema. Oracle Data Integrator automatically
creates the logical schema.
Click OK.
1.
2.
3.
Context: Global
Note:
4.
57-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The reverse engineering produces a reverse.log file. The name and location of
the log file can be changed in the LOG_FILE_NAME option.
Any of the knowledge module options can be changed on this tab (they are
described in Table 574).
5.
When reverse engineering is complete, the metadata for the Oracle BAM schema
appears in Oracle Data Integrator Designer, under the Oracle BAM target node.
You can try a use case in which you create source and target data models. Then,
when you have completed reverse engineering, use relevant knowledge modules
to create the interface.
57.6 Updating the Oracle Data Integrator External Data Source Definition
When you install the Oracle BAM integration files for Oracle Data Integrator with a
correctly populated properties file, you are not required to do any other configuration
in Oracle BAM. Two external data source (EDS) definitions are created during the
installation process, and they are populated with the correct values to connect Oracle
BAM Server with the ODI_Master and ODI_Work repositories in Oracle Data
Integrator. These Oracle Data Integrator-specific EDS definitions must never be
deleted.
There are cases in which you must update the Oracle Data Integrator EDS definitions:
If you change the Oracle Data Integrator login credentials, you must update the
Oracle Data Integrator EDS definitions in Oracle BAM Architect.
If the ODI_Master or ODI_Work repositories are moved to different hosts after the
initial installation, you must update the corresponding EDS definitions in Oracle
BAM Architect.
57.6.1 How to Update the Oracle Data Integrator External Data Source Definitions
To update the Oracle Data Integrator external data source definitions:
1. Open Oracle BAM Architect, and go to the External Data Sources page.
Figure 571 Opening External Data Source Page in Oracle BAM Architect
2.
3.
57.7 Launching Oracle Data Integrator Scenarios From Oracle BAM Alerts
Alerts created in Oracle BAM can launch Oracle Data Integrator scenarios when
specified conditions are met. See Section F.3.10, "Run an Oracle Data Integrator
Scenario" for more information.
You need to manually configure the following files using the appropriate values:
BAMServerConfig.xml
Table 575
BAMServerConfig.xml values
Property
Value
Datasource JNDI
jdbc/oracle/bam/adc
ODI User
SUPERVISOR
Login
ODI Password
welcome1
localhost
8001
BAMCommonConfig.xml
Application URL: http://localhost:9001
BAMWebConfig.xml
Table 576
BAMWebConfig.xml values
Property
Value
ADCservername
localhost
ADC serverPort
9001
57-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Installation Files for Integrating Oracle BAM and Oracle Data Integrator
2.
3.
Follow the instructions in the readme.txt file in that directory to configure the
Oracle Data Integrator agent to run with Oracle BAM.
The agent.bat (or agent.sh) file picks up the same environment variables as do
the other Oracle Data Integrator applications (such as Designer, Topology, Operator).
As long as the Oracle Data Integrator integration installation has been performed on
the Oracle Data Integrator directory in which the agent script runs, no additional
steps are needed to run the Oracle Data Integrator agent as a standalone application or
as a daemon or service.
57.9 Installation Files for Integrating Oracle BAM and Oracle Data
Integrator
Table 577 lists and describes the files that are important to the BAM-ODI installation.
Table 577
New with 11g?
Preexisting 11g?
Directory
Filename
Description
Renamed?
./bin
bam-odi-configuration.sh
Preexisting
./bin
bam-odi-config-was.sh
Preexisting
./bin
bam-odi-config-wls.sh
New
Installation Files for Integrating Oracle BAM and Oracle Data Integrator
Filename
Description
./bin
bam-odi10g-config-wls.sh
Renamed
Shell script called by
bam-odi-config-wls.sh in the case that
ODI_VERSION = 10g. This script has
not been changed (except for its name)
in this project. This script does the
installation by invoking java code
(which resides in oracle-bam-etl.jar) and
ant script bam-odi10g-config.xml
(which also has not changed except for
its name). Previously this file was
named bam-odi-config-wls.sh.
./bin
bam-odi11g-config-wls.sh
New
./bin
deploy_shared_library.sh
New
./bin
undeploy_shared_library.sh
New
./config
Preexisting
bam-odi-configuration.properties Properties file which is read in by the
installer scripts. Its variable ODI_
VERSION indicates whether the ODI
10g or ODI 11g version of the BAM-ODI
integration is to be installed. Since this
is a new variable, if it does not exist in
the properties file, the installer will
assume that it is to install for ODI 10g.
57-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Renamed?
Installation Files for Integrating Oracle BAM and Oracle Data Integrator
Filename
Description
./config
bam-odi10g-config.xml
Renamed
Ant script invoked by
bam-odi10g-config.sh. This script has
not changed (except for its name) in this
project. Previously this file was named
bam-odi-config.xml.
./config
bam-odi11g-config.xml
New
Preexisting
/modules/ora oracle-bam-adc-ejb.jar
cle-bam_11.1.1
oracle-bam-common.jar
oracle-bam-etl.jar
oracle-bam-odi-config.jar
oracle-bam-odi_11.1.1.jar
Renamed?
Preexisting
Preexisting
New
New
Installation Files for Integrating Oracle BAM and Oracle Data Integrator
57-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
58
58
This chapter describes how to create and manage External Data Sources (EDS) in
Oracle Business Activity Monitoring (Oracle BAM) Architect. It describes how to
create a data object using an EDS and how to configure an EDS definition to work with
Oracle Business Intelligence Enterprise Edition.
This chapter includes the following sections:
Section 58.4.1, "Use Case: Creating an EDS Against Oracle Business Intelligence
Enterprise Edition"
Select External Data Sources from the Oracle BAM Architect function list.
Click Create.
3.
5.
6.
58.2.2 What You May Need to Know About Oracle Data Integrator External Data
Sources
If you install the integration files for Oracle BAM and Oracle Data Integrator, two EDS
definitions are created in Oracle BAM Architect: ODI_Master and ODI_Work. These
EDS definitions cannot be deleted from Oracle BAM Architect, and their configuration
should not be changed unless you are updating your Oracle Data Integrator host.
3.
Select Edit.
4.
58-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
To delete an EDS:
1. Select External Data Sources from the Oracle BAM Architect function list.
2.
3.
Select Delete.
4.
Click Create.
3.
4.
5.
6.
Enter scott in the Login field and tiger in the Password field.
This sample account comes with your Oracle database installation. If you do not
have this sample account you can create a new account and use it for this example.
7.
8.
Click Save.
9.
Click Continue.
The EDS information is displayed on the screen.
3.
4.
Leave the slash (/) in the Location for new Data Object field.
The data object appears in the top level Data Objects folder.
5.
Use Cases
6.
7.
8.
9.
Field
Field Type
ename
ename
String
empno
empno
Integer
job
job
String
mgr
mgr
Integer
hiredate
hiredate
DateTime
sal
sal
Decimal
comm
comm
Decimal
deptno
deptno
Integer
Keep default settings for field attributes not specified in the table.
11. Click Create Data Object.
12. Click Continue.
13. Click Contents to view the contents of the data object
The data in the Employees data object should match the data in the Oracle
database sample EMP table.
58.4.1 Use Case: Creating an EDS Against Oracle Business Intelligence Enterprise
Edition
The following are the steps to configure an EDS definition in Oracle BAM Architect to
work with Oracle Business Intelligence Enterprise Edition.
1.
Get the bijdbc.jar file and add it to the Oracle WebLogic Server class path.
Add the JAR to WEBLOGIC_CLASSPATH in
WLS_HOME/wlserver 10.3/common/bin/commEnv.cmd
2.
58-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Use Cases
Create a data object based on this EDS. See "Step 2: Create a Data Object using the
EDS" on page 58-3 for an example.
Associate the new user to the table you want to create EDS against.
3.
4.
5.
Get the file jconn4.jar (the Sybase Driver JAR file) and add it to the Oracle
WebLogic Server class path.
Add the JAR to WEBLOGIC_CLASSPATH in
WLS_HOME/wlserver 10.3/common/bin/commEnv.cmd
6.
for example:
jdbc:weblogic:sybase://machine.us.example.com:5000;databaseName=bamtest
Login: <User> (other than dbo)
Password: <Password> for above user
Connection String:
jdbc:weblogic:sybase://sybasehost:sybaseport;databaseName=dat
abase name
58.4.3 Use Case: Creating an External Data Source Against Microsoft SQL Server
If you use the standard data object user to create an EDS in Microsoft SQL Server, then
you will not be able to view the tables in the data object.
To enable Oracle BAM to list the data object tables using EDS, do the steps described
in this use case.
Use Cases
Associate the new user to the table you want to create EDS against.
3.
4.
58-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
59
Using Oracle BAM Web Services
59
This chapter describes how to use Oracle Business Activity Monitoring (Oracle BAM)
web services such as DataObjectOperations, DataObjectDefinition, and
ManualRuleFire to build applications that publish data to the Oracle BAM Server for
use in real-time charts and dashboards.
This chapter includes the following sections:
Note:
The data objects in the Oracle BAM Server are available using the Oracle BAM web
services. There are several other meta objects that are available using the ICommand
web service.
External web services can be called by an Oracle BAM alert rule. See Section 60.2,
"Creating Alert Rules" for more information.
Oracle BAM provides the following static untyped web service APIs:
These services can be discovered within an Oracle BAM Server using a WSIL interface.
Batch performs batch operations on a data object. Batch is not supported for
DataObjectOperationsByName web service.
Delete removes a row from the data object.
Get fetches the details from a data object per the specifications in the XML
payload. Get is only available in DataObjectOperationsByName web service.
Insert adds a row to the data object.
Upsert inserts new data into an existing row in a data object if the row exists. If the
row does not exist a new row is created.
Update inserts new data into an existing row in a data object.
The request and response messages vary depending on the operation used. See
Section E.1, "DataObjectOperations10131," Section E.2,
"DataObjectOperationsByName," and Section E.3, "DataObjectOperationsByID" for
information about using the operations supported by each of the web services.
59-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
When the web service proxy is created, you see it in the Application Navigator under
the Application Sources folder in your project as shown in Figure 591.
Figure 591 DataObjectOperations Web service proxy in Application Sources
Create creates a data object. For more information see Section E.4.1, "Create."
Delete removes a data object from the server. For more information see
Section E.4.2, "Delete."
Get returns the definition of an existing data object. For more information see
Section E.4.3, "Get."
Update changes the definition of a data object. For more information see
Section E.4.4, "Update."
The request and response messages vary depending on the operation used. See
Section E.4, "DataObjectDefinition Operations" for more information.
Note:
When the web service proxy is created, you see it in the Application Navigator under
the Application Sources folder in your project as shown in Figure 592.
Using Oracle BAM Web Services 59-3
Note:
When the web service proxy is created, you see it in the Application Navigator under
the Application Sources folder in your project.
Export a report
The key differences revolve around the fact that the web service cannot access files on
the remote system. Therefore, you cannot pass in a file name when using the import
command or the export command.
Instead, you must pass in the import content inline. Similarly, you receive the
export content inline.
Commands other than import and export generally work the same as with the
command-line utility.
59-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the commands and parameters provided by ICommand,
see Appendix G, "Oracle BAM ICommand Operations and File Formats."
The ICommand web service has a single method, called Batch. It takes a single input
parameter, which is a string containing a set of commands in the syntax described in
Section G.3, "Format of Command File." The return value is a string containing the
results of executing each command, in the log syntax described in Section G.4, "Format
of Log File."
Note:
Example 591
<OracleBAMCommands>
<Delete type="dataobject" name="/test123"/>
</OracleBAMCommands>
59-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
60
Creating Oracle BAM Alerts
60
This chapter describes how to create and use alerts in Oracle Business Activity
Monitoring (Oracle BAM). It describes how to define rules that specify the events and
conditions under which an alert fires, include messages with alert rules, manage
nested rules with dependent rules, and create custom actions for rules using external
actions.
This chapter includes the following sections:
In Oracle BAM Architect, alerts are displayed in a table, which may include an Alert
Owner column that shows the users who created the alerts, as shown in Figure 603.
The Alert Owner column displays only if the current user is a member of the
administrative role (that is, an admin user). Admin users are able to see alerts they
have created and alerts created by other users (admin and non-admin).
Figure 603 Alerts Table with Alert Owner Column
In Oracle BAM Active Studio, alerts are shown in the Alert Rules table (Figure 604),
which includes a Last Launched column that indicates the last time the alert rule was
fired. As in Oracle BAM Architect, each alert name is accompanied by an icon
indicating its status as described in Table 601, and non-admin users only see the alerts
they have created. If the current user is an admin user, the table displays all alerts and
includes the Alert Owner column that shows the users who created the alerts.
Figure 604 Alert Rules Table in Oracle BAM Active Studio
Table 601
Icon
60-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Invalid indicates that an alert has become orphaned or broken
due to some error. This icon is displayed when an alert cannot be
loaded properly into the Event Engine. The rule might require
correction.
For example, when a report is deleted and an alert based on this
report still exists, that alert cannot be loaded properly.
This icon appears only when rules are loaded into the Event
Engine (on restarts). Alerts displayed with this icon do not fire
again until they are edited and corrected.
Expired means that the alert does not fire again. This icon is seen
in time based alerts which fire only one time, after the alert has
fired. However, these alerts can be edited and reused, resetting
the state to Normal.
Inactive and expired alerts behave differently. An alert can be deactivated only if it is
running. This behavior is a benefit to users who do not want to receive alerts for some
time interval, but want to retain the ability to activate the alert at a convenient time.
Alerts that are not active, but still valid (displayed with the Normal icon) can be
activated again.
Those alerts that are expired have run for the specified condition and do not run again.
They cannot be activated to run again. However, to reuse an expired alert, double click
the alert, update the definition to make it a valid rule, and save the alert rule
definition. The alert is reloaded and is ready to fire again.
If any changes to the time or time zone are made on the Oracle
BAM Server system, the Oracle BAM Server application must be
restarted or time-based alerts misfire.
Note:
Note:
3.
4.
6.
Click Next.
7.
8.
Select one or more actions. See Section F.3, "Actions" for descriptions of each
action.
9.
In the rule expression, click each underlined item and specify a value to complete
the alert rule.
For example, click select report, and choose a report in the dialog box that opens.
Other values you define include user names receiving reports, dates and times,
time intervals, and filter expressions for a specific field. To continue adding
conditions or actions, click the last line in the expression and then select another
condition or action.
You can click the Back and Next buttons to go between the events page and the
page containing actions and conditions, and make changes to those parts of the
rule expression you have constructed.
10. You can click the Frequency Constraint button to set a limit to how often an alert
can launch.
The default frequency constraint for alerts is five seconds. Type a number and
select a time measurement such as seconds, minutes, or hours, and click OK. To
turn off the frequency constraint, uncheck the Constraint Enabled checkbox. For
more information about frequency constraint see Section F.4, "Frequency
Constraint."
11. Click Delete this expression to remove lines from the alert rule.
12. Click OK.
60-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Click Edit in the Alert Actions list or Edit alert in the Actions list.
The Rule Creation and Edit dialog box opens.
3.
Click Delete in the Alert Actions list or Delete alert in the Actions list.
A dialog box opens to confirm alert deletion.
3.
Click OK.
The alert is deleted.
when sending a report by email and escalating to another user after a specific
amount of time
when sending a parameterized message for every matching row in a data object
For example, when admin users edit a non-admin user's alert that uses the When a
report changes event, they are able to see and select only the reports of the alert owner
(and not their own reports) in the Select Report dialog (Figure 605). Similarly, when
editing a message in the Alert Message - WebPage dialog, admin users are able to add
a link to a report of the alert owner only, to send in the message body (Figure 606).
Figure 605 Select a Report Dialog
60-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Also, when editing a non-admin user's alert in the Rule Creation and Edit dialog,
admin users are not able to add the "run as <user name>" option and other
admin-specific options in the Rule Expression box (Figure 607).
Figure 607 Rule Creation and Edit Dialog
3.
4.
5.
In the Rule Expression box, click each underlined item and specify a value to
complete the alert rule. For example, click select report, and choose a report in the
dialog box that opens. Other values you define include user names receiving
reports, dates and times, time intervals, and filter expressions for a specific field.
6.
You can click Frequency Constraint to specify how often an alert can launch. The
default frequency constraint for alerts is five seconds. Enter a number and select a
time measurement such as seconds, minutes, or hours, and click OK.
7.
You can click Modify this rule to modify the rule without using the template. This
provides more options for creating rules.
8.
Click OK.
The alert rule is added to list and is active.
3.
4.
5.
6.
60-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Special fields are listed in the box in the lower left corner of the Alert Message
dialog box. The special fields listed change when reports are selected on the right
side of the dialog box.
To insert a special field into the message:
a.
b.
You can insert multiple values of the same type, for example, multiple links to
different reports.
7.
Click OK.
Create a rule that includes the action Launch a rule or Launch rule if an action
fails. The Launch rule if an action fails applies to any of the actions contained in
the rule.
3.
4.
Select a dependent rule. Only rules that include the When this rule is launched
event are displayed in the list.
5.
Click OK.
To handle a failing action, add the action Launch rule if an action fails. For example, if
a rule is supposed to send a message, and for some reason the message does not send,
you could launch another rule to notify you.
60-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Click OK.
The alerts history list is deleted. New alerts launched after clearing appear in the
alerts history list.
Note:
60-11
Oracle BAM 11g. Call a Web Service action has a more sophisticated Web services
client, which is dynamic and can invoke any service by reading WSDLs at runtime.
2.
3.
4.
Click select user and enter the e-mail addresses in the And/Or external email
addresses box, separating the addresses with semicolons.
60-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
61
61
Using ICommand
This chapter describes how to use the ICommand command-line utility to perform
operations on items in the Active Data Cache, such as exporting, importing, and
renaming. It also describes how to run ICommand from a remote system and execute
the commands on a server located remotely.
This chapter includes the following sections:
Note:
All parameters given on the command line are in the following form:
-parameter value
The parameter portion is not case sensitive. If the value portion contains spaces or
other special characters, it must be enclosed in double quotation marks. For example
icommand -cmd export -name "/Samples/Call Center" -type dataobject
-file C:\CallCenter.xml
It is required to use quotation marks around report names and file names that contain
spaces and other special characters.
For some parameters, the value may be omitted. See Section G.2, "Detailed Operation
Descriptions," for information about individual parameter values.
However, command line entries always override the properties specified in the
configuration file.
The user name and password for running ICommand operations can come from the
configuration file, command line prompts, or command line options as follows:
61-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If the user name and password are only specified in the configuration file (that is,
-username parameter is not used in the command line), then the ICommand_
Default_User_Name and ICommand_Default_Password values in the
configuration file are used.
If only the user name is specified in the configuration file and the password is not,
then the user name value is used, and ICommand prompts the user for the
password at the command line.
If user name is specified on the command line, then that value is used, and
ICommand prompts the user for a password. The password prompt occurs
regardless of any properties specified in the configuration file. For example:
icommand -cmd export -name TestDO -file C:\TestDO.xml -username user_name
In an XML command file, commands are specified by the XML tag. Options for the
command are given as XML attribute values of the command tag, in the form
parametername=value.
Command names and parameter values (except for Active Data Cache item names) are
not case sensitive.
For information about individual commands and their parameters see Appendix G,
"Oracle BAM ICommand Operations and File Formats."
If the Data Object is at the root, the leading slash (/) is optional. The following two
examples are equivalent:
/MyDataObject
MyDataObject
The /private:user_name/ part of the prefix may be omitted if the user running
ICommand is the user that owns the report.
"Report/Subfolder1/My Report"
The path information without the public or private prefix is saved in the export
file.
Similarly, a report folder can be specified using the appropriate prefix.
/public/Report/Subfolder1
/private:jsmith/Report/Subfolder1
Alert Rules
Either the name of the Alert, or the full name of the Alert may be specified. The
following two examples are equivalent for Alerts if the user running ICommand is the
user that owns Alert1:
Alert1
/private:user_name/Rule/Alert1
If the user running ICommand is not the owner of Alert1, then only the second form
may be used.
All other object types
Specify the full name of the object.
61-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In this example, while exporting all of the objects in the system, the command passes
owner = 1 to the report, rule, and folder Active Data Cache object types. The command
also passes permissions = 1 to the dataobject and folder object types. The comma (,)
separates the object types and the parameter is listed after a colon (:).
Supplying multiple values in the example single command line gives the same results
as the following three commands:
icommand -cmd export -type report -owner 1 ...
icommand -cmd export -type rule -owner 1 ...
icommand -cmd export -type folder -owner 1 ...
Cmd
-cmd commandname
Cmdfile
-cmdfile file_name
Optional parameter that specifies the name of the file that contains commands to
be processed. Because this is an XML file, it would usually have the XML
extension, although that is not required.
The Cmdfile and cmd parameters are mutually exclusive. Exactly one of them
must be present.
Debug
-debug flag
Domain
-domain domain_name
Optional parameter that specifies the domain name to use to login to the Active
Data Cache (the name of the computer on which the Active Data Cache server is
running).
If this parameter is omitted, main is used, which means the server information is
obtained from the ServerName property in the ICommand.exe.config file.
If the reserved value ADCInProcServer is used, then ICommand directly
accesses the Active Data Cache database (which must be local on the same system
on which ICommand is running) rather than contacting the Active Data Cache
server. This option is necessary only when the Active Data Cache server is not
running; otherwise corruption of the database could occur. The information about
Using ICommand 61-5
the location and structure of the Active Data Cache database is obtained from
various keys in the ICommand.exe.config file.
Logfile
-logfile file_name
Optional parameter that specifies the name of the file to which results and errors
are logged. If the file does not exist, it is created. If the file does exist, any contents
are overwritten. Because this is an XML file, it would usually have the XML
extension, although that is not required.
If this parameter is not present, results and errors are output to the console.
See Section G.4, "Format of Log File" for more information about the log file
format.
Logmode
-logmode mode
Username
-username user_name
Optional parameter that specifies the username that the command should run as.
There is no password parameter.
ICommand requires users to specify security credentials when running
commands. ICommand securely prompts for a user name and password. If the
-username parameter is specified on the command line, ICommand prompts the
user for the password only.
61-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</BAMICommand>
The Oracle BAM version installed on the remote system should be same as the Oracle
BAM Server version (that is, both servers should be from the same label).
61-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part XI
Part XI
62
Oracle User Messaging Service
This chapter describes the features and architecture of Oracle User Messaging Service
(UMS).
This chapter includes the following section:
Integration with Oracle BAM: Oracle BAM uses UMS to send email alerts in
response to monitoring events.
62.1.1 Components
There are three types of components that comprise the Oracle User Messaging Service.
These components are standard Java EE applications, making it easy to deploy and
manage them using the standard tools provided with Oracle WebLogic Server.
UMS Server: The UMS Server orchestrates message flows between applications
and users. The server routes outbound messages from a client application to the
appropriate driver, and routes inbound messages to the correct client application.
The server also maintains a repository of previously sent messages in a persistent
store, and correlates delivery status information with previously sent messages.
UMS Drivers: UMS Drivers connect UMS to the messaging gateways, adapting
content to the various protocols supported by UMS. Drivers can be deployed or
undeployed independently of one another depending on what messaging
channels are available in a given installation.
UMS Client applications: UMS client applications implement the business logic of
sending and receiving messages. A UMS client application might be a SOA
application that sends messages as one step of a BPEL workflow, or a Spaces
application that can send messages from a web interface.
In addition to the components that comprise UMS itself, the other key entities in a
messaging environment are the external gateways required for each messaging
channel. These gateways are not a part of UMS or Oracle WebLogic Server. Since UMS
Drivers support widely-adopted messaging protocols, UMS can be integrated with
existing infrastructures such as a corporate email servers or XMPP (Jabber) servers.
Alternatively, UMS can connect to outside providers of SMS or text-to-speech services
that support SMPP or VoiceXML, respectively.
62.1.2 Architecture
The system architecture of Oracle User Messaging Service is shown in Figure 621.
For maximum flexibility, the components of UMS are separate Java EE applications.
This allows them to be deployed and managed independently of one another. For
example, a particular driver can be stopped and reconfigured without affecting
message delivery on all other channels.
Exchanges between UMS client applications and the UMS Server occur as
SOAP/HTTP web service requests for web service clients, or through Remote EJB and
JMS calls for BPEL messaging activities. Exchanges between the UMS Server and UMS
Drivers occur through JMS queues.
Oracle UMS server and drivers are installed alongside SOA or BAM in their respective
WebLogic Server instances. An Oracle WebCenter Portal installation includes the
necessary libraries to act as a UMS client application, invoking a server deployed in a
SOA instance.
62-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
62-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
63
Sending and Receiving Messages using the
User Messaging Service EJB API
63
This chapter describes how to use the User Messaging Service (UMS) EJB API to
develop applications, and describes how to build two sample applications,
usermessagingsample-ejb.ear and usermessagingsample-echo-ejb.ear.
The User Messaging Service EJB API (described in this
chapter) is deprecated. Use the User Messaging Service Java API
instead, as described in Chapter 64, "Sending and Receiving Messages
using the User Messaging Service Java API".
Note:
Section 63.5, "Using the UMS Enterprise JavaBeans Client API to Build a Client
Application"
Section 63.6, "Using the UMS Enterprise JavaBeans Client API to Build a Client
Echo Application"
Section 63.7, "Creating a New Application Server Connection"
To learn more about the code samples for Oracle User
Messaging Service, or to run the samples yourself, see the samples at:
Note:
http://www.oracle.com/technetwork/indexes/samplecode
/sample-ums-1454424.html
oracle.sdp.messaging
Sending and Receiving Messages using the User Messaging Service EJB API
63-1
oracle.sdp.messaging.userprefs
oracle.sdp.messaging.userprefs.tools
Whichever application module is selected uses the UMS Client API to register the
application with the UMS Server and subsequently invoke operations to send or
retrieve messages, status, and register or unregister access points. For a complete list of
operations refer to the UMS Javadoc.
The samples with source code are available on Oracle Technology Network (OTN).
Sending a Message
Example 632
Sending and Receiving Messages using the User Messaging Service EJB API
63-3
Sending a Message
63-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending a Message
Address recipient =
AddressFactory.getInstance().createAddress("Email:john.doe@example.com");
63.3.5.2.2 Creating Multiple Address Objects in a Batch Example 637 shows code for
creating multiple Address objects in a batch:
Example 637
63.3.5.2.3 Adding Sender or Recipient Addresses to a Message Example 638 shows code
for adding sender or recipient addresses to a message:
Example 638
Address sender =
AddressFactory.getInstance().createAddress("Email:john.doe@example.com");
Address recipient =
AddressFactory.getInstance().createAddress("Email:jane.doe@example.com");
message.addSender(sender);
message.addRecipient(recipient);
Sending and Receiving Messages using the User Messaging Service EJB API
63-5
Receiving a Message
Address recipient =
AddressFactory.getInstance().createAddress(recipientWithFailoverStr);
or,
Status[] statuses = messagingClient.getStatus(messageId, address[]) --- where
address[] is an array of one or more of the recipients set in the message.
2.
3.
4.
63-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Receiving a Message
Note:
Sending and Receiving Messages using the User Messaging Service EJB API
63-7
Using the UMS Enterprise JavaBeans Client API to Build a Client Application
MessageFilter senderFilter =
MessageFilterFactory.createBlacklistFilter("spammer@foo.com");
messagingClient.registerMessageFilter(senderFilter);
63.5 Using the UMS Enterprise JavaBeans Client API to Build a Client
Application
This section describes how to create an application called usermessagingsample, a web
client application that uses the UMS Enterprise JavaBeans Client API for both
outbound messaging and the synchronous retrieval of message status.
usermessagingsample also supports inbound messaging. Once you have deployed and
configured usermessagingsample, you can use it to send a message to an email client.
To learn more about the code samples for Oracle User
Messaging Service, or to run the samples yourself, see the Oracle SOA
Suite samples.
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
Of the two application modules choices described in Section 63.1.1, "Creating a Java EE
Application Module," this sample focuses on the Web Application Module (WAR),
which defines some HTML forms and servlets. You can examine the code and
corresponding XML files for the web application module from the provided
usermessagingsample-src.zip source. The servlets uses the UMS Enterprise
JavaBeans Client API to create an UMS Enterprise JavaBeans Client instance (which in
turn registers the application's info) and sends messages.
This application, which is packaged as an Enterprise Archive file (EAR) called
usermessagingsample-ejb.ear, has the following structure:
usermessagingsample-ejb.ear
META-INF
META-INF
ejb-jar.xml
weblogic-ejb-jar.xml
WEB-INF
web.xml
weblogic.xml
63-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Application
2.
3.
4.
Enter the name of the SMTP mail server as the value for the
OutgoingMailServer property.
This sample application is generic and can support outbound
messaging through other channels when the appropriate messaging
drivers are deployed and configured.
Note:
Sending and Receiving Messages using the User Messaging Service EJB API
63-9
Using the UMS Enterprise JavaBeans Client API to Build a Client Application
Satisfy the build dependencies for the sample application by ensuring the "Oracle
UMS Client" library is used by the web module.
1.
2.
3.
Click OK.
3.
4.
Explore the Java files under the usermessagingsample-web project to see how the
messaging client APIs are used to send messages, get statuses, and synchronously
receive messages. The application info that is registered with the UMS Server is
specified programmatically in SampleUtils.java in the project
(Example 6310).
63-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Application
2.
3.
4.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample, you must configure any additional drivers in
Oracle User Messaging Service and optionally configure a default device for the
user receiving the message in User Messaging Preferences.
Refer to Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for more
information.
Note:
Launch a web browser and enter the address of the sample application as follows:
http://host:http-port/usermessagingsample/. For example, enter
http://localhost:7001/usermessagingsample/ into the browsers
navigation bar.
When prompted, enter login credentials. For example, username weblogic. The
browser page for testing messaging samples appears (Figure 634).
Sending and Receiving Messages using the User Messaging Service EJB API 63-11
Using the UMS Enterprise JavaBeans Client API to Build a Client Application
2.
Click Send sample message. The Send Message page appears (Figure 635).
3.
4.
63-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
5.
6.
Click Send. The Message Status page appears, showing the progress of transaction
(Message received by Messaging engine for processing in Figure 636).
7.
Click Refresh to update the status. When the email message has been delivered to
the email server, the Status Content field displays Outbound message delivery to
remote gateway succeeded.
63.6 Using the UMS Enterprise JavaBeans Client API to Build a Client
Echo Application
This section describes how to create an application called usermessagingsample-echo,
a demo client application that uses the UMS Enterprise JavaBeans Client API to
asynchronously receive messages from an email address and echo a reply back to the
sender.
To learn more about the code samples for Oracle User
Messaging Service, or to run the samples yourself, see the Oracle SOA
Suite samples.
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
This application, which is packaged as a Enterprise Archive file (EAR) called
usermessagingsample-echo-ejb.ear, has the following structure:
usermessagingsample-echo-ejb.ear
META-INF
META-INF
Sending and Receiving Messages using the User Messaging Service EJB API 63-13
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
ejb-jar.xml
weblogic-ejb-jar.xml
META-INF
ejb-jar.xml
weblogic-ejb-jar.xml
WEB-INF
web.xml
weblogic.xml
2.
3.
4.
Enter the name of the SMTP mail server as the value for the OutgoingMailServer
property.
Enter the name of the IMAP4/POP3 mail server as the value for the
IncomingMailServer property. Also, configure the incoming user name, and
password.
This sample application is generic and can support inbound
and outbound messaging through other channels when the
appropriate messaging drivers are deployed and configured.
Note:
63-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
Note:
2.
3.
Verify that the build dependencies for the sample application have been satisfied
by checking that the following library has been added to the
usermessagingsample-echo-web and usermessagingsample-echo-ejb
modules.
2.
Sending and Receiving Messages using the User Messaging Service EJB API 63-15
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
3.
Click OK.
4.
5.
Explore the Java files under the usermessagingsample-echo-ejb project to see how
the messaging client APIs are used to asynchronously receive messages
(ClientReceiverBean), and send messages (ClientSenderBean).
6.
7.
Note that the application info that is registered with the UMS Server is specified
declaratively in the usermessagingclient-ejb projects ejb-jar.xml file.
(Example 6311).
63-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
sdpm/MessageListenerSessionBeanJNDIName
</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>
ejb/umsEchoApp/ClientReceiverLocal</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>
sdpm/MessageListenerSessionBeanHomeClassName</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>
oracle.sdp.messaging.sample.ejbApp.ClientReceiverHomeLocal
</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>
sdpm/StatusListenerSessionBeanJNDIName
</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>ejb/umsEchoApp/ClientReceiverLocal</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>sdpm/StatusListenerSessionBeanHomeClassName</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>oracle.sdp.messaging.sample.ejbApp.ClientReceiverHomeLocal</env-e
ntry-value>
</env-entry>
8.
Note that the Application Name (UMSEchoApp) and Application Instance Name
(UMSEchoAppInstance) are also used in the Message Selector for the
MessageDispatcherBean MDB, which is used for asynchronous receiving of
messages and statuses placed in the application receiving queue (Example 6312).
Note:
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
2.
3.
4.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample you must configure any additional drivers in
Oracle User Messaging Service and optionally configure a default device for the
user receiving the message in User Messaging Preferences.
Refer to Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for more
information.
Note:
Launch a web browser and enter the address of the sample application as follows:
http://host:http-port/usermessagingsample-echo/. For example,
enter http://localhost:7001/usermessagingsample-echo/ into the
browsers navigation bar.
When prompted, enter login credentials. For example, username weblogic. The
browser page for testing messaging samples appears (Figure 6310).
63-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Using the UMS Enterprise JavaBeans Client API to Build a Client Echo Application
Figure 6310
2.
Figure 6311
3.
4.
Select the Action Register and Click Submit. The registration status page appears,
showing "Registered" in Figure 6312).
Sending and Receiving Messages using the User Messaging Service EJB API 63-19
5.
Send a message from your messaging client (for email, your email client) to the
address you just registered as an access point in the previous step.
If the UMS messaging driver for that channel is configured correctly, you should
expect to receive an echo message back from the usermessagingsample-echo
application.
2.
3.
63-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Enter the authentication information. A typical value for user name is weblogic.
5.
In the Connection dialog, enter the hostname, port, and SSL port for the SOA
admin server, and enter the name of the domain for WLS Domain.
6.
Click Next.
7.
8.
Sending and Receiving Messages using the User Messaging Service EJB API 63-21
63-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
64
Sending and Receiving Messages using the
User Messaging Service Java API
64
This chapter describes how to use the User Messaging Service (UMS) client API to
develop applications. This API serves as a programmatic entry point for Fusion
Middleware application developers to incorporate messaging features within their
enterprise applications.
Because the API provides a plain old java (POJO/POJI) programming model, this
eliminates the needs for application developers to package and implement various
Java EE modules (such as an EJB module) in an application to access UMS features.
This reduces application development time because developers can create applications
to run in a Java EE container without performing any additional packaging of
modules, or obtaining specialized tools to perform such packaging tasks.
Consumers of the UMS Java API are not required to use any Java EE mechanism such
as environment entries or other Java EE deployment descriptor artifacts. Besides the
overhead involved in maintaining Java EE descriptors, many client applications
already have a configuration framework that does not rely on Java EE descriptors.
This chapter includes the following sections:
Section 64.2, "Creating a UMS Client Instance and Specifying Runtime Parameters"
Section 64.9, "Using the UMS Client API to Build a Client Application"
Section 64.10, "Using the UMS Client API to Build a Client Echo Application"
Note:
http://www.oracle.com/technetwork/indexes/samplecode/samp
le-ums-1454424.html
Sending and Receiving Messages using the User Messaging Service Java API
64-1
oracle.sdp.messaging
The samples with source code are available on Oracle Technology Network (OTN).
Parameter
Notes
APPLICATION_NAME
APPLICATION_INSTANCE_NAME
SDPM_SECURITY_PRINCIPAL
64-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending a Message
Notes
MESSAGE_LISTENER_THREADS
STATUS_LISTENER_THREADS
RECEIVE_ACKNOWLEDGEMENT_MODE
LISTENER_ACKNOWLEDGEMENT_MODE
64-3
Sending a Message
Creating a Message
Addressing a Message
or
Message message = MessagingFactory.createMessage();
message.setContent("This is a Plain Text message.", "text/plain");
Sending a Message
Sending and Receiving Messages using the User Messaging Service Java API
64-5
Sending a Message
64.3.5.2.2 Creating Multiple Address Objects in a Batch Example 646 shows code for
creating multiple Address objects in a batch:
Example 646
64.3.5.2.3 Adding Sender or Recipient Addresses to a Message Example 647 shows code
for adding sender or recipient addresses to a message:
Example 647
64-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Example 649 shows how to specify a user recipient and supply facts for business
terms for the user preferences in a message. For a complete list of supported business
terms, refer to Chapter 67, "User Messaging Preferences."
Example 649
or,
Status[] statuses = messagingClient.getStatus(messageId, address[]) --- where
address[] is an array of one or more of the recipients set in the message.
Sending and Receiving Messages using the User Messaging Service Java API
64-7
Receiving a Message
concrete class - one of your existing classes, a new class, or an anonymous or inner
class.
The following code example shows how to implement a status listener:
import oracle.sdp.messaging.Listener;
public class StatusListener implements Listener {
@Override
public void onMessage(Message message, Serializable correlator) {
}
@Override
public void onStatus(Status status, Serializable correlator) {
System.out.println("Received Status: " + status + " with optional
correlator: " +
correlator);
}
}
64-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Receiving a Message
client application can then invoke the receive method to fetch the pending messages.
When receiving messages without specifying an access point, the application receives
messages for any of the access points that it has registered. Otherwise, if an access
point is specified, the application receives messages sent to that access point.
AccessPoint represents one or more device addresses to receive incoming messages.
An application that wants to receive incoming messages must register one or more
access points that represent the recipient addresses of the messages. The server
matches the recipient address of an incoming message against the set of registered
access points, and routes the incoming message to the application that registered the
matching access point.
You can use MessagingFactory.createAccessPoint to create an access point
and MessagingClient.registerAccessPoint to register it for receiving
messages.
To register an SMS access point for the number 9000:
AccessPoint accessPointSingleAddress =
MessagingFactory.createAccessPoint(AccessPoint.AccessPointType.SINGLE_ADDRESS,
DeliveryType.SMS, "9000");
messagingClient.registerAccessPoint(accessPointSingleAddress);
Note:
Sending and Receiving Messages using the User Messaging Service Java API
64-9
Receiving a Message
64-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Configuring Security
Sending and Receiving Messages using the User Messaging Service Java API 64-11
Threading Model
To use the UMS Java API from an EJB (either a Message Driven Bean or a Session
Bean) application, the recommended approach is to create a MessagingClient
instance in the bean s ejbCreate (or equivalent @PostConstruct) method,
and store the MessagingClient in an instance variable in the bean class. The EJB
container ensures that only one thread at a time uses a given EJB instance, which
ensures that only one thread at a time accesses the bean s MessagingClient
instance.
To use the UMS Java API from a Servlet, there are several possible approaches. In
general, web containers create a single instance of the servlet class, which may be
accessed by multiple threads concurrently. If a single MessagingClient instance
is created and stored in a servlet instance variable, then access to the instance must
be synchronized.
Another approach is to create a pool of MessagingClient instances that are
shared among servlet threads.
Finally, you can associate individual MessagingClient instances with
individual HTTP Sessions. This approach allows increased concurrency compared
to having a single MessagingClient for all servlet requests. However, it is
possible for multiple threads to access an HTTP Session at the same time due to
concurrent client requests, so synchronization is still required in this case.
64-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
This sample focuses on a Web Application Module (WAR), which defines some HTML
forms and servlets. You can examine the code and corresponding XML files for the
web application module from the provided usermessagingsample-src.zip
source. The servlets uses the UMS Client API to create an UMS Client instance (which
in turn registers the application's information) and sends messages.
This application, which is packaged as a Enterprise ARchive file (EAR) called
usermessagingsample.ear, has the following structure:
usermessagingsample.ear
META-INF
WEB-INF
web.xml
weblogic.xml
2.
Sending and Receiving Messages using the User Messaging Service Java API 64-13
3.
4.
Enter the name of the SMTP mail server as the value for the
OutgoingMailServer property.
This sample application is generic and can support outbound
messaging through other channels when the appropriate messaging
drivers are deployed and configured.
Note:
64-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Satisfy the build dependencies for the sample application by ensuring the "Oracle
UMS Client" library is used by the web module.
1.
2.
3.
3.
Click OK.
Explore the Java files under the usermessagingsample-web project to see how the
messaging client APIs are used to send messages, get statuses, and synchronously
receive messages. The MessagingClient instance is created in
SampleUtils.java in the project.
Sending and Receiving Messages using the User Messaging Service Java API 64-15
1.
2.
3.
4.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample, you must configure any additional drivers in
Oracle User Messaging Service and optionally configure a default device for the
user receiving the message in User Messaging Preferences.
Refer to Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for more
information.
Note:
Launch a web browser and enter the address of the sample application as follows:
http://host:http-port/usermessagingsample/. For example, enter
http://localhost:7001/usermessagingsample/ into the browsers
navigation bar.
When prompted, enter login credentials. For example, username weblogic. The
browser page for testing messaging samples appears (Figure 645).
64-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Click Send sample message. The Send Message page appears (Figure 646).
3.
4.
5.
6.
Click Send. The Message Status page appears, showing the progress of transaction
(Message received by Messaging engine for processing in Figure 647).
7.
Click Refresh to update the status. When the email message has been delivered to
the email server, the Status Content field displays Outbound message delivery to
remote gateway succeeded., as illustrated in Figure 648.
64.10 Using the UMS Client API to Build a Client Echo Application
This section describes how to create an application called usermessagingsample-echo,
a demo client application that uses the UMS Client API to asynchronously receive
messages from an email address and echo a reply back to the sender.
64-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
This application, which is packaged as a Enterprise Archive file (EAR) called
usermessagingsample-echo.ear, has the following structure:
usermessagingsample-echo.ear
META-INF
WEB-INF
web.xml
weblogic.xml
2.
3.
4.
Enter the name of the SMTP mail server as the value for the OutgoingMailServer
property.
Enter the name of the IMAP4/POP3 mail server as the value for the
IncomingMailServer property. Also, configure the incoming user name, and
password.
Sending and Receiving Messages using the User Messaging Service Java API 64-19
Note:
Note:
2.
In the Oracle JDeveloper main window the project appears (Figure 6410).
64-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 6410
3.
Verify that the build dependencies for the sample application have been satisfied
by checking that the following library has been added to the
usermessagingsample-echo-web module.
2.
Sending and Receiving Messages using the User Messaging Service Java API 64-21
3.
4.
Click OK.
2.
3.
4.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample you must configure any additional drivers in
Oracle User Messaging Service and optionally configure a default device for the
user receiving the message in User Messaging Preferences.
64-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Launch a web browser and enter the address of the sample application as follows:
http://host:http-port/usermessagingsample-echo/. For example,
enter http://localhost:7001/usermessagingsample-echo/ into the
browsers navigation bar.
When prompted, enter login credentials. For example, username weblogic. The
browser page for testing messaging samples appears (Figure 6413).
Figure 6413
2.
Sending and Receiving Messages using the User Messaging Service Java API 64-23
3.
4.
Select the Action Register and Click Submit. The registration status page appears,
showing "Registered" in Figure 6415).
5.
Send a message from your messaging client (for email, your email client) to the
address you just registered as an access point in the previous step.
If the UMS messaging driver for that channel is configured correctly, you should
expect to receive an echo message back from the usermessagingsample-echo
application.
64-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
1.
Figure 6416
2.
3.
Figure 6417
4.
Enter the authentication information. A typical value for user name is weblogic.
5.
In the Connection dialog, enter the hostname, port, and SSL port for the SOA
admin server, and enter the name of the domain for WLS Domain.
6.
Click Next.
7.
8.
Sending and Receiving Messages using the User Messaging Service Java API 64-25
64-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
65
Sending and Receiving Messages using the
User Messaging Service Web Service API
65
This chapter describes how to use the User Messaging Service (UMS) Web Service API
to develop applications. This API serves as a programmatic entry point for Fusion
Middleware application developers to implement UMS messaging applications that
run in a remote container relative to the UMS server.
This chapter includes the following sections:
Section 65.2, "Creating a UMS Client Instance and Specifying Runtime Parameters"
Note:
http://www.oracle.com/technetwork/indexes/samplecode
/sample-ums-1454424.html
Sending and Receiving Messages using the User Messaging Service Web Service API 65-1
oracle.ucs.messaging.ws
oracle.ucs.messaging.ws.types
The samples with source code are available on Oracle Technology Network (OTN).
Key
Use
javax.xml.ws.BindingProvider.ENDP
OINT_ADDRESS_PROPERTY
javax.xml.ws.BindingProvider.USEN
AME_PROPERTY
oracle.ucs.messaging.ws.ClientCon
stants.POLICIES
oracle.wsm.security.util.SecurityConstants.C
onfig.KEYSTORE_RECIPIENT_ALIAS_
PROPERTY
65-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending a Message
Example 652 shows code for creating a MessagingClient instance using SAML
token security, using the programmatic approach:
Example 652 Programmatic Approach to Creating a MessagingClient Instance, SAML
Token Security
HashMap<String, Object> config = new HashMap<String, Object>();
config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://example.com:8001/ucs/messaging/webservice");
config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_saml_token_
identity_switch_with_message_protection_client_policy"});
config.put(BindingProvider.USERNAME_PROPERTY, "user1");
config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_
LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_
SUBJECT);
config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_
ALIAS_PROPERTY, "example.com");
config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp");
mClient = new MessagingClient(config);
Sending and Receiving Messages using the User Messaging Service Web Service API 65-3
Sending a Message
65-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending a Message
mp_partPlain.setDataHandler(new DataHandler(plainDS));
mp.addBodyPart(mp_partPlain);
MimeBodyPart mp_partRich = new MimeBodyPart();
StringDataSource richDS = new StringDataSource(
"<html><head></head><body><b><i>This is an HTML part.</i></b></body></html>",
"text/html");
mp_partRich.setDataHandler(new DataHandler(richDS));
mp.addBodyPart(mp_partRich);
message.setContent(new DataHandler(mp, mp.getContentType()));
Sending a Message
65.3.4.2.2 Creating Multiple Address Objects in a Batch Example 658 shows code for
creating multiple Address objects in a batch:
Example 658
65.3.4.2.3 Adding Sender or Recipient Addresses to a Message Example 659 shows code
for adding sender or recipient addresses to a message:
Example 659
65-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending a Message
Note:
Example 6511 shows how to specify a user recipient and supply facts for business
terms for the user preferences in a message. For a complete list of supported business
terms, refer to Chapter 67, "User Messaging Preferences."
Example 6511 User Preference Based Messaging
Message message = MessagingFactory.createMessage();
// create and add a user recipient
Address userRecipient1 = MessagingFactory.createAddress("USER:sampleuser1");
message.addRecipient(userRecipient1);
// specify business term facts
MessagingFactory.setMetadata(message, oracle.sdp.messaging.Message.NAMESPACE_
Sending and Receiving Messages using the User Messaging Service Web Service API 65-7
or,
List<Status> statuses = messagingClient.getStatus(messageId, addresses) --- where
addresses is a "List<Address>" of one or more of the recipients set in the
message.
65-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Receiving a Message
65.4.2.4 Registration
Once the listener web service is published, you must register the fact that your client
has such an endpoint. There are the following relevant methods in the
MessagingClient API:
setStatusListener(ListenerReference listener)
Sending and Receiving Messages using the User Messaging Service Web Service API 65-9
Receiving a Message
Note:
65-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Receiving a Message
65-11
65-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Configuring Security
Sending and Receiving Messages using the User Messaging Service Web Service API
65-13
Threading Model
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
Note:
65.9.1 Overview
This sample demonstrates how to create a web-based chat application to send and
receive messages through email, SMS, or IM. The sample uses the Web Service APIs to
interact with a User Messaging server. You define an application server connection in
Oracle JDeveloper, and deploy and run the application.
The application is provided as a pre-built Oracle JDeveloper project that includes a
simple web chat interface.
65-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Sending and Receiving Messages using the User Messaging Service Web Service API
65-15
The application contains one web module. All of the source code for the
application is in place.
2.
Satisfy the build dependencies for the sample application by ensuring the "Oracle
UMS Client" library is used by the web module.
1.
2.
65-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Click OK.
3.
4.
5.
6.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
2.
Sending and Receiving Messages using the User Messaging Service Web Service API
65-17
http://host:port/usermessagingsample-ws/
The Messaging Web Services Sample web page appears (Figure 655). This page
contains navigation tabs and instructions for the application.
Figure 655 Messaging Web Services Sample Web Page
3.
65-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click Save.
5.
Click Manage.
6.
7.
Click Start.
Verify that the message Registration operation succeeded appears.
8.
Sending and Receiving Messages using the User Messaging Service Web Service API
65-19
9.
Enter recipients in the To: field in the format illustrated in Figure 658.
65-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
Figure 6510
4.
Enter the authentication information. A typical value for user name is weblogic.
5.
In the Connection dialog, enter the hostname, port, and SSL port for the SOA
admin server, and enter the name of the domain for WLS Domain.
6.
Click Next.
7.
8.
Sending and Receiving Messages using the User Messaging Service Web Service API
65-21
65-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
66
Parlay X Web Services Multimedia
Messaging API
This chapter describes the Parlay X Multimedia Messaging web service that is
available with Oracle User Messaging Service and how to use the Parlay X Web
Services Multimedia Messaging API to send and receive messages through Oracle
User Messaging Service.
To learn about the architecture and components of Oracle User Messaging Service, see
Oracle Fusion Middleware Getting Started with Oracle SOA Suite.
The Parlay X Multimedia Messaging API (described in this
chapter) is deprecated. Use the User Messaging Service Java API
instead, as described in Chapter 64, "Sending and Receiving Messages
using the User Messaging Service Java API"".
Note:
Section 66.5, "Parlay X Messaging Client API and Client Proxy Packages"
Note:
http://www.oracle.com/technetwork/indexes/samplecode
/sample-ums-1454424.html
Note:
66-1
tables, describing input/output message parameters for each operation, are taken
directly from the Parlay X specification.
Oracle User Messaging Service implements a subset of the Parlay X 2.1 Multimedia
Messaging specification. Specifically Oracle User Messaging Service supports the
SendMessage and ReceiveMessage interfaces. The MessageNotification and
MessageNotificationManager interfaces are not supported.
Part Name
Part Type
Optional
Description
addresses
xsd:anyURI[0..unbounded]
No
senderAddress
xsd:string
Yes
66-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part Type
Optional
Description
subject
xsd:string
Yes
priority
MessagePriority
Yes
charging
common:
ChargingInformation
Yes
receiptRequest
common:SimpleReference
Yes
Part Name
Part Type
Optional
Description
result
xsd:string
No
Part Name
Part Type
Optional
Description
registrationIdentifier
xsd:string
No
66-3
Table 664
Part Name
Part Type
Optional
Description
result
DeliveryInformation
[0..unbounded]
Yes
The registration ID parameter is a string that identifies the endpoint address for
which the application wants to receive messages. See the discussion of the
ReceiveMessageManager interface for more details.
The Parlay X specification says that if the registration ID is not specified, all
messages for this application should be returned. However, the WSDL says that
the registration ID parameter is mandatory. Therefore our implementation treats
the empty string ("") as the "not-specified" value. If you call getReceivedMessages
with the empty string as your registration ID, you get all messages for this
application. Therefore the empty string is not an allowed value of registration ID
when calling startReceiveMessages.
According to the Parlay X specification, if the received message content is "pure
ASCII text", then the message content is returned inline within the
MessageReference object, and the messageIdentifier (Message ID) element is null.
Our implementation treats any content with Content-Type "text/plain", and with
encoding "us-ascii" as "pure ASCII text" for the purposes of this operation. As per
the MIME specification, if no encoding is specified, "us-ascii" is assumed, and if no
Content-Type is specified, "text/plain" is assumed.
The priority parameter is currently ignored.
Part Name
Part Type
Optional
Description
registrationIdentifier
xsd:string
No
66-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part Type
Optional
Description
priority
MessagePriority
Yes
Part Name
Part Type
Optional
Description
registrationIdentifier
xsd:string
No
priority
MessagePriority
Yes
Part Name
Part Type
Optional
Description
messageRefIdentifier
xsd:string
No
These URIs are HTTP URLs that can be dereferenced to retrieve the content.
If the inbound message has a Content-Type of "multipart", then there are multiple
URIs returned, one per subpart. If the Content-Type is not "multipart", then a
single URI are returned.
Per the Parlay X specification, if the inbound messages a body text part, defined as
"the message body if it is encoded as ASCII text", it is returned inline within the
66-5
MessageURI object. For the purposes of our implementation, you define this
behavior as follows:
If the message's Content-Type is "text/*" (any text type), and if the charset
parameter is "us-ascii", then the content is returned inline in the MessageURI
object. There are no URIs returned since there is no content other than what is
returned inline.
Per the MIME specification, if the charset parameter is omitted, the default
value of "us-ascii" is assumed. If the Content-Type header is not specified for
the message, then a Content-Type of "text/plain" is assumed.
Part Name
Part Type
Optional
Description
messageRefIdentifier
xsd:string
No
Part Name
Part Type
Optional
Description
result
MessageURI
No
66-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part Name
Part Type
Optional
Description
registrationIdentifier
xsd:string
No
A registration identifier.
messageService
ActivationNumber
xsd:anyURI
No
criteria
xsd:string
Yes
Descriptive string.
66-7
Table 6611
Part Name
Part Type
Optional
Description
registrationIdentifier
xsd:string
No
A registration identifier.
oracle.sdp.parlayx.multimedia_
messaging.send.SendMessageClient
oracle.sdp.parlayx.multimedia_
messaging.receive.ReceiveMessageClient
oracle.sdp.parlayx.multimedia_messaging.extension.receive_
manager.ReceiveMessageManager
Each client class allows a client application to invoke the operations in the
corresponding interface. Additional web service parameters such as the remote
gateway URL and any required security credentials, are provided when an instance of
the client class is constructed. See the Javadoc for more details. The security credentials
are propagated to the server using standard WS-Security headers, as mandated by the
Parlay X specification.
The general process for a client application is to create one of the client classes above,
set the necessary configuration items (endpoint, username, password), then invoke
one of the business methods (for example, SendMessageClient.sendMessage(),
and so on). For examples of how to use this API, see the Messaging samples on Oracle
Technology Network (OTN), and specifically
usermessagingsample-parlayx-src.zip.
Note:
Once you have navigated to this page, you can find code samples for
Oracle User Messaging Service by entering the search term "UMS" and
clicking Search.
66-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
66.6.1 Overview
This sample demonstrates how to create a web-based chat application to send and
receive messages through email, SMS, or IM. The sample uses standards-based Parlay
X Web Service APIs to interact with a User Messaging server. The sample application
includes web service proxy code for each of three web service interfaces: the
SendMessage and ReceiveMessage services defined by Parlay X, and the
ReceiveMessageManager service which is an Oracle extension to Parlay X. You define
an application server connection in Oracle JDeveloper, and deploy and run the
application.
The application is provided as a pre-built Oracle JDeveloper project that includes a
simple web chat interface.
Project the directory containing the archived Oracle JDeveloper project files.
Readme.txt.
Release notes
66-9
2.
In Oracle JDeveloper, select File > Open..., then navigate to the directory above
and open workspace file "usermessagingsample-parlayx.jws".
This opens the precreated JDeveloper application for the Parlay X sample
application. The application contains one web module. All of the source code for
the application is in place. You must configure the parameters that are specific to
your installation.
3.
Satisfy the build dependencies for the sample application by ensuring the "Oracle
UMS Client" library is used by the web module.
1.
2.
66-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
Click OK.
4.
5.
6.
7.
8.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample you must configure any additional drivers in
Oracle User Messaging Service and configure a default device for the user
receiving the message in User Messaging Preferences, as described in the
following sections.
Note:
2.
3.
66-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
4.
Click Save.
5.
Click Manage.
6.
7.
Click Start.
Verify that the message Registration operation succeeded appears.
8.
9.
Enter recipients in the To: field in the format illustrated in Figure 667.
66-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
4.
5.
In the Connection dialog, enter the hostname, port and SSL port for the SOA
admin server, and enter the name of the domain for the Oracle WebLogic Server
Domain.
6.
Click Next.
7.
8.
66-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
67
User Messaging Preferences
This chapter describes the User Messaging Preferences that are packaged with Oracle
User Messaging Service. It describes how to work with messaging channels and to
create contact rules using messaging filters.
To learn about the architecture and components of Oracle User
Messaging Service, see Oracle Fusion Middleware Getting Started with
Oracle SOA Suite.
Note:
67.1.1 Terminology
User Messaging Preferences defines the following terminology:
Channel: the transport type, for example, email, voice, or SMS. Also, generally, a
physical channel, such as a phone, or PDA.
Channel address: one of the addresses that a channel can communicate with.
User Messaging Preferences 67-1
Operators: comparison operators equals, does not equal, contains, or does not contain.
Facts: data passed in from the message to be evaluated, such as time sent, or sender.
Rules Engine: the User Messaging Preferences component that processes and
evaluates filters.
Comparison: a rule term and the associated comparison operator.
Action: the action to be taken if the specified conditions in a rule are true, such as
Broadcast to All, Failover, or Do not Send to Any Channel.
One use case for notification delivery preference is for bugs entered into a bug tracking
system. For example, user Alex wants to be notified through SMS and EMAIL channels
for bugs filed against his product with priority = 1 by a customer type = Premium. For
all other bugs with priority > 1, he only wants to be notified by EMAIL. Alexs
preferences can be stated as follows:
Example 671
Rule (1): if (Customer Type = Premium) AND (priority = 1) then notify [Alex] using
SMS and EMAIL.
Rule (2): if (Customer Type = Premium) AND (priority > 1) then notify [Alex] using
EMAIL.
A runtime service, the Oracle Rules Engine, evaluates the filters to process the
notification delivery of user requests.
Supported Values
Date
isEqual, isNotEqual,
isGreaterThan,
isGreaterThanOrEqua
l, isLessThan,
isLessThanOrEqual,
Between, isWeekday,
isWeekend
Time
isEqual, isNotEqual,
Between
Number (Decimal)
String
isEqual, isNotEqual,
Contains,
NotContains
Data Type
Note:
System Term
Data Type
Supported Values
Date
Date
Time
Time
A business term consists of a key, a data type, an optional description, and an optional
List of Values (LOV).
Table 673 lists the pre-defined business terms supported by User Messaging
Preferences.
Table 673
Business Term
Data Type
Service Name
String
Process Name
String
System Code
String
Error Code
String
Occurrence Count
Number (Decimal)
Organization
String
Priority
String
Application
String
Application Type
String
Expiration Date
Date
From
String
To
String
Customer Name
String
Customer Type
String
Status
String
Amount
Number (Decimal)
Due Date
Date
Process Type
String
Expense Type
String
Total Cost
Number (Decimal)
Processing Time
Number (Decimal)
Order Type
String
String
Group Name
String
Source
String
Classification
String
Duration
Number (Decimal)
User
String
Role
String
67-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
Any channel that a user creates is associated with that users system ID. In Oracle User
Messaging Service, channels represent both physical channels, such as mobile phones,
and also email client applications running on desktops, and are configurable on the
The Messaging Channels tab (Figure 671).
The Messaging Channels tab enables users to perform the following tasks:
2.
Enter a name for the channel in the Name field (Figure 673).
3.
Select the channels transport type from the Type dropdown menu.
4.
Enter the number or address appropriate to the transport type you selected.
5.
Select the Default checkbox to set the channel as a default channel. You can have
multiple default channels.
67-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
6.
Click OK to create the channel. The channel appears on the Channels page. The
Channels page enables you to edit or delete the channel.
Certain channels are based on information retrieved from your user profile in the
identity store, and this address cannot be modified by User Messaging Preferences
(Figure 675). The only operation that can be performed on such as channel is to make
it the default.
Note:
67-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Figure 679 illustrates the creation of a filter called Travel Filter, by a user named
weblogic, for handling notifications regarding Customers during his travel.
Notifications that match all of the filter conditions are first directed to his "Business
Mobile" channel. Should this channel become unavailable, Oracle User Messaging
Service transmits the notifications as e-mails since the next available channel selected
is Business Email.
Click Create (Figure 672). The Create Filter page appears (Figure 679).
2.
3.
4.
Select whether notifications must meet all of the conditions or any of the
conditions by selecting either the All of the following conditions or Any of the
following conditions options.
5.
Define the filter conditions using the lists and fields of the Condition section as
follows:
a.
Select the notification's attributes. Refer to Table 673 for a list of these
attributes.
b.
Combine the selected condition type with one of the comparison operators
described in Table 671.
c.
For instance, if you select the Date attribute, select one of the comparison
operators and then select the appropriate dates from the date chooser.
6.
Click Add (Figure 676) to add the attribute and the comparison operators to the
table.
67-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Configuring Settings
7.
Repeat these steps to add more filter conditions. To delete a filter condition, click
Delete (Figure 676).
8.
9.
Send Messages to all Selected Channels -- Select this option to send messages
to every listed channel.
Send to the First Available Channel (Failover in the order) -- Select this
option to send messages matching the filter criteria to a preferred channel (set
using the up and down arrows) or to the next available channel.
Send No Messages -- Select this option to block the receipt of any messages
that meet the filter conditions.
To set the delivery channels, select a channel from the Add Notification Channel
list and then click Add (Figure 676). To delete a channel, click Delete
(Figure 676).
10. If needed, use the up and down arrows to prioritize channels. If available, the
top-most channel receives messages meeting the filter criteria if you select Send to
the First Available Channel.
11. Click OK to create the filter. Clicking Cancel discards the filter.
67-11
Configuring Settings
67-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Part XII
Part XII
Appendices
Appendix D, "Understanding Sensor Public Views and the Sensor Actions XSD"
A
BPEL Process Activities and Services
This appendix describes the BPEL process activities and services that you use when
designing a BPEL process in a SOA composite application. It also describes how to
publish and browse the Oracle Service Registry and how the Oracle Enterprise
Repository provides design-time governance.
This appendix includes the following sections:
See the following sections for additional details about these service components.
BPEL process
See Part II, "Using the BPEL Process Service Component"
Business rule
Human task
Part V, "Using the Human Workflow Service Component"
Mediator
See Part III, "Using the Oracle Mediator Service Component"
For information about Oracle BPEL Designer, see Chapter 4, "Getting Started with
Oracle BPEL Process Manager."
Activity
Display Under...
Supported in
BPEL 1.1
Assign
BPEL Constructs
Yes
Yes
Assert
Yes
Bind Entity
No
Compensate
BPEL Constructs
Yes
Yes
Section A.2.6,
"Compensate Activity"
No
Yes
Section A.2.7,
"CompensateScope
Activity"
Create Entity
No
Dehydrate
Yes
Yes
A-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Display Under...
Supported in
BPEL 1.1
Empty
BPEL Constructs
Yes
Yes
Exit
BPEL Constructs
No
Yes
BPEL Constructs
Yes
Yes
FlowN
No
BPEL Constructs
No
Yes
Note: Replaces the
FlowN activity in BPEL
2.0.
If
BPEL Constructs
No
Yes
Note: Replaces the
switch activity in BPEL
2.0.
IM
Yes
Invoke
BPEL Constructs
Yes
Yes
Java Embedding
Yes
Partner Link
BPEL Constructs
Yes
Yes
Phase
Yes
Pick
BPEL Constructs
Yes
Yes
Receive
BPEL Constructs
Yes
Yes
Receive Signal
Yes
Remove Entity
No
RepeatUntil
BPEL Constructs
No
Yes
Section A.2.26,
"RepeatUntil Activity"
Replay
Yes
Reply
BPEL Constructs
Yes
Yes
Rethrow
BPEL Constructs
No
Yes
Display Under...
Supported in
BPEL 1.1
Scope
BPEL Constructs
Yes
Yes
Sequence
BPEL Constructs
Yes
Yes
Signal
Yes
SMS
Yes
Switch
BPEL Constructs
No
Yes
BPEL Constructs
Yes
No
Note: Replaced by the
exit activity in BPEL 2.0
Throw
BPEL Constructs
Yes
Yes
Transform
Yes
User Notification
Yes
Validate
Yes
BPEL Constructs
(in BPEL 2.0)
Voice
Yes
Wait
BPEL Constructs
Yes
Yes
While
BPEL Constructs
Yes
Yes
For more information about activities, see the Business Process Execution Language for
Web Services Specification Version 1.1 or the Web Services Business Process Execution
Language Specification Version 2.0 by visiting the following URL:
http://www.oasis-open.org
A-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The Annotations tab does not provide a method for changing the order of annotations.
As a work around, change the order of annotations in the Source view of the projects
BPEL file in Oracle BPEL Designer.
Preassert: This condition is executed before the invoke or reply activity send out
the outbound message.
Postassert: This condition is executed after an invoke activity, receive activity, or
onMessage branch receives the inbound message.
For more information, see the online help for this tab and Section 12.14, "Throwing
Faults with Assertion Conditions."
Note:
For more information, see the online help for this tab and Oracle Fusion Middleware
User's Guide for Technology Adapters
Note:
For more information, see the online help for this tab and Section 10.2.3,
"Synchronizing the Execution of Activities in a Flow Activity."
A-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
You cannot copy activities from a BPEL 1.1 project to a BPEL 2.0 project or from a
BPEL 2.0 project to a BPEL 1.1 project.
In BPEL 2.0 projects, you cannot copy an individual OnAlarm activity from a pick
activity into a scope activity, or vice versa. However, this type of copying and
pasting is supported in BPEL 1.1 projects.
When you copy and paste a scope activity, the variables referenced in the first
scope activity are not copied.
Select Copy.
3.
4.
Right-click the activity closest to where you want to paste the activity.
b.
Choose to either paste the activity before or after the selected activity.
or
a.
b.
Drag the source node to the target node to create a BPEL copy rule from the source
to the target node. This action creates a line that connects the source and target
types.
Select the source node, select the target node, and then click the Add icon above
the table at the bottom of the dialog. The mapping is then added to the table and
the connecting line between the nodes is drawn in the tree.
The copy rule is displayed in the From and To sections at the bottom of the dialog.
Figure A3 Copy Rules Tab of Edit Assign Dialog
The Select Insertion Mode list above the source node section enables you to insert the
next copy rule you create either after or before the rule selected at the bottom of the
dialog.
Icons display above the target node that enable you to perform the following tasks
(from left to right) on target nodes. By default, the center canvas is open. If it is closed,
drag the bars open to display the center canvas.
Expression icon: Drag this icon to a target node to invoke the Expression Builder
dialog for assigning an XPath expression to that node. You can also drag this icon
to the center canvas to invoke this dialog, specify the expression, save and close
the dialog, and then drag the icon to the target node.
Literal (BPEL 2.0 specification) icon or XML Fragment (BPEL 1.1 specification)
icon: Drag this icon to a target node to invoke a dialog for assigning a literal (if the
BPEL project supports the BPEL 2.0 specification) or XML fragment (if the BPEL
A-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
project supports the BPEL 1.1 specification) to that target node. You can also drag
this icon to the center canvas to invoke this dialog, specify the value, save and
close the dialog, and then drag the icon to the target node.
Remove icon: Drag this icon to a target node to create a bpelx:remove extension
rule. You can also drag this icon to the center canvas to invoke this dialog, specify
the rule, save and close the dialog, and then drag the icon to the target node.
Rename icon: Drag this icon to rename a target node. This adds a bpelx:rename
extension rule with an elementTo attribute. You can also drag this icon to the
center canvas to invoke a dialog, specify the rule, save and close the dialog, and
then drag the icon to the target node.
Recast icon: Drag this icon to recast a target node. This adds a bpelx:rename
extension rule with a typeCastTo attribute. This results in an xsi:type
attribute in the XML output. You can also drag this icon to the center canvas to
invoke a dialog, specify the rule, save and close the dialog, and then drag the icon
to the target node.
You can also change a selected copy rule to a bpelx extension type
(bpelx:copyList, bpelx:insertAfter, bpelx:insertBefore, or
bpelx:append).
The method of selection differs between BPEL 1.1 and BPEL 2.0.
Figure A4 shows how you select an extension type in BPEL 1.1. You select a copy
rule, select the Copy dropdown list, and then select the appropriate extension.
Figure A4 Copy Rule Converted to bpelx Extension in BPEL 1.1
Figure A5 shows how you select an extension type in BPEL 2.0. You right-click a copy
rule, select Change rule type, and then select the appropriate extension.
For more information about manipulating XML data with bpelx extensions, see
Section 6.15, "Manipulating XML Data with bpelx Extensions."
In the From and To XPath fields, you can also place your cursor over the icon to the
left of the source type to display the operation being performed (for example, copy,
append, and so on). Each operation type is represented by a different icon. You can
also right-click a copy rule to display a list of actions to perform:
Edit 'From' expression or Edit 'To' expression: Select this option to edit XPath
expression values when the created copy rule contains a query for the source or
target node. This selection invokes the Expression Builder dialog. The menu
option that displays is based on the current content of your copy rule selection.
ignoreMissingFromData: Select this option to toggle the
ignoreMissingFromData attribute on the copy rule on and off. When toggled
on, this suppresses any bpel:selectionFailure standard faults.
insertMissingToData: Select this option to toggle the insertMissingToData
attribute on the copy rule on and off.
keepSrcElementName (in BPEL 2.0 projects only): Select this option to toggle the
keepSrcElementName attribute on the copy rule on and off. This option enables
you to replace the element name of the destination (as selected by the to-spec)
with the element name of the source.
Change Rule Type (in BPEL 2.0 projects only): Select this option to change the
type of the selected rule to one of the BPEL extension rules: bpelx:copyList,
bpelx:insertAfter, bpelx:insertBefore, or bpelx:append.
Delete rule: Select this option to delete the selected rule.
A-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
The icons above the To section enable you to add, delete, move up, and move down a
selected copy rule.
For more information about the assign activity, see the online Help for the Copy Rules
dialog and Chapter 6, "Manipulating XML Data in a BPEL Process."
If an assign activity contains multiple bpelx:append
settings, it must be split into two assign activities. Otherwise,
bpelx:append is moved to the end of the list each time, which can
cause problems. As a work around, move it manually.
Note:
For more information about the standalone assert activity, see Section 12.14.1.7,
"Assertion Conditions in a Standalone Assert Activity" and Section 12.14.4, "What
Happens When You Create Assertion Conditions."
A-11
example, the database adapter). This action enhances Oracle BPEL Process Manager
runtime performance and incorporates native features of the underlying data provider
service during compilation and runtime.
Note:
Click the General tab to provide the activity with a meaningful name.
A-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A-13
For more information about the compensateScope activity, see Section 12.12, "Using
Compensation After Undoing a Series of Operations."
For more information, see Section 6.2, "Delegating XML Data Operations to Data
Provider Services."
For BPEL projects that support BPEL version 2.0, the syntax is as shown in
Example A2.
A-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A-15
For more information about the email activity, see Section 17.3.1, "How To Configure
the Email Notification Channel."
A-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
For more information about the exit activity, see Section 12.13.2, "Immediately Ending
a Business Process Instance with the Exit Activity in BPEL 2.0."
A-17
You can also synchronize the execution of activities within a flow activity. This ensures
that certain actives only execute after other activities have completed.
Oracle's BPEL implementation executes flows in the same,
single execution thread of the BPEL process, and not in separate
threads.
Note:
For more information about the flow activity, see Section 10.2, "Creating a Parallel
Flow."
A-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the flowN activity, see Section 10.3.1, "Customizing the
Number of Flow Activities with the flowN Activity in BPEL 1.1."
A-19
For more information about the forEach activity, see Section 10.3.2, "Processing
Multiple Sets of Activities with the forEach Activity in BPEL 2.0."
A.2.16 If Activity
This activity enables you to define conditional behavior for specific activities to decide
between two or more branches. Only one activity is selected for execution from a set of
branches.
Note:
Figure A19 shows an if activity with the following defined if, elseif, and else
branches.
Figure A19 If Activity
A-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the if activity, see Section 11.2.2, "Defining Conditional
Branching with the If Activity in BPEL 2.0."
A.2.17 IM Activity
This activity enables you to send an automatic, asynchronous instant message (IM)
notification to a user, group, or destination address. Figure A20 shows the IM dialog.
Figure A20 IM Dialog
For more information, see Section 17.3.2, "How to Configure the IM Notification
Channel."
A-21
In BPEL 2.0, the Invoke dialog includes the Documentation, Targets, and Sources tabs.
For more information about the invoke activity, see the following:
A-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the Java embedding activity, see Chapter 14,
"Incorporating Java and Java EE Code in a BPEL Process."
The web services description language (WSDL) file of the external service.
A-23
In BPEL 2.0, the Partner Link dialog also includes the Documentation tab.
For more information about partner links, see Chapter 8, "Invoking an Asynchronous
Web Service from a BPEL Process."
An assign activity that includes the message request input and message response
output variables.
An invoke activity that is automatically designed to invoke an Oracle Mediator
partner link in the BPEL process.
An Oracle Mediator partner link that is automatically designed to route the
message request input variable to the business rules service component in the
SOA composite application of which this BPEL process is a part. The business
rules service component displays in the SOA Composite Editor. Oracle Mediator
also displays as a service component in the SOA Composite Editor.
A business rules service component that evaluates the content of the message
request input variable and returns the results in the message response output
variable to Oracle Mediator. Oracle Mediator then makes a routing decision and
routes the message to the correct target destinations.
A-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
A-25
OnAlarm (Does not automatically display; you must manually add this branch by
selecting the Pick activity icon and clicking the Add OnAlarm icon.)
Contains the code for a timeout, for example, after one minute.
Whichever branch completes first is executed; the other branch is not executed. The
branch that has its condition satisfied first is executed.
Figure A26 shows the OnAlarm dialog of the pick activity in BPEL 1.1.
Figure A26 OnAlarm Branch Dialog of a Pick Activity
A-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
If you add correlations to an OnMessage branch, the correlations syntax is placed after
the assign activity syntax. The correlation syntax must go before the assign activity.
To put the correlation syntax before the assign activity:
Create a correlation set in Oracle JDeveloper.
1.
2.
3.
4.
Before making or deploying the BPEL process, move the correlation syntax before
the assign activity in the BPEL source code.
For more information about the pick activity, see the following:
A-27
In BPEL 2.0, the Receive dialog includes the Documentation, Targets, and Sources
tabs.
For more information about the receive activity, see the following:
A-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information, see Chapter 16, "Coordinating Master and Detail Processes."
A-29
activity completes. The condition is evaluated repeatedly (and the body of the activity
processed) until the provided boolean condition is true. Figure A30 shows the Repeat
Until dialog.
Note:
For more information about the repeatUntil activity, see, Section 11.4, "Defining
Conditional Branching with the repeatUntil Activity."
A-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In BPEL 1.1, the Replay dialog does not include a Documentation tab, Targets tab, or
Sources tab. For more information about the replay activity, see Section 12.11,
"Re-executing Activities in a Scope Activity with the Replay Activity."
In BPEL 2.0, the Reply dialog includes the Documentation, Targets, and Sources tabs.
For more information about the reply activity, see the following:
Figure A33 shows a rethrow activity within a fault handler (catch activity).
A-31
For more information about rethrowing faults, see Section 12.8, "Rethrowing Faults
with the Rethrow Activity."
In BPEL 2.0, the Scope dialog includes the Documentation, Targets, and Sources tabs.
Fault handling is associated with a scope activity. The goal is to undo the incomplete
and unsuccessful work of a scope activity in which a fault has occurred. You define
A-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the scope activity and fault handling, see the following:
A-33
The request is processed inside a flow activity that enables concurrent behavior.
A reply message with the final approval status of the request is sent back to the
customer in a reply activity.
A sequence activity makes the assumption that the request can be processed in a
reasonable amount of time, justifying the requirement that the invoker wait for a
synchronous response (because this service is offered as a request-response operation).
When this assumption cannot be made, it is better to define the customer interaction as
a pair of asynchronous message exchanges.
When you double-click the Sequence icon, the activity area shown in Figure A37
appears. Drag and define appropriate activities inside the sequence activity.
Figure A37 Sequence Activity
For more information about the sequence activity, see the following:
For more information, see Chapter 16, "Coordinating Master and Detail Processes."
A-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about the SMS activity, see Section 17.3.3, "How to Configure the
SMS Notification Channel."
Note:
Figure A40 shows a switch activity with the following defined branches.
A-35
For more information about the switch activity, see the following:
Figure A41 shows several terminate activities in the otherwise branch of a switch
activity.
Figure A41 Terminate Activity
For more information about the terminate activity, see Section 12.13.1, "Stopping a
Business Process Instance with the Terminate Activity in BPEL 1.1."
A-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In BPEL 2.0, the Throw dialog includes the Documentation, Targets, and Sources tabs.
For more information about the throw activity, see Section 12.7, "Throwing Internal
Faults with the Throw Activity."
Click the second icon (the Add icon) to the right of the Mapper File field to access
the XSLT Mapper for creating a new XSL file for graphically mapping source and
target elements. Click the Edit icon (third icon) to edit an existing XSL file.
A-37
In BPEL 2.0, the Transform dialog includes the Documentation, Targets, and Sources
tabs.
For more information about the transform activity, see Chapter 40, "Creating
Transformations with the XSLT Mapper."
A-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information, see Section 17.4, "Allowing the End User to Select Notification
Channels."
In BPEL 2.0, the Validate dialog includes the Documentation, Targets, and Sources
tabs
For more information about the validate activity, see Section 6.16, "Validating XML
Data."
A-39
For more information about the voice activity, see Section 17.3.4, "How to Configure
the Voice Notification Channel."
A-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
In BPEL 2.0, the Wait dialog includes the Documentation, Targets, and Sources tabs.
For more information about the wait activity, see Section 15.4, "Creating a Wait
Activity to Set an Expiration Time."
In BPEL 2.0, the While dialog includes the Documentation, Targets, and Sources tabs.
A-41
For more information about the while activity, see Section 11.3, "Defining Conditional
Branching with the While Activity."
Drag and drop the service to the appropriate swimlane. Table A2 lists the
available services and provides references to documentation that describes these
services.
Table A2
BPEL Services
BPEL Service
ADF-BC services
AQ adapter
Oracle B2B
Database adapter
EJB service
File adapter
FTP adapter
A-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
HTTP binding
JMS adapter
MQ adapter
Oracle Applications
adapter
Socket adapter
Web services
OSR 11g
OSR 10.1.3
Notes:
This section does not describe how to configure OSR against the
embedded Oracle WebLogic Server in Oracle JDeveloper.
OSR 10.3 deploys to the 10.3.0.0 version of Oracle WebLogic
Server.
OSR 10.3 does not support the 10.3.1.0 version of Oracle WebLogic
Server.
A-43
You can also access the documentation by clicking the Registry Documentation link.
To publish a business service:
1. Go to the Registry Control:
http://hostname:port/registry/uddi/web
2.
3.
4.
Complete the fields on this page to specify the access point URL and publish the
WSDL for the business service.
If you later change your endpoint location, you must also
update the WSDL location in the Registry Control. Otherwise, UDDI
invocation fails during runtime. See section Section A.4.4.1, "Changing
Endpoint Locations in the Registry Control."
Note:
Select File > New > Connections > UDDI Registry Connection to create a UDDI
connection.
3.
4.
5.
6.
Click Next.
7.
8.
If successful, click Finish. Otherwise, click the Back button and correct your
errors.
A.4.3 How to Configure a SOA Project to Invoke a Service from the Registry
To configure a SOA project to invoke a service from the registry:
1. Open the SOA project in which to create a reference to the business service.
2.
3.
To the right of the WSDL URL field, click the icon to select a WSDL.
4.
5.
6.
7.
Select the published business service, and click OK. Figure A49 provides details.
A-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
9.
Click OK.
You are returned to the Create Web Service dialog.
10. See the following section based on your selection in the UDDI Deployment
Options dialog.
A-45
2.
3.
4.
If you want, you can also resolve the SOAP endpoint location by explicitly adding
the oracle.soa.uddi.servicekey property in the Property Inspector. This
action dynamically resolves the SOAP endpoint location at runtime for any
external reference to a web service. Figure A52 provides details.
a.
b.
c.
d.
e.
In the Value field, specify the value for oracle.soa.uddi.servicekey from the
composite.xml file.
A-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
3.
A-47
Table A3
Resolving Endpoints
Endpoint
Resolutions
Description
Example
Normalized
message UDDI
serviceKey
Normalized
message
endpointURI
<copy target="$out.property.endpointURI"
value="http://hostname:8001/soa-infra/services
/partition/Project/endpoint_ep"/>
composite.xml
UDDI serviceKey
composite.xml
endpointURI
The endpointURI
<binding.ws
property is specified within
port="http://xmlns.oracle.com/UDDIPublishApplica
the binding component
tion/Project/BPELProcess1#wsdl.endpoint(bpelproc
section of composite.xml. ess1_client_ep/BPELProcess1_pt)"
. . . >
Note: This can be
overwritten in Oracle
<property name="oracle.soa.uddi.endpointURI"
Enterprise Manager Fusion
value="http://hostname:8001/soa-infra/services/
Middleware Control.
Partition/Project/bpelprocess1_client_ep"</property>
</binding.ws>
composite.xml
concrete WSDL
endpoint location
<binding.ws
port="http://xmlns.oracle.com/UDDIPublishApplication
/Project/BPELProcess1#wsdl.endpoint(bpelprocess1_
client_ep/BPELProcess1_pt)"
location="http://hostname:8001/soa-infra/services
/Partition/Project/bpelprocess1_client_ep?wsdl"
soapVersion="1.1">
A-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
composite.xml endpointURI
A.4.4 How To Configure the Inquiry URL, UDDI Service Key, and Endpoint Address for
Runtime
You can set the inquiry URL, UDDI service key, and endpoint address during runtime
in Oracle Enterprise Manager Fusion Middleware Control.
To configure the inquiry URL, UDDI service key, and endpoint reference for
runtime:
1. Log in to Oracle Enterprise Manager Fusion Middleware Control.
2.
3.
In the SOA Infrastructure Common Properties page, specify the same UDDI
inquiry URL that you specified in the Create UDDI Registry Connection
wizard. For information, see section "Configuring SOA Infrastructure
Properties" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA
Suite and Oracle Business Process Management Suite.
In the Properties page of the reference binding component, you can change the
endpoint reference and service key values created during design time. For
information, see section "Configuring Service and Reference Binding
Component Properties" of Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
A-49
4.
5.
6.
Go to the Manage page and check statistics to see the increase in the number of
invocations when not cached (the first time).
Caching of WSDL URLs occurs by default during runtime. If a WSDL URL is
resolved using the orauddi protocol, subsequent invocations retrieve the WSDL
URLs from cache, and not from OSR. When an endpoint WSDL obtained from
cache is no longer reachable, the cache is refreshed and OSR is contacted to
retrieve the new endpoint WSDL location. As a best practice, Oracle recommends
that you undeploy services that are no longer required in Oracle Enterprise
Manager Fusion Middleware Control and used by the SOA Infrastructure.
Endpoint services that are shut down or retired (but not undeployed) are still
reachable. Therefore, the cache is not refreshed.
If you move the business service WSDL from one host to another, ensure that you
change the location in the Registry Control. No change is required in Oracle
JDeveloper or Oracle Enterprise Manager Fusion Middleware Control.
You can optionally increase the amount of time that the WSDL URL is available in
cache for inquiry by the service key. For more information, see "Configuring
Service and Reference Binding Component Properties" of Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management
Suite.
Note: In 11g, caching occurs automatically. If you are using Oracle
SOA Suite 10.1.3, caching is supported by setting the
CacheRegistryWSDL property to true in bpel.xml. Setting this
property to false disables caching.
3.
4.
5.
Click Find.
6.
7.
8.
9.
A-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
11. In the list of bindings, select the notepad icon next to the description column.
In the tModel name field, enter the name and click Find tModel.
3.
In the name column, click the name with the description wsdl:type representing
portType.
4.
5.
6.
7.
8.
9.
Click Update and save the changes. Figure A55 provides details.
A-51
10. To verify, navigate to the service and ensure that the WSDL URL is pointing to a
new location.
3.
b.
Enter values in the Business key and WSDL location (URI) fields.
c.
d.
Click Publish.
e.
In the navigation tree in the left pane, select the endpoint, bindings, and port
type, and ensure that the "new" mode option is selected. Figure A56 provides
details.
f.
Click Publish.
You cannot publish the same service with the same target namespace from
different SOA partitions or from different hosts.
There is no option for entering your own service key.
Instead, use the Registry Console to publish the same WSDL service deployed to
different partitions to OSR.
A-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
3.
4.
Harvest Oracle SOA Suite project artifacts, including BPEL, WSDL, XSD, and
XSLT files and file directories. After harvesting, the Oracle Enterprise Repository
automatically creates assets, populates asset metadata, and generates relationship
links based on the information in the artifact files.
Browse for assets and artifacts available in the Oracle Enterprise Repository.
View asset details such as description, usage history, expected savings, and
relationships.
Download an asset's artifacts (that is, payload) into your project. Typically, an asset
payload is the functionality required for using a service (such as a WSDL file) or
incorporating it into your code base (such as a binary or a BPEL file).
Consume a WSDL file or a service from the Oracle Enterprise Repository.
For more information about these tasks and how to configure and use Oracle
Enterprise Repository with an IDE, see the Oracle Fusion Middleware Integration Guide
for Oracle Enterprise Repository.
For more information about harvesting from Oracle JDeveloper, see the Oracle Fusion
Middleware Configuration Guide for Oracle Enterprise Repository.
A-53
2.
3.
Click OK.
4.
A-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B
XPath Extension Functions
This appendix describes the XPath extension functions for Oracle SOA Suite, Oracle
BPEL Process Manager, Oracle Mediator, and human workflow. It also describes
advanced XPath functions, how to build XPath expressions in the Expression Builder
in Oracle JDeveloper, and how to create user-defined XPath extension functions.
Oracle provides XPath functions that use the capabilities built into Oracle SOA Suite
and XPath standards for adding new functions.
This appendix includes the following sections:
For additional information about XPath functions, visit the following URL:
http://www.w3.org
Database functions
Date functions
Mathematical functions
String functions
B.1.1.1 lookup-table
This function returns a string based on the SQL query generated from the parameters.
The string is obtained by executing:
B-1
You execute it against the data source that can be either a JDBC connect string
(jdbc:oracle:thin:username/password@host:port:sid) or a data source
JNDI identifier. Only the Oracle thin driver is supported if the JDBC connect string is
used.
Example:
oraext:lookup-table('employee','id','1234','last_
name','jdbc:oracle:thin:xyz/xyz@localhost:1521:ORCL')
Signature:
oraext:lookup-table(table, inputColumn, key, outputColumn, data
source)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.1.2 query-database
This function returns a node set by executing the SQL query against the specified
database.
Signature:
oraext:query-database(sqlquery as string, rowset as boolean, row
as boolean, data source as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B.1.1.3 sequence-next-val
Returns the next value of an Oracle sequence.
The next value is obtained by executing the following:
SELECT sequence.nextval FROM dual
You execute it against a data source that can be either a JDBC connect string
(jdbc:oracle:thin:username/password@host:port:sid) or a data source
JNDI identifier. Only the Oracle thin driver is supported if a JDBC connect string is
used.
Example:
oraext:sequence-next-val('employee_id_
sequence','jdbc:oracle:thin:xyz/xyz@localhost:1521:ORCL')
Signature:
oraext:sequence-next-val(sequence as string, data source as
string)
Arguments:
data source: Either a JDBC connect string or a data source JNDI identifier.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.2.1 add-dayTimeDuration-to-dateTime
This function returns a new date time value adding dateTime to the given duration.
If the duration value is negative, then the resulting value precedes dateTime.
Signature:
xpath20:add-dayTimeDuration-from-dateTime(dateTime as string,
duration as string)
Arguments:
dateTime as string: The dateTime to which the function adds the duration,
in string format.
duration as string: The duration to add to the dateTime, or subtract if the
duration is negative, in string format.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B-3
B.1.2.2 current-date
This function returns the current date in the ISO format of YYYY-MM-DD.
Signature:
xpath20:current-date(object)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.3 current-dateTime
This function returns the current datetime value in the ISO format of
CCYY-MM-DDThh:mm:ss.sTZD (where s denotes the time in milliseconds).
For example, if the time is 6 hours, 17 minutes, 15 seconds, 125 milliseconds in the
evening (PM) of May 12, 2004 in time zone Z, current-dateTime returns a value of:
2004-05-12T18:17:15.125Z
2.
Signature:
B-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xpath20:current-dateTime(object)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.4 current-time
This function returns the current time in ISO format. The format is hh:mm:ssTZD.
Signature:
xpath20:current-time(object)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.5 day-from-dateTime
This function returns the day from dateTime. The default day is 1.
Signature:
xpath20:day-from-dateTime(object)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.6 format-dateTime
This function returns the formatted string of dateTime using the format provided.
For examples of date and time formatting strings, see the W3C XSL Transformations
documentation; for example, [Y0001]-[M01]-[D01].
Signature:
xpath20:format-dateTime(dateTime as string, format as string)
Arguments:
B-5
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.7 hours-from-dateTime
This function returns the hour from dateTime. The default hour is 0.
Signature:
xpath20:hours-from-dateTime(dateTime as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.8 implicit-timezone
This function returns the current time zone in the ISO format of +/- hh:mm,
indicating a deviation from Coordinated Universal Timezone (UTC).
Signature:
xpath20:implicit-timezone
Arguments:
This function does not take any arguments.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.9 minutes-from-dateTime
This function returns the minutes from dateTime. The default minute is 0.
Signature:
xpath20:minutes-from-dateTime(dateTime as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B.1.2.10 month-from-dateTime
This function returns the month from dateTime. The default month is 1 (January).
Signature:
xpath20:month-from-dateTime(dateTime as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.11 seconds-from-dateTime
This function returns the seconds from dateTime. The default second is 0.
Signature:
xpath20:seconds-from-dateTime(dateTime as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.12 subtract-dayTimeDuration-from-dateTime
This function returns a new dateTime value after subtracting the duration from
dateTime.
If the duration value is negative, then the resulting dateTime value follows
input-dateTime value.
Signature:
xpath20:subtract-dayTimeDuration-from-dateTime(dateTime as
string, duration as string)
Arguments:
dateTime as string: The dateTime from which the function subtracts the
duration, in string format.
duration as string: The duration to subtract from the dateTime, or to add if
the duration is negative, in string format.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xp20
B-7
B.1.2.13 timezone-from-dateTime
This function returns the time zone from dateTime. The default time zone is
GMT+00:00.
Signature:
xpath20:timezone-from-dateTime(dateTime as string)
Arguments:
dateTime as string: The dateTime for which this function returns a time
zone.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.2.14 year-from-dateTime
This function returns the year from dateTime.
Signature:
xpath20:year-from-dateTime(dateTime as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.3.1 abs
This function returns the absolute value of inputNumber.
If the inputNumber is not negative, the inputNumber is returned. If the
inputNumber is negative, the negation of inputNumber is returned.
Example:
abs(-1) returns 1.
Signature:
xpath20:abs(inputNumber as number)
Arguments:
Property IDs:
B-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.4.1 compare
This function returns the lexicographical difference between inputString and
compareString by comparing the unicode value of each character of both the
strings.
This function returns -1 if inputString lexicographically precedes the
compareString.
This function returns 0 if both inputString and compareString are equal.
This function returns 1 if inputString lexicographically follows the
compareString.
Example:
xpath20:compare('Audi', 'BMW') returns -1
Signature:
xpath20:compare(inputString as string, compareString as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.4.2 compare-ignore-case
This function returns the lexicographical difference between inputString and
compareString while ignoring case and comparing the unicode value of each
character of both the strings. Table B1 provides details.
Table B1
Values Returned
If...
-1
Example:
oraext:compare-ignore-case('Audi','bmw') returns -1
B-9
Signature:
xp:compare-ignore-case(inputString as string, compareString as
string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: oraext
B.1.4.3 create-delimited-string
This function returns a delimited string created from nodeSet delimited by a
delimiter.
Signature:
oraext:create-delimited-string(nodeSet as node-set, delimiter as
string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.4 ends-with
This function returns true if inputString ends with searchString.
Example:
xpath20:ends-with('XSL Map','Map') returns true
Signature:
xpath20:ends-with(inputString as string, searchString as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B.1.4.5 format-string
This function returns the message formatted with the arguments passed. At least one
argument is required and supports up to a maximum of 10 arguments.
Example:
oraext:format-string('{0} + {1} = {2}','2','2','4') returns '2 + 2
= 4'
Signature:
oraext:format-string(string,string,string...)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.6 get-content-as-string
This function returns the XML representation of the input element.
Signature:
oraext:get-content-as-string(element as node-set)
Arguments:
element as node-set: The input element that the function returns as an XML
representation.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.7 get-content-from-file-function
This function parses the file in the specified native format. Use this function when
designing assign activities in BPEL processes.
Signature:
oraext:get-content-from-file-function(fileName, nxsdTemplate?,
nxsdRoot?)
Example:
oraext:get-content-from-file-function("file:/c:/Ftab.txt",
"file:/c:/Ftab_1.xsd","root")
Arguments:
B-11
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.8 get-localized-string
This function returns the locale-specific string for the key. This function uses language,
country, variant, and resource bundle to identify the correct resource bundle. All
parameters must be in string format. Use the string() function to convert any
parameter values to strings before sending them to get-localized-string.
The resource bundle is obtained by resolving resourceLocation against the
resourceBaseURL. The URL is assumed to be a directory only if it ends with /.
Usage: oraext:get-localized-string(resourceBaseURL as string,
resourceLocation as string, resource bundle as string, language
as string, country as string, variant as string, key as string)
Example:
oraext:get-localized-string('file:/c:/','','MyResourceBundle','e
n','US','','MSG_KEY') returns a locale-specific string from a resource bundle
'MyResourceBundle' in the C:\ directory
Signature:
oraext:get-localized-string(resourceURL,resourceLocation,resourc
eBundleName,language,country,variant,messageKey)
Arguments:
resourceBundleName: The name of the ZIP file containing the resource bundle.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.9 index-within-string
This function returns the zero-based index of the first occurrence of searchString
within the inputString.
This function returns -1 if searchString is not found.
Example:
B-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.10 last-index-within-string
This function returns the zero-based index of the last occurrence of searchString
within inputString.
This function returns -1 if searchString is not found.
Example:
oraext:last-index-within-string('ABCABC', 'B') returns 4
Signature:
oraext:last-index-within-string(inputString as string,
searchString as string)
Arguments:
searchString: The string for which the function searches in the inputString.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.11 left-trim
This function returns the value of inputString after removing all the leading white
spaces.
Example:
oraext:left-trim(' account ') returns 'account '
Signature:
oraext:left-trim(inputString)
Arguments:
Property IDs:
B-13
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.12 lower-case
This function returns the value of inputString after translating every character to its
lower-case correspondent.
Example:
xpath20:lower-case('ABc!D') returns 'abc!d'
Signature:
xpath20:lower-case(inputString)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.4.13 matches
This function returns true if intputString matches the regular expression pattern
regexPattern.
Example:
xpath20:matches('abracadabra', '^a.*a$') returns true
Signature:
xpath20:matches(intputString, regexPattern)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.1.4.14 right-trim
This function returns the value inputString after removing all the trailing white
spaces.
Example:
oraext:right-trim(' account ') returns ' account'
Signature:
B-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
oraext:right-trim(inputString as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.1.4.15 upper-case
This function returns the value of inputString after translating every character to its
uppercase correspondent.
Example:
xpath20:upper-case('abCd0') returns 'ABCD0'
Signature:
xpath20:upper-case(inputString as string)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.Xpath20
namespace-prefix: xpath20
B.2.1 addQuotes
This function returns the content of a string with single quotes added.
Signature:
ora:addQuotes(string)
XPath Extension Functions
B-15
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.2 authenticate
This function authenticates an LDAP user and returns true or false.
The authenticate, listUsers, lookupUser, and search XPath functions
provide the lookup and search functionality to obtain information from the LDAP
server (typically, the LDAP user details).
These XPath functions use a configuration file to obtain server access information for
the JNDI (for example, context factory, LDAP server provider URL, authenticate type,
and so on). The configuration file is named directories.xml and must be placed in
the same directory in which the .bpel file for the BPEL project is located. To call these
XPath functions, you must provide this file.
Example B1 shows the format of the directories.xml file:
Example B1 directories.xml File Format
<?xml version="1.0" ?>
<directories>
<directory name='people'>
<property name="java.naming.provider.url">ldap://servername:port</property>
<property
name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.security.principal">[username]</property>
<property name="java.naming.security.authentication">simple</property>
<property name="java.naming.security.credentials">[passord]</property>
<property name="entryDN">[entry dn]</property>
</directory>
</directories>
Signature:
B-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ldap:authenticate('directoryName','userId','password')
Parameters:
Return:
true or false
Example:
ldap:authenticate('people','weblogic','weblogic')
For this XPath function, only two properties must be specified in the
directories.xml file:
java.naming.provider.url
java.naming.factory.initial
B.2.3 appendToList
Note: The appendToList function is deprecated. Oracle
recommends that you use the bpelx:copyList extension of an
assign activity to append data to a node list.
This function appends to a node list. The node list with which to append should not be
null or empty.
Signature:
ora:appendToList('variableName', 'partName'?, 'locationPath'?,
Object)
Arguments:
Property IDs:
deprecated
Use the bpelx:copyList or bpelx:append extension activity to append to a
list.
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-17
B.2.4 copyList
While the copyList function is still available for use, Oracle
recommends that you use the bpelx:copyList extension to copy a
node list or a node. For more information, see Section 6.15.6, "How to
Use bpelx:copyList."
Note:
This function copies a node list or a node. The node list to be copied to should not be
null or empty.
Signature:
ora:copyList('variableName', 'partName'?, 'locationPath'?,
Object)
Arguments:
Property IDs:
deprecated
Use the bpelx:copyList extension activity to append to a list.
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.5 countNodes
While the countNodes function is still available for use,
Oracle recommends that you use version 1.0 of the XPath count()
function to return the size of the elements as an integer.
Note:
B-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.6 doc
This function returns the content of an XML file.
Signature:
ora:doc('fileName','xpath'?)
Arguments:
xpath: A part of an XML file (for example, the node set, node list, or leaf node).
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.7 doStreamingTranslate
This function translates using the streaming XPath APIs. It uses a unique concept
called batching so that the transformation engine does not materialize the result of a
transformation into memory. Therefore, it can handle arbitrarily large payloads of the
order of gigabytes. However, it can only handle forward-only XSL constructs such as
for-each. The targetType can be SDOM or ATTACHMENT.
Signature:
ora:doStreamingTranslate('input SDOM or attachment element',
'streaming xpath context', 'SDOM or ATTACHMENT', 'attachment
element?')
Arguments:
SDOM or ATTACHMENT
attachment element
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.8 doTranslateFromNative
This function translates the input data to XML, where the input can be a string,
attachment, or element that contains Base64-encoded data. The targetType can be
DOM, ATTACHMENT or SDOM.
Signature:
B-19
ora:doTranslateFromNative('input','nxsdTemplate','nxsdRoot','tar
getType','attachment element?')
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.9 doTranslateToNative
This function translates the input DOM to a string or attachment. The targetType
can be a STRING or ATTACHMENT.
Signature:
ora:doTranslateToNative('input','nxsdTemplate','nxsdRoot','targe
tType','attachment element?')
Arguments:
input: The input data of the XPath function. The data can either be DOM or
SDOM data that must be translated to a native format such as comma-separated
values (CSV).
The input node is usually the root element of the incoming DOM. Example B3
provides details.
However, the input node can be a subelement and not the root element of the
incoming DOM. Example B4 provides details.
Example B4 doTranslateToNative Function
med:doTranslateToNative($in.request/inp1:requestToNative/ns1:Root-Element,
'xsd/address_csv.xsd', 'Root-Element','ATTACHMENT',
$in.request/inp1:requestToNative/inp1:attachment)
In these situations, you must set the following property in the schema node of the
NXSD for this function to execute properly.
nxsd:useArrayIdentifiers="true"
This setting can adversely impact the performance of this function for very large
inputs (in which case, use the dostreamingxlate function).
B-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
nxsdTemplate: The NXSD schema to use to translate the input data to XML
format.
nxsdRoot: The root element in the NXSD schema.
targetType: Decides how the XPath function translates the native data into
XML.
attachment element: This is the attachment for the returned XML. This
parameter is optional.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.10 doXSLTransform
This function implements the WS-BPEL 2.0's doXSLTransform function that
supports multiple parameters of XSLT. When using this function, the XSL template
match must not be set to root (which is /). It must be the root element.
Signature:
ora:doXSLTransform('url_to_
xslt',input,['paramQname',paramValue]*)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.11 doXSLTransformForDoc
This function is a complementary XPath function to doXSLTransform(). It aims to
perform the transformation when the XSLT template matches the document.
Example B5 shows the doXSLTransformForDoc function.
Example B5 doXSLTransformForDoc Functions
<function name="ora:doXSLTransformForDoc">
<className>com.collaxa.cube.xml.xpath.functions.xml.DoXSLTransformForDocument
</className>
<return type="node-set"/>
<params>
<param name="template" type="string"/>
<param name="input" type="string"/>
<param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
</params>
<desc resourceKey="PI_FUNCTION_DESC_DOXSLTRANSFORM_FOR_DOC"></desc>
<detail resourceKey="PI_FUNCTION_DESC_LONG_DOXSLTRANSFORM_FOR_DOC">
This function is a complement xpath function to doXSLTransform(). It aims
B-21
Signature:
ora:doXSLTransformForDoc('url_to_
xslt',input,['paramQname',paramValue]*)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
You can use the ora:doXSLTransformForDoc function to write the results of large
XSLT/XQuery operations to a temporary file in a directory system. The document is
then loaded from the temporary file when needed. This eliminates the need for
caching an entire document as binary XML in memory.
For more information, see Section 45.1.3.9, "Using XPath Functions to Write Large
XSLT/XQuery Output to a File System."
B.2.12 formatDate
This function converts standard XSD date formats to characters suitable for output.
Signature:
ora:formatDate('dateTime','format')
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.13 generateGUID
Generates a unique GUID.
Signature:
B-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ora:generateGUID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.14 getApplicationName
This function returns the application name.
Signature:
ora:getApplicationName()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.15 getAttachmentContent
This function gets the attachment content from an href function.
Signature:
ora:getAttachmentContent(varName[, partName[, query]])
Arguments:
query: (Optional) Specifies an absolute location path (with / meaning the root of
the document fragment representing the entire part) to identify the root of a
subtree within the document fragment representing the part.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
For more information, see Reading and Encoding SOAP Attachment Content.
B.2.16 getComponentName
This function returns the component name.
Signature:
ora:getComponentName()
Arguments:
There are no arguments for this function.
Property IDs:
XPath Extension Functions
B-23
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.17 getComponentInstanceID
This function returns the component instance ID.
Signature:
ora:getComponentInstanceID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.18 getCompositeName
This function returns the composite name.
Signature:
ora:getCompositeName()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.19 getCompositeInstanceID
This function returns the BPEL process composite instance ID.
Signature:
ora:getCompositeInstanceID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.20 getCompositeURL
This function returns the composite URL.
Signature:
ora:getCompositeURL()
Arguments:
There are no arguments for this function.
B-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.21 getContentAsString
This function returns the content of an element as an XML string.
Signature:
ora:getContentAsString(element elementAsNodeList)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.22 getConversationId
This function returns the conversation ID.
Signature:
ora:getConversationId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.23 getCreator
This function returns the instance creator.
Signature:
ora:getCreator()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.24 getCurrentDate
This function returns the current date as a string.
Signature:
ora:getCurrentDate('format'?)
XPath Extension Functions
B-25
Argument:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
For more information, see Section 6.13.1, "How to Assign a Date or Time."
B.2.25 getCurrentDateTime
This function returns the current date time as a string.
Signature:
ora:getCurrentDateTime('format'?)
Argument:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.26 getCurrentTime
This function returns the current time as a string.
Signature:
ora:getCurrentTime('format'?)
Argument:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.27 getECID
This function returns the execution context ID (ECID).
Signature:
ora:getECID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B.2.28 getElement
This function returns an element using an index from the array of elements.
Signature:
ora:getElement('variableName', 'partName', 'locationPath',
index)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.29 getFaultAsString
This function returns the fault as a string value.
Signature:
ora:getFaultAsString()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
For more information, see Section 12.6, "Getting Fault Details with the
getFaultAsString XPath Extension Function."
B.2.30 getFaultName
This function returns the fault name.
Signature:
ora:getFaultName()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-27
B.2.31 getGroupIdsFromGroupAlias
This function returns a list of user IDs for a group alias specified in the
TaskServiceAliases section of the BPEL suitcase descriptor.
Signature:
ora:getGroupIdsFromGroupAlias(String aliasName)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.32 getInstanceId
This function returns the instance ID.
Signature:
ora:getInstanceId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.33 getNodeValue
This function returns the value of a DOM node as a string.
Signature:
ora:getNodeValue(node)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.34 getNodes
This function gets a node list. This is implemented as an alternate to
bpws:getVariableData, which does not return a node list.
Signature:
ora:getNodes('variableName', 'partName'?, 'locationPath'?)
Arguments:
B-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.35 getOwnerDocument
This function returns the document object associated with the node.
Signature:
ora:getOwnerDocument(node)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.36 getParentComponentInstanceID
This function returns the BPEL process instance parent component instance ID.
Signature:
ora:getParentComponentInstanceID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.37 getPreference
This function returns the value of a property specified in the preferences section of the
BPEL suitcase descriptor.
Signature:
ora:getPreference(preferenceName)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-29
B.2.38 getProcessId
This function returns the ID of the current BPEL process.
Signature:
ora:getProcessId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.39 getProcessOwnerId
This function returns the ID of the user who owns the process, if specified in the
TaskServiceAliases section of the BPEL suitcase descriptor.
Signature:
ora:getProcessOwnerId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.40 getProcessURL
This function returns the root URL of the current BPEL process.
Signature:
ora:getProcessURL()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.41 getProcessVersion
This function returns the current process version.
Signature:
ora:getProcessVersion()
Arguments:
There are no arguments for this function.
Property IDs:
B-30 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.42 getUserAliasId
This function returns the user ID for an alias specified in the TaskServiceAliases
section of the BPEL suitcase descriptor.
Signature:
ora:getUserAliasId (String aliasName)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.43 getUserIdsFromGroupAlias
This function returns a list of user IDs for a group alias specified in the
TaskServiceAliases section of the BPEL suitcase descriptor.
Signature:
ora:getUserIdsFromGroupAlias( String aliasName )
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.44 setCompositeInstanceTitle
This function sets a title to the composite instance that can later be used as one of the
criteria in searching the instances. This function returns the same string that is passed
as the argument.
Signature:
med:setCompositeInstanceTitle(title)
Arguments:
title: Specifies the composite instance title. This can be specified as an XPath
expression on the message payload.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.45 instanceOf
This function extracts arbitrary values from BPEL variables.
B-31
Signature:
ora:instanceOf(an_xpath_expression, 'typeQName')
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.46 integer
This function returns the content of the node as an integer.
Signature:
ora:integer(node)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.47 listUsers
This function returns a list of LDAP users.
Signature:
ldap:listUsers('directoryName',filter')
Arguments:
Returns:
An XML element that contains a list of users.
For this XPath function, all properties must be specified in the directories.xml
file.
Example:
ldap:listUsers('people','ou=people');
B-32 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<userpassword>
Unknown macro: {ssha}
bHDVJRfWVt/Uwlzb4TKU+QTOLB4FLySO</userpassword>
<objectclass>inetOrgPerson</objectclass>
<objectclass>organizationalPerson</objectclass>
<objectclass>person</objectclass>
<objectclass>top</objectclass>
<objectclass>wlsUser</objectclass>
<description>This user is the default administrator.</description>
<wlsMemberOf>cn=Administrators,ou=groups,ou=myrealm,dc=soainfra</wlsMember
Of>
<orclguid>8AC1B6206FDD11DEBF9A7F3D47003274</orclguid>
<sn>weblogic</sn>
<cn>weblogic</cn>
</user>
</users>
B.2.48 lookupUser
This function returns LDAP user information.
:Signature:
ldap:lookupUser('directoryName','userId')
Arguments:
Returns:
An XML element that contains the user information.
For this XPath function, all properties must be specified in the directories.xml
file.
Example:
ldap:lookupUser('people','ou=people');
Example B7 provides an example of the output:
Example B7 lookupUser Output
<user dn="" xmlns="http://schemas.oracle.com/bpel/ldap">
<ou>people</ou>
<objectclass>organizationalUnit</objectclass>
<objectclass>top</objectclass>
<orclguid>8ABB9BA06FDD11DEBF9A7F3D47003274</orclguid>
</user>
B.2.49 parseEscapedXML
This function parses a string to DOM.
Signature:
oraext:parseEscapedXML(contentString)
B-33
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: oraext
For more information about this function, see Section 6.21.1, "How To Convert from a
String to an XML Element."
B.2.50 parseXML
This function parses a string to a DOM element.
Signature:
oraext:parseXML(contentString)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.2.51 processXQuery
This function returns the result of an XQuery transformation.
Signature:
ora:processXQuery('template','context'?)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.52 processXSLT
This function returns the result of an XSLT transformation using the Oracle XDK XSLT
processor.
Example B8 shows the 11g version of processXSLT.
Example B8 11g Version of processXSLT
<function name="ora:processXSLT">
<className>com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXDKXSLTFunction
</className>
<return type="node-set"/>
<params>
B-34 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Example B9 shows the 10g version of processXSLT, which is provided for backward
compatibility.
Example B9 10g Version of processXSLT
<function name="xdk:processXSLT">
<className>com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXDKXSLTFunction
</className>
<return type="node-set"/>
<params>
<param name="template" type="string"/>
<param name="input" type="string"/>
<param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
</params>
<desc resourceKey="PI_FUNCTION_DESC_PROCESSXSLT"></desc>
<detail resourceKey="PI_FUNCTION_DESC_LONG_PROCESSXSLT">
This is same as 11g, for backward compatiablity this function uses the
old 10.1.2 namespace. This function returns the result of XSLT transformation
by using Oracle XDK XSLT processor.
</detail>
<group>BPEL XPath Extension Functions</group>
</function>
Signature:
Arguments:
template: The XSLT template. Both HTTP and file URLs are supported.
properties: The properties that translate to XSL parameters that can be accessed
within the XSL map using the construct <xsl:param name="paramName"/>.
The properties are defined as follows:
1.
B-35
<xsd:element name="parameters">
<xsd:complexType>
<xsd:sequence>
<!-- Each Parameter is represented by an "item" node that contains
one unique name and a string value
-->
<xsd:element name="item" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="value" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
2.
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:ehdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.esb.server.
headers.ESBHeaderFunctions"
xmlns:ns0="http://www.w3.org/2001/XMLSchema"
xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services
.functions.ExtFunc"
xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
B-36 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
xmlns:ns1="http://xmlns.oracle.com/TestXSLParams"
exclude-result-prefixes="xsl ns0 ns1 ns2 xp20 bpws ora ehdr
orcl ids hwf">
<xsl:template match="/">
<ns2:parameters>
<ns2:item>
<ns2:name>
<xsl:value-of select="'userName'"/>
</ns2:name>
<ns2:value>
<xsl:value-of select="'jsmith'"/>
</ns2:value>
</ns2:item>
<ns2:item>
<ns2:name>
<xsl:value-of select="'location'"/>
</ns2:name>
<ns2:value>
<xsl:value-of select="'CA'"/>
</ns2:value>
</ns2:item>
</ns2:parameters>
</xsl:template>
</xsl:stylesheet>
3.
Within assign activity executeXSLT, you invoke the XSLT with the
parameters as the properties (third) argument of the function
processXSLT.
For example:
<process name="TestXSLParams"
. . .
. . .
<sequence name="main">
<receive name="receiveInput" partnerLink="client"
portType="client:TestXSLParams" operation="initiate"
variable="inputVariable" createInstance="yes"/>
<assign name="initializeXSLParameters">
<bpelx:annotation>
<bpelx:pattern>transformation</bpelx:pattern>
</bpelx:annotation>
<copy>
<from expression="ora:processXSLT ('SetParams.xsl',
bpws:getVariableData('inputVariable','payload'))"/>
<to variable="propertiesXMLVar"/>
</copy>
</assign>
<assign name="executeXSLT">
<bpelx:annotation>
<bpelx:pattern>transformation</bpelx:pattern>
</bpelx:annotation>
<copy>
B-37
<from expression="ora:processXSLT('TestXSLParams.xsl',
bpws:getVariableData('inputVariable','payload'),
bpws:getVariableData('propertiesXMLVar'))"/>
<to variable="outputVariable" part="payload"/>
</copy>
</assign>
<invoke name="callbackClient" partnerLink="client"
portType="client:TestXSLParamsCallback"
operation="onResult"
inputVariable="outputVariable"/>
</sequence>
</process>
4.
In a BPEL process, you use the properties to process the XSLT function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
You can use the ora:processXSLT function to write the results of large
XSLT/XQuery operations to a temporary file in a directory system. The document is
then loaded from the temporary file when needed. This eliminates the need for
caching an entire document as binary XML in memory.
For more information, see Section 45.1.3.9, "Using XPath Functions to Write Large
XSLT/XQuery Output to a File System."
B.2.53 readBinaryFromFile
This function reads data from a file.
Signature:
ora:readBinaryFromFile(fileName)
Arguments:
Property IDs:
namespace-uri:http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.54 readFile
This function returns the content of the file.
Signature:
ora:readFile('fileName','nxsdTemplate'?,'nxsdRoot'?)
Arguments:
fileName: The name of the file. This argument can also be an HTTP URL.
This function by default reads files relative to the suitcase JAR file for the process.
If the file to read is located in a different directory path, you must specify an extra
directory slash ( /) to indicate that this is an absolute path. For example:
B-38 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ora:readFile(file:///c:/temp/test.doc)
If you specify only two directory slashes (//), you receive an error similar to that
shown in Example B10:
Example B10 Error Message with readFile Function
XPath expression failed to execute.
Error while processing xpath expression,
the expression is "ora:readFile("file://c:/temp/test.doc")",
the reason is c. Verify the xpath query.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
Currently, the readFile function does not support the
functionality to access files on a web server that requires
authorization. If you tried to access such a file, then you get the
following error:
Note:
B.2.55 search
This function returns a list of LDAP entries.
Signature:
ldap:search('directoryName','filter','scope')
Parameters:
Returns:
An XML element that contains the list of entries.
For this XPath function, all properties must be specified in the directories.xml
file.
Example
ldap:search('people','cn=weblogic');
B-39
B.2.56 writeBinaryToFile
This function writes the binary bytes of a variable (or part of the variable) to a file of
the given file name.
Signature:
ora:writeBinaryToFile(varName[, partName[, query]])
Arguments:
Property IDs:
namespace-uri:http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-40 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Function
bpws:getLinkStatus
Yes
No
bpws:getVariableData
Yes
No
getVariableProperty
Yes
No
bpel:getVariableProperty
No
Yes
B.2.57.1 getLinkStatus
This function returns a boolean value indicating the status of the link. If the status of
the link is positive, the value is true. Otherwise, the value is false. This function can
only be used in a join condition.
The linkName argument refers to the name of an incoming link for the activity
associated with the join condition.
Signature:
bpws:getLinkStatus ('linkName')
Arguments:
Property IDs:
namespace-uri:
http://schemas.xmlsoap.org/ws/2003/03/business-process/
namespace-prefix: bpws
B.2.57.2 getVariableData
This function extracts arbitrary values from BPEL variables.
When only the first argument is present, the function extracts the value of the variable,
which in this case must be defined using an XML schema simple type or element.
Otherwise, the return value of this function is a node set containing the single node
representing either an entire part of a message type (if the second argument is present
and the third argument is absent) or the result of the selection based on the
locationPath (if both optional arguments are present).
Signature:
bpws:getVariableData ('variableName', 'partName'?,
'locationPath'?)
Arguments:
B-41
Property IDs:
namespace-uri:
http://schemas.xmlsoap.org/ws/2003/03/business-process/
namespace-prefix: bpws
B.2.57.2.1 selectionFailure Fault is Thrown if the Result Node Set is a Size Other Than One
During Execution According to the Business Process Execution Language for Web Services
Specification, if the locationPath argument selects a node set of a size other than one
during execution, the standard fault bpws:selectionFailure must be thrown by a
compliant implementation.
For example, the count() function shown in Example B12 does not work if there are
multiple entries of product elements under StoreRequest; this causes a
selectionFailure fault to be thrown.
Example B12 count() Function Error
count(bpws:getVariableData('inputVariable',
'payload','/ns2:StoreRequest/ns2:product'))
Property IDs:
namespace-uri:
http://schemas.xmlsoap.org/ws/2003/03/business-process/
namespace-prefix: bpws
B-42 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
node set of a size other than one during execution, the standard fault
bpws:selectionFailure is thrown.
Signature:
bpel:getVariableProperty ('variableName', 'propertyname')
Arguments:
Property IDs:
namespace-uri:
http://schemas.xmlsoap.org/ws/2003/03/business-process/
namespace-prefix: bpel
B.2.58.1 batchProcessActive
This function returns the number of active processes in the batch.
Signature:
ora:batchProcessActive(String rootId, String processId)
Arguments:
Property IDs:
namespace-uri:http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.58.2 batchProcessCompleted
This function returns the number of completed processes in the batch.
Signature:
ora:batchProcessCompleted(String rootId, String processId)
Arguments:
Property IDs:
namespace-uri:http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.58.3 format
This function formats a message using Java's message format.
XPath Extension Functions
B-43
Signature:
ora:format(formatStrings, args+)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.58.4 genEmptyElem
This function generates a list of empty elements for the given QName.
Signature:
ora:genEmptyElem('ElemQName',size?, 'TypeQName'?, xsiNil?)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
For more information about this function, see Section 6.20.4.4, "Generating
Functionality Equivalent to an Array of an Empty Element."
B.2.58.5 getChildElement
This function gets a child element for the given element.
Signature:
ora:getChildElement(element, index)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B-44 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B.2.58.6 getMessage
This function gets a message based on the arguments.
Signature:
ora:getMessage(locale, relativeLocation, resourceName,
resourceKey, resourceLocation?)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: ora
B.2.58.7 max-value-among-nodeset
This function returns the maximum value from a list of input numbers, the node set
inputNumber.
The node set inputNumber can be a collection of text nodes or elements containing
text nodes.
In the case of elements, the first text node's value is considered.
Signature:
oraext:max-value-among-nodeset(inputNumber as node-set)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.2.58.8 min-value-among-nodeset
This function returns the minimum value from a list of input numbers, the node set
inputNumbers.
The node set can be a collection of text nodes or elements containing text nodes.
In the case of elements, the first text node's value is considered.
Signature:
oraext:min-value-among-nodeset(inputNumbers as node-set)
Arguments:
B-45
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.2.58.9 square-root
This function returns the square root of inputNumber.
Example:
oraext:square-root(25) returns 5
Signature:
oraext:square-root(inputNumber as number)
Arguments:
inputNumber: The input number for which the function calculates the square
root.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.3.1 doStreamingTranslate
This function translates using the streaming XPath APIs. It uses a unique concept
called batching so that the transformation engine does not materialize the result of the
transformation into memory. Therefore, it can handle arbitrarily large payloads of the
order of gigabytes. However, it can only handle forward-only XSL constructs such as
for-each. The targetType can be SDOM or ATTACHMENT.
Signature:
med:doStreamingTranslate('input','streaming xpath
context','targetType','attachment element'?)
Arguments:
input: The input data of the XPath function. This can be an SDOM or attachment
element.
streaming xpath context
targetType: Determines how the XPath function translates the native data into
XML.
attachment element: The attachment for the returned XML. This parameter is
optional.
Property IDs:
B-46 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: med
Example:
med.doStreamingTranslate($in.request/inp1:request/inp1:sourceAtt
achmentElement,$in.request/inp1:request/inp1:streamingcontext,
'ATTACHMENT',
$in.request/inp1:request/inp1:targetAttachmentElement)
B.3.2 doTranslateFromNative
This function translates the input data to XML, where the input can be a string to
translate, a file or FTP adapter attachment, an attachment, or an element that contains
Base64-encoded data. The targetType can be DOM, ATTACHMENT or SDOM.
Signature:
med:doTranslateFromNative('input','nxsdTemplate','nxsdRoot','tar
getType','attachment element'?)
Arguments:
input: The input data of the XPath function. The data is in a native format, such
as comma-separated values (CSV).
nxsdTemplate: The NXSD schema to use to translate the input data to XML
format.
nxsdRoot: The root element in the NXSD schema.
targetType: Determines how the XPath function translates the native data into
XML.
attachment element: The attachment for the returned XML. This parameter is
optional.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: med
Example:
med:doTranslateFromNative(string($in.request/inp1:request/inp1:s
ource),'xsd/address_csv.xsd','Root-Element','DOM')
B.3.3 doTranslateToNative
This function translates the input DOM to a string or attachment. The targetType
can be a STRING or ATTACHMENT.
Signature:
med:doTranslateToNative('input','nxsdTemplate','nxsdRoot','targe
tType','attachment element'?)
Arguments:
input: The input data of the XPath function. The data can either be DOM or
SDOM data that must be translated to a native format such as comma-separated
values (CSV).
B-47
The input node is usually the root element of the incoming DOM, as shown in
Example B13.
Example B13 Input Node as Root Element in doTranslateToNative Function
med:doTranslateToNative($in.request/inp1:Root-Element, 'xsd/address_csv.xsd',
@ 'Root-Element','STRING')"
However, the input node can also be a subelement and not the root element of the
incoming DOM, as shown in Example B14.
Example B14 Input Node as Subelement in doTranslateToNative Function
med:doTranslateToNative($in.request/inp1:requestToNative/ns1:Root-Element,
'xsd/address_csv.xsd', 'Root-Element','ATTACHMENT',
$in.request/inp1:requestToNative/inp1:attachment)
In this case, you must set the useArrayIdenitifer property to true in the
schema node of the NXSD, as shown below.
nxsd:useArrayIdentifiers="true"
This setting can adversely impact the performance of this function for very large
inputs. You can use the dostreamingxlate function in this case.
nxsdTemplate: The NXSD schema to use to translate the input data to XML
format.
nxsdRoot: The root element in the NXSD schema.
targetType: Determines how the XPath function translates the native data into
XML.
attachment element: The attachment for the returned XML. This parameter is
optional.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: med
Example:
med:doTranslateToNative($in.request/inp1:Root-Element,'xsd/addre
ss_csv.xsd','Root-Element','STRING')
B.3.4 getAttachmentContent
This function gets the attachment content and encodes the data into Base64 format.
Signature:
med:getAttachmentContent(xpathExpr)
Arguments:
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: med
Example:
B-48 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
med:getAttachmentContent($in.bin/bin)
B.3.5 getComponentInstanceID
This function returns the component instance ID.
Signature:
mdhr:getComponentInstanceId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.6 getComponentName
This function returns the component name.
Signature:
mdhr:getComponentName()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.7 getCompositeInstanceID
This function returns the composite instance ID.
Signature:
mdhr:getComponentInstanceId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.8 getCompositeName
This function returns the composite name.
Signature:
mdhr:getCompositeName()
Arguments:
There are no arguments for this function.
Property IDs:
XPath Extension Functions
B-49
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.9 getHeader
This function returns the value of an XPath expression from the Oracle Mediator
message header.
The getHeader function works only when both parameters
are specified.
Note:
Signature:
mdhr:getHeader(xpath as string, namespaces as string)
Arguments:
In the XSLT Mapper in Oracle JDeveloper, drag the getHeader function into
the mapper.
2.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix:mdhr
B.3.10 getECID
This function returns the ECID.
Signature:
mdhr:getECID()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B-50 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Advanced Functions
B.3.11 getParentComponentInstanceID
This function returns the Oracle Mediator instance parent component instance ID.
Signature:
mdhr:getParentComponentInstanceId()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.12 readBinaryFromFile
This function creates an attachment by reading binary data from the given file name. It
returns the element that holds the created attachment.
Signature:
med:readBinaryFromFile(location)
Arguments:
location: The path and file name from which to read data.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.3.13 setCompositeInstanceTitle
This function sets a title to the composite instance that can later be used as one of the
criteria in searching the instances. This function returns the same string that is passed
as the argument.
Signature:
mdhr:setCompositeInstanceTitle(title)
Arguments:
title: Specifies the composite instance title. This can be specified as an XPath
expression on the message payload.
Property IDs:
namespace-uri: http://schemas.oracle.com/xpath/extension
namespace-prefix: mdhr
B.4.1 create-nodeset-from-delimited-string
This function takes a delimited string and returns a nodeSet.
Signature:
XPath Extension Functions
B-51
Advanced Functions
oraext:create-nodeset-from-delimited-string(qname,
delimited-string, delimiter)
Arguments:
qname: The qualified name in which each node in the node set must be created.
The QName can be represented in two forms:
task:assignee
{http://mytask/task}assignee
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.4.2 generate-guid
This function generates a unique GUID.
Signature:
oraext:generate-guid()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.4.3 lookupPopulatedColumns
This function looks up a cross-reference column for a single value or multiple values
corresponding to a value in a reference column.
Signature:
xref:lookupPopulatedColumns(tableName,columnName,value,needAnExc
eption)
Arguments:
B-52 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Advanced Functions
Property IDs:
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
B.4.4 lookupValue
This function returns a string by looking up the value for the target column in a
domain value map, where the source column contains the given source value.
Signature:
dvm:lookupValue(dvmLocation,sourceColumnName,sourceValue,targetC
olumnName,defaultValue)
Arguments:
sourceValue: The source value (an XPath expression bound to the source
document of the XSLT transformation).
defaultValue: If the value is not found, then the default value is returned.
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.Looku
pValue
namespace-prefix: dvm
B.4.5 lookupValue1M
This function returns an XML document fragment containing values for multiple
target columns of a domain value map, where the value for the source column equals
the source value.
Signature:
dvm:lookupValue1M(dvmLocation,sourceColumnName,sourceValue,targe
tColumnName1,targetColumnName2...)
Arguments:
SourceValue: The source value (an XPath expression bound to the source
document of the XSLT transformation).
TargetColumnName: The name of the target columns. You must specify at least
one column name. The question mark symbol (?) indicates that you can specify
multiple target column names.
XPath Extension Functions
B-53
Advanced Functions
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.Looku
pValue
namespace-prefix:dvm
B.4.6 lookupXRef
This function looks up a cross-reference column for a value that corresponds to a value
in a reference column.
Signature:
xref:lookupXRef(tableName,referenceColumnName,referenceValue,col
umnName,needAnException)
Arguments:
Property IDs:
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
For more information, see Section 49.6.1, "About the xref:lookupXRef Function."
B.4.7 lookupXRef1M
This function looks up a cross-reference column for multiple values corresponding to a
value in a reference column.
Signature:
xref:lookupXRef1M(tableName,referenceColumnName,referenceValue,c
olumnName,needAnException)
Arguments:
Property IDs:
B-54 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Advanced Functions
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
For more information, see Section 49.6.2, "About the xref:lookupXRef1M Function."
B.4.8 lookup-xml
This function returns the string value of an element defined by lookupXPath in an
XML file (docURL) given its parent XPath (parentXPath), the key XPath
(keyXPath), and the value of the key (key).
Example:
oraext:lookup-xml('file:/d:/country_data.xml',
'/Countries/Country', 'Abbreviation', 'FullName', 'UK') returns the
value of the element FullName child of /Countries/Country, where
Abbreviation = 'UK' is in the file D:\country_data.xml.
Signature:
oraext:lookup-xml(docURL, parentXPath, keyXPath, lookupXPath,
key)
Arguments:
Property IDs:
namespace-uri:
http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.servic
es.functions.ExtFunc
namespace-prefix: oraext
B.4.9 markForDelete
This function deletes a value in a cross-reference table. The row, containing the
column value passed to the function, is deleted from the XREF_DATA table and moved
to the XREF_DELETED_DATA table. This function returns true if the deletion is
successful. Otherwise, it returns false.
Signature:
xref:markForDelete(tableName,columnName,value)
Arguments:
xrefColumnName: The name of the column that contains the value to be deleted.
Property IDs:
B-55
Advanced Functions
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
For more information, see Section 49.7.1, "How to Delete a Cross Reference Table
Value."
B.4.10 populateXRefRow
This function populates the column name in the cross-reference table (XREF) in which
the reference column has the reference value.
Signature:
xref:populateXRefRow(tableName,referenceColumnName,referenceValu
e,columnName,value,mode)
Arguments:
Property IDs:
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
For more information, see Section 49.5.1, "About the xref:populateXRefRow Function."
B.4.11 populateXRefRow1M
This function populates the column with multiple values in the cross-reference table
(XREF) in which the reference column has the reference value.
Signature:
xref:populateXRefRow1M(tableName,referenceColumnName,referenceVa
lue,columnName,value,mode)
Arguments:
Property IDs:
B-56 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.t
ip.xref.xpath.XRefXPathFunctions
namespace-prefix: xref
B.5.1 clearTaskAssignees
This function clears the current task assignees.
Signature:
hwf:clearTaskAssignees(taskID)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.2 createWordMLDocument
This function creates a Microsoft Word ML document as a base 64-encoded string.
Signature:
hwf:createWordMLDocument(node, xsltURI)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.3 getNotificationProperty
This function retrieves a notification property. This function evaluates to
corresponding values for each notification. Only use this function in the notification
content XPath expression. If used elsewhere, it returns null.
Signature:
hwf:getNotificationProperty(propertyName)
Arguments:
B-57
taskId: The task ID of the task for which the notification is meant.
taskNumber: The task number of the task for which the notification is meant.
appLink: The HTML link to the Oracle BPM Worklist task details page.
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.4 getNumberOfTaskApprovals
This function computes the number of times the task was approved.
Signature:
hwf:getNumberOfTaskApprovals(taskId)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.5 getPreviousTaskApprover
This function retrieves the previous task approver.
Signature:
hwf:getPreviousTaskApprover(taskId)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.6 getTaskAttachmentByIndex
This function retrieves the task attachment at the specified index.
Signature:
hwf:getTaskAttachmentByIndex(taskId, attachmentIndex)
Arguments:
B-58 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.7 getTaskAttachmentByName
This function retrieves the task attachment by the attachment name.
Signature:
hwf:getTaskAttachmentByName(taskId, attachmentName)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.8 getTaskAttachmentContents
This function retrieves the task attachment contents by the attachment name.
Signature:
hwf:getTaskAttachmentContents(taskId, attachmentName)
Arguments:
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.9 getTaskAttachmentsCount
This function retrieves the number of task attachments.
Signature:
hwf:getTaskAttachmentsCount(taskId)
Arguments:
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B-59
B.5.10 getTaskResourceBundleString
This function returns the internationalized resource value from the resource bundle
associated with a task definition.
Signature:
hwf:getTaskResourceBundleString(taskId, key, locale?)
Arguments:
locale: (Optional) The locale. This value defaults to system locale. This returns a
resourceString XML element in the namespace
http://xmlns.oracle.com/bpel/services/taskService, which contains
the string from the resource bundle.
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.11 wfDynamicGroupAssign
This function gets the name of an identity service group, selected according to the
specified assignment pattern. The group is selected from either the subordinate groups
of the specified group (if a single group name is supplied), or from the list of groups (if
a list of user names is supplied). If the identity service is configured with multiple
realms, the realm name for the group and groups must also be supplied. Additional
assignment pattern-specific parameters can be supplied. These additional parameters
are optional, depending on the details of the specific assignment pattern used.
There are two signatures of this function.
Signature 1:
hwf:wfDynamicGroupAssign(patternName,groupName,realmName?,
patternParam1?,patternParam2?,...,patternParamN?)
Argument 1:
groupName: The name of the group from which to select a subordinate group.
realmName: The name of the identity service realm to which the group belongs.
Signature 2:
hwf:wfDynamicGroupAssign(patternName,groupList,realmName?,
patternParam1?,patternParam2?,...,patternParamN?)
Argument 2:
realmName: The name of the identity service realm to which the groups belong.
B-60 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B.5.12 wfDynamicUserAssign
This function returns the name of an identity service user, selected according to the
specified assignment pattern. The user is selected from either the subordinate users of
the specified group (if a single group name is supplied), or from the list of users (if a
list of user names is supplied). If the identity service is configured with multiple
realms, the realm name for the group and users must also be supplied. Additional
assignment pattern-specific parameters can be supplied. These additional parameters
are optional, depending on the details of the specific assignment pattern used.
There are two signatures for this function.
Signature 1:
hwf:wfDynamicUserAssign(patternName,groupName,realmName?,
patternParam1?,....,patternParam2?,...,patternParamN?)
Arguments 1:
groupName: The name of the group from which to select a subordinate user.
realmName: The name of the identity service realm to which the group belongs.
Signature 2:
hwf:wfDynamicUserAssign(patternName,userList,realmName?,patternP
aram1?,patternParam2?,...,patternParamN?)
Arguments 2:
realmName: The name of the identity service realm to which the users belong.
Property IDs:
namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath
namespace-prefix: hwf
B-61
B.5.13.1 getDefaultRealmName
This function returns the default realm name.
Signature:
ids:getDefaultRealmName()
Arguments:
There are no arguments for this function.
Property IDs:
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
B.5.13.2 getGroupProperty
This function returns the property value for the given group. If the group or attribute
does not exist, it returns null.
Signature:
ids:getGroupProperty(groupName, attributeName, realmName)
Arguments:
realmName: The realm name. This is optional. If not specified, the default realm is
assumed.
Property IDs:
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
B.5.13.3 getManager
This function gets the manager of a given user. If the user does not exist or there is no
manager for this user, it returns null.
Signature:
ids:getManager(userName, realmName)
Arguments:
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/services/IdentitySer
vice/xpath
B-62 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
namespace-prefix: ids
B.5.13.4 getReportees
This function gets the reportees of the user. If the user does not exist, it returns null.
This function returns a list of nodes. Each node in the list is called user.
Signature:
ids:getReportees(userName, upToLevel, realmName)
Arguments:
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/services/IdentitySer
vice/xpath
namespace-prefix: ids
B.5.13.5 getSupportedRealmNames
This function returns the supported realm names.
Signature:
ids:getSupportedRealms()
Property IDs:
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
B.5.13.6 getUserProperty
This function returns the property of the user. If the user does not exist, it returns
null. Use custom attributes if the desired attribute does not exist.
Signature:
ids:getUserProperty(userName, attributeName, realmName)
Arguments:
realmName: The realm name. This is optional. If not specified, the default realm
name is assumed.
Property IDs:
XPath Extension Functions
B-63
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
For more information, see Section 17.3.5, "How to Select Email Addresses and
Telephone Numbers Dynamically."
B.5.13.7 getUserRoles
This function gets the user roles. This function returns a list of objects, either
application roles or groups, depending on the roleType. If the user or role does not
exist, it returns null.
Signature:
ids:getUserRoles(userName, roleType, direct)
Arguments:
userName: String or element containing the user whose roles are to be retrieved.
roleType: The role type that takes one of three values: ApplicationRole,
EnterpriseRole, or AnyRole.
direct: A string or element indicating if direct or indirect roles must be fetched.
This is optional. If not specified, only direct roles are fetched. This is either
xsd:boolean or string true/false.
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/services/IdentitySer
vice
namespace-prefix: ids
B.5.13.8 getusersinapprole
This function returns the list of users who are granted this application role. If either
the application role name or the application name provided as input is null, then it
returns null.
Signature: ids:getUsersInAppRole(appRoleName, appName, direct,
realmName)
Arguments:
B.5.13.9 getUsersInGroup
This function gets the users in a group. If the group does not exist, it returns null.
This function returns a list of nodes. Each node in the list is called user.
Signature:
ids:getUsersInGroup(groupName, direct, realmName)
B-64 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Arguments:
Property IDs:
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
B.5.13.10 isUserInRole
This function verifies if a user has a given role.
Signature:
ids:isUserInRole(userID, roleName, realmName)
Arguments:
userID: A string or element containing the user whose participation in the role
must be verified.
roleName: The role name.
realmName: The realm name. This is optional. If not specified, the default realm
name is assumed.
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/services/IdentitySer
vice/xpath
namespace-prefix: ids
B.5.13.11 lookupGroup
This function gets the group. If the group does not exist, it returns null.
Signature:
ids:lookupGroup(groupName, realmName)
Arguments:
Property IDs:
namespace-uri:http://xmlns.oracle.com/bpel/services/IdentitySer
vice/xpath
namespace-prefix: ids
B.5.13.12 lookupUser
This function gets the user object. If the user does not exist, it returns null.
B-65
Signature:
ids:lookupUser(userName, realmName)
Arguments:
Property IDs:
namespace-uri:
http://xmlns.oracle.com/bpel/services/IdentityService/xpath
namespace-prefix: ids
3.
B-66 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
This inserts the function into the Expression field at the top.
4.
In the Expression field, place the cursor between the parentheses of the function,
as shown in Figure B2.
5.
In the Schema section, expand the schema path to make your selection, as shown
in Figure B3.
6.
Expression field of the Initialize tab of the Create Variable dialog in BPEL 2.0
Edit XPath Expression and Edit Function dialogs of the XSLT Mapper
B-67
Functions
This value is added to the Expression field. The list automatically displays again
with different options and prompts you to enter the next portion of the XPath
expression.
3.
This value is added to the Expression field. The list automatically displays again
and prompts you to enter the next portion of the XPath expression.
4.
Continue this process to build the remaining parts of the XPath expression.
5.
B-68 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note:
3.
4.
Drag and drop the xpath-expression function into the XSLT Mapper, as shown in
Figure B8.
Figure B8 xpath-expression
5.
6.
7.
Press Ctrl and then the space bar to display a list of values for building an
expression, as shown in Figure B9.
B-69
8.
Make a selection from the list (for this example, concat(String) as String) in either
of the following ways:
This selection is added to the XPath Expression field. The list automatically
displays again with different options and prompts you to enter the next portion of
the XPath expression.
9.
Continue this process to build the remaining parts of the XPath expression.
10. Click OK to close the Edit XPath Expression dialog when complete.
B-70 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Once you finish specifying one argument, and enter a comma to move to the next
argument, the tool tip updates itself to highlight the second argument name in bold,
and so on. While editing existing XPaths that contain functions, you can re-invoke
parameter tool tips by positioning the cursor within the function and then pressing a
combination of the Ctrl, Shift, and space bar keys.
Syntactically valid XPaths may be semantically invalid. This can cause unexpected
errors at runtime. For example, you can misspell the name of an element, variable,
function, or part. The XPath Building Assistant warns you about semantic errors by
underlining the erroneous area in blue. Drag the mouse pointer over this area. The
error message displays as a tool tip. The blue underlining error disappears after you
make corrections. Figure B13 provides details.
Figure B13 Semantically Incorrect XPaths
B.6.7 Creating Expressions with Free Form Text and XPath Expressions
You can mix free form text with XPath expressions in some dialogs.
1.
Place your cursor over the field to display a popup message that describes this
functionality. Figure B14 provides details.
2.
Enter free form text (in this example, Hello, your telephone number).
Figure B15 provides details.
B-71
Figure B15
3.
Enter <% when you are ready to invoke the XPath Building Assistant. Figure B16
provides details.
A red underline appears, which indicates that you are being prompted to add
information.
4.
Press Ctrl and then the space bar to invoke the XPath Building Assistant.
Figure B17 provides details.
5.
Scroll down the list and double-click the value you want.
6.
B.6.8 Using Double Slashes for Directory Paths in XPath Functions on Windows Can
Cause Errors
The use of slashes to represent directory paths in XPath extension functions on
Windows operating systems can be interpreted in two ways:
If you specify double slashes and receive an error message, try specifying single
slashes.
For example, the following use of double slashes does not work:
oraext:get-content-from-file-function("file://c:/Ftab.txt","file:
//c:/Ftab_1.xsd","root")
B-72 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Oracle Mediator
XSLT Mapper
Human workflow
XPath extension functions in Oracle SOA Suite adhere to the following standards:
A single schema defines the configuration syntax for both system functions and
user-defined functions.
XPath functions are categorized based on usage (Oracle BPEL Process Manager,
Oracle Mediator, human workflow, XSLT Mapper, and those commonly used by
all).
System functions are separated from user-defined functions.
A repository hosts both system function configuration files and user-defined
function configuration files.
A repository hosts user-defined function implementation JAR files and
automatically makes them available for the Java Virtual Machine (JVM) (class
loaders).
If possible, write functions that can be shared across all components. Functions
shared by all components can be created in a configuration file named
ext-soa-xpath-functions-config.xml. You must implement XSLT
Mapper functions differently than Oracle BPEL Process Manager, Oracle
Mediator, and human workflow functions.
For more information about these implementation differences, see Section B.7.1,
"How to Implement User-Defined XPath Extension Functions."
If you create a function for one component that cannot be used by others (for
example, a function for Oracle BPEL Process Manager that cannot be used by
Oracle Mediator or human workflow), then create that function in the
configuration file specific to that component. For this example, the Oracle BPEL
Process Manager function must be created in a configuration file named
ext-bpel-xpath-functions-config.xml.
Example B15 shows the function schema used by system and user-defined functions.
Example B15 Function Schema
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://xmlns.oracle.com/soa/config/xpath"
targetNamespace="http://xmlns.oracle.com/soa/config/xpath"
elementFormDefault="qualified">
<element name="soa-xpath-functions" type="tns:XpathFunctionsConfig"/>
<element name="function" type="tns:XpathFunction"/>
<complexType name="XpathFunctionsConfig">
<sequence>
<element ref="tns:function" minOccurs="1" maxOccurs="unbounded"/>
B-73
</sequence>
<attribute name="resourceBundle" type="string"/>
<attribute name="version" type="string"/>
</complexType>
<complexType name="XpathFunction">
<sequence>
<element name="className" type="string"/>
<element name="return">
<complexType>
<attribute name="type" type="tns:XpathType"
use="required"/>
</complexType>
</element>
<element name="params" type="tns:Params" minOccurs="0"
maxOccurs="1"/>
<element name="desc">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="resourceKey"
type="string"/>
</extension>
</simpleContent>
</complexType>
</element>
<element name="detail" minOccurs="0">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="resourceKey"
type="string"/>
</extension>
</simpleContent>
</complexType>
</element>
<element name="icon" minOccurs="0">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="resourceKey"
type="string"/>
</extension>
</simpleContent>
</complexType>
</element>
<element name="helpURL" minOccurs="0">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="resourceKey"
type="string"/>
</extension>
</simpleContent>
</complexType>
</element>
<element name="group" minOccurs="0">
<complexType>
<simpleContent>
<extension base="string">
B-74 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Each XSLT Mapper function requires a corresponding public static method from a
public static class. The function name and method name must match.
XSLT Mapper function namespaces must take the form
http://www.oracle.com/XSL/Transform/java/mypackage.MyFunction
Class, where mypackage.MyFunctionClass is the fully-qualified class name
of the public static class containing the public static methods for the functions.
For additional details about creating a user-defined XPath extension function for the
XSLT Mapper, see Section 40.3.4.4, "Importing User-Defined Functions."
B-75
where:
context: The context at the point in the expression when the function is
called.
args: The list of arguments provided during the call of the function.
B-76 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
B-77
Table B3
Element
Description
className
return
The return type of the function. This can be one of the following types supported by XPath and
XSLT: string, number, boolean, node set, and tree.
params
The parameters of the function. A function can have no parameters. A parameter has the
following attributes:
name: The name of the parameter.
type: The type of the parameter. This can be one of the following types supported by XPath
and XSLT: string, number, boolean, node set, and tree.
wizardEnabled: Indicates whether to enable a wizard to enter the parameter value. This
supports a user interface where the parameter value must be entered. If set to true, a
wizard launch button is rendered next to the parameter value field. The wizard launch
button, when pressed, launches a popup wizard to help the user enter the parameter value.
The wizard class must be specified later. The default value is false if this attribute is
absent, meaning there is no wizard support for the parameter by default.
desc
detail
An optional longer (detailed) description of the function. If the resourceKey is present, the
description is retrieved from the resource bundle specified earlier on the root element.
icon
An optional icon URL of the function. If the resourceKey is present, the icon URL is retrieved
from the resource bundle specified earlier on the root element. This is to support a user interface
in which the function must be displayed.
helpURL
An optional help HTML URL of the function. If the resourceKey is present, the help URL is
retrieved from the resource bundle specified earlier on the root element. This is to support a user
interface in which the function help link must be displayed.
group
An optional group name of the function. If the resourceKey is present, the group name is
retrieved from the resource bundle specified earlier on the root element. This is to support a user
interface where functions must be grouped. If no group name is specified, the function falls into
a built-in advanced functions group when being grouped in a user interface.
wizardClass
The fully qualified class name of the wizard class for all parameters that are wizard-enabled.
This is to support a user interface in which parameter values must be entered. This wizard class
is invoked by wizard launch buttons to help you enter parameter values. If there is no
wizard-enabled parameter, this element must be absent.
Note: This element is not supported for user-defined functions. Only system functions currently
support this feature.
2.
B-78 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Table B4
ext-bpel-xpath-functions-config.xml
Oracle Mediator
ext-mediator-xpath-functions-config.xml
XSLT Mapper
ext-mapper-xpath-functions-config.xml
Human workflow
ext-wf-xpath-functions-config.xml
All components
ext-soa-xpath-functions-config.xml
3.
Place the configuration file inside a JAR file along with the compiled classes.
Within the JAR file, the configuration file must be located in the META-INF
directory. The JAR file does not need to reside in a specific directory.
The customXpathFunction JAR must be added explicitly as
it is not part of the SOA composite.
Note:
4.
5.
6.
B-79
B-80 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
C
Deployment Descriptor Properties
Note:
For more information about deployment descriptor properties, see Chapter "Oracle
BPEL Process Manager Performance Tuning" of Oracle Fusion Middleware Performance
and Tuning Guide.
Configuration
C-1
Table C1
Property Name
Description
completionPersistPolicy
This property configures how the instance data is saved. It can only be set at the
BPEL service component level. The following values are available:
disableAsserts
globalTxMaxRetry
globalTxRetryInterval
inMemoryOptimization
Default value is false. This property can only be set to true if it does not have
dehydration points. Activities like wait, receive, onMessage, and onAlarm create
dehydration points in the process. If this property is set to true, in-memory
optimization is attempted on the instances of this process on to-spec queries.
keepGlobalVariables
Specify whether the server can keep global variable values in the instance store
when the instance completes:
oneWayDeliveryPolicy
false (default): Global variable values are deleted when the instance
completes.
true: Global variable values are not deleted.
This property sets the persistence policy of the process in the delivery layer. The
possible values are:
For information about setting this property during BPEL process creation, see
Section 4.1.1, "How to Add a BPEL Process Service Component."
For more information, see Section "Tuning Database Persistence for BPEL" of
Oracle Fusion Middleware Performance and Tuning Guide.
C-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
reenableAggregationOnCo
mplete
This property controls the number of instances to create and use to route
messages. The possible values are:
For more information, see Section 9.2, "Routing Messages to the Same Instance."
sensorActionLocation
The location of the sensor action XML file. The sensor action XML file configures
the action rule for the events.
sensorLocation
The location of the sensor XML file. The sensor XML file defines the list of
sensors into which events are logged.
transaction
This property configures the transaction behavior of the BPEL instance for
initiating calls.
Note: This property does not apply for midprocess receive activities. In those
cases, another thread in another transaction is used to process the message. This
is because a correlation is needed and it is always done asynchronously.
For information about setting this property during BPEL process creation, see
Section 4.1.1, "How to Add a BPEL Process Service Component."
C-3
Table C2
Property Name
Description
idempotent
true (default): If the server fails, it performs the activity again after
restarting. This is because the server does not dehydrate immediately after
the invoke and no record exists that the activity executed.
false: Activity is dehydrated immediately after execution and recorded in
the dehydration store. When idempotent is set to false, it provides better
failover protection, but may impact performance if the BPEL process
accesses the dehydration store frequently.
For information about using fault handling with the idempotent property
set to false, see Section 12.10.6, "What You May Need to Know About the
idempotent Property and Fault Handling."
For more information about the idempotent property, see Section 8.4,
"Managing Idempotence at the Partner Link Operation Level."
nonBlockingInvoke
Default value is false. When this is set to true, a separate thread is spawned
to perform the invocation so that the invoke activity does not block the instance.
For more information, see Section 10.1.1, "What You May Need to Know About
the Execution of Parallel Flow Branches in a Single Thread."
Enables message boundary validation. When set to true, the XML message is
validated against the XML schema during a receive activity and an invoke
activity for this partner link. If the XML message is invalid, then a
bpelx:invalidVariables runtime fault is thrown. This overrides the
domain level validateXML property. The following example enables validation
for only the StarLoanService partner:
validateXML
<partnerLinkBinding name="StarLoanService">
<property name="wsdlLocation">
http://<hostname>:9700/orabpel/default/StarLoan/Sta
rLoan?wsdl</property>
<property name="validateXML">true</property>
</partnerLinkBinding>
In the SOA Composite Editor, select the BPEL process service component, as
shown in Figure C1.
C-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Go to the Property Inspector in the lower right corner of Oracle JDeveloper. If the
Property Inspector is not displayed, select Property Inspector from the View main
menu.
3.
In the Properties section, click the Add icon, as shown in Figure C2.
For this example, the oneWayDeliveryPolicy property is already defined because
the Delivery option was selected in the Create BPEL Process dialog during BPEL
process creation. For more information about setting this property during BPEL
process creation, see Section 4.1.1, "How to Add a BPEL Process Service
Component."
In the Name field, enter the deployment descriptor property. For this example, the
configuration deployment descriptor property inMemoryOptimization is
defined. Therefore, a prefix of bpel.config is required. For more information
about configuration deployment descriptor properties, see Table C1.
If you instead add a partner link binding property, a prefix of
bpel.partnerLink.partner_link_name is required, where partner_
link_name is the name of the partner link (for example, LoanService). For
more information about partner link binding deployment descriptor properties,
see Table C2.
5.
In the Value field, enter an applicable value for this property (for example, true).
Figure C3 shows the completed Create Property dialog.
C-5
6.
Click OK.
The Property Inspector displays the added deployment descriptor property.
7.
If you instead define a partner link binding deployment descriptor property in the
Property Inspector (for example, the nonBlockingInvoke partner link binding
property), it is displayed in the composite.xml file, as shown in Example C2. Note
the prefix of bpel.partnerLink.partner_link_name, which is required for this
type of property.
Example C2 Partner Link Binding Property Definition in composite.xml
...
<component name="myBPELServiceComponent">
....
<property name="bpel.partnerLink.partner_link_name.
nonBlockingInvoke">false</property>
</component>
C-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Deprecated Properties
Property
completionPersistLevel
configurations
11g Release 1
defaultInput
configurations
11g Release 1
initializeVariables
configurations
11g Release 1
loadSchema
configurations
11g Release 1
noAlterWSDL
configurations
11g Release 1
optimizeVariableCopy
configurations
11g Release 1
relaxTypeChecking
configurations
11g Release 1
relaxXPathQName
configurations
11g Release 1
transaction
configurations
10.1.3.4
SLACompletionTime
configurations
11g Release 1
xpathValidation
configurations
11g Release 1
user
configurations
11g Release 1
pw
configurations
11g Release 1
role
configurations
11g Release 1
correlation
partnerLinkBinding
11g Release 1
contentType
partnerLinkBinding
10.1.3
retryInterval
partnerLinkBinding
retryMaxCount
partnerLinkBinding
wsdlLocation
partnerLinkBinding
11g Release 1
wsdlRuntimeLocation
partnerLinkBinding
11g Release 1
wsseHeaders
partnerLinkBinding
11g Release 1
wsseUsername
partnerLinkBinding
11g Release 1
wssePassword
partnerLinkBinding
11g Release 1
preferredPort
partnerLinkBinding
11g Release 1
fullWSAddressing
partnerLinkBinding
11g Release 1
C-7
C-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
D
Understanding Sensor Public Views and the
Sensor Actions XSD
This appendix describes the available sensor public views and the sensor actions XSD
file that you can import into Oracle BPEL Designer.
This appendix includes the following sections:
Section D.1, "Introduction to Sensor Public Views and the Sensor Actions XSD File"
For more information, see Chapter 18, "Using Oracle BPEL Process Manager Sensors."
D.1 Introduction to Sensor Public Views and the Sensor Actions XSD File
A set of public views is exposed to allow SQL access to sensor values from literally any
application interested in the data. In addition, a sample sensor action schema is
provided for importing into Oracle BPEL Designer.
D-1
D.2.1.1 BPEL_PROCESS_INSTANCES
Table D1 provides an overview of all the process instances of Oracle BPEL Process
Manager.
Table D1
BPEL_PROCESS_INSTANCES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
INSTANCE_KEY
NUMBER
--
PK
Unique instance ID
APPLICATION_
NAME
VARCHAR2
500
--
COMPOSITE_
NAME
VARCHAR2
500
--
REVISION
VARCHAR2
50
--
LABEL
VARCHAR2
500
--
User-defined label
COMPONENT_
NAME
VARCHAR2
500
--
TITLE
NVARCHAR2
200
--
STATE
NUMBER
--
--
STATE_TEXT
VARCHAR2
21
--
PRIORITY
NUMBER
--
--
STATUS
NVARCHAR2
200
--
STAGE
VARCHAR2
100
--
CONVERSATION_ VARCHAR2
ID
256
--
User-defined conversation ID of a
BPEL process
CREATION_DATE TIMESTAMP
--
MODIFY_DATE
TIMESTAMP
--
TS_DATE
DATE
--
--
TS_HOUR
NUMBER
--
--
EVAL_TIME
NUMBER
--
--
D.2.1.2 BPEL_ACTIVITY_SENSOR_VALUES
Table D2 contains all the activity sensor values of the monitored BPEL processes.
Table D2
BPEL_ACTIVITY_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
SENSOR_NAME
NVARCHAR2
200
U1,2
SENSOR_TARGET NVARCHAR2
512
--
ACTION_NAME
NVARCHAR2
200
U1,3
ACTION_FILTER NVARCHAR2
512
--
D-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Null?
Comment
CREATION_DATE TIMESTAMP
--
MODIFY_DATE
TIMESTAMP
--
TS_DATE
DATE
--
--
TS_HOUR
NUMBER
--
--
CRITERIA_
SATISFIED
VARCHAR2
--
NULL, Y, or N
ACTIVITY_NAME NVARCHAR2
200
--
ACTIVITY_TYPE VARCHAR2
30
--
ACTIVITY_
STATE
VARCHAR2
30
--
EVAL_POINT
VARCHAR2
30
--
ERROR_MESSAGE NCLOB
--
--
An error message
RETRY_COUNT
NUMBER
--
--
EVAL_TIME
NUMBER
--
--
ID
NUMBER
--
PK
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
BPEL process ID
APPLICATION_
NAME
VARCHAR2
500
--
COMPOSITE_
NAME
VARCHAR2
500
--
REVISION
VARCHAR2
50
--
LABEL
VARCHAR2
500
--
User-defined label
COMPONENT_
NAME
VARCHAR2
500
--
Attribute Name
SQL Type
D.2.1.3 BPEL_FAULT_SENSOR_VALUES
Table D3 contains all the fault sensor values.
Table D3
BPEL_FAULT_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
BPEL process ID
APPLICATION_
NAME
VARCHAR2
500
--
COMPOSITE_
NAME
VARCHAR2
500
--
REVISION
VARCHAR2
50
--
LABEL
VARCHAR2
500
--
User-defined label
D-3
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
COMPONENT_
NAME
VARCHAR2
500
--
SENSOR_NAME
NVARCHAR2
200
U1,2
SENSOR_TARGET NVARCHAR2
512
--
ACTION_NAME
NVARCHAR2
200
U1,3
ACTION_FILTER NVARCHAR2
512
--
CREATION_DATE TIMESTAMP
--
MODIFY_DATE
TIMESTAMP
--
TS_DATE
DATE
--
--
TS_HOUR
NUMBER
--
--
CRITERIA_
SATISFIED
VARCHAR2
--
ACTIVITY_NAME NVARCHAR2
200
--
ACTIVITY_TYPE VARCHAR2
30
--
MESSAGE
--
--
CLOB
D.2.1.4 BPEL_VARIABLE_SENSOR_VALUES
Table D4 contains all the variable sensor values.
Table D4
BPEL_VARIABLE_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
BPEL process ID
APPLICATION_
NAME
VARCHAR2
500
--
COMPOSITE_
NAME
VARCHAR2
500
--
REVISION
VARCHAR2
50
--
LABEL
VARCHAR2
500
--
User-defined label
COMPONENT_
NAME
VARCHAR2
500
--
SENSOR_NAME
NVARCHAR2
200
U1,2
SENSOR_TARGET NVARCHAR2
512
--
ACTION_NAME
NVARCHAR2
200
U1,3
ACTION_FILTER NVARCHAR2
512
--
ACTIVITY_
SENSOR
--
--
--
Creation date
NUMBER
CREATION_DATE TIMESTAMP
D-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
TS_DATE
DATE
--
--
TS_HOUR
NUMBER
--
--
VARIABLE_NAME NVARCHAR2
512
--
EVAL_POINT
VARCHAR2
30
--
CRITERIA_
SATISFIED
VARCHAR2
--
NULL, Y, or N
TARGET
NVARCHAR2
512
--
--
--
UPDATER_NAME
NVARCHAR2
200
--
UPDATER_TYPE
NVARCHAR2
200
--
SCHEMA_
NAMESPACE
NVARCHAR2
512
--
SCHEMA_
DATATYPE
NVARCHAR2
512
--
VALUE_TYPE
NUMBER
--
--
VARCHAR2_
VALUE
NVARCHAR2
4000
--
NUMBER_VALUE
NUMBER
--
--
DATE_VALUE
TIMESTAMP
--
User-defined date
DATE_VALUE_TZ VARCHAR2
10
--
BLOB_VALUE
BLOB
--
--
CLOB_VALUE
CLOB
--
--
D-5
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="BpelReportsSchema"/>
<xsd:enumeration value="JMSQueue"/>
<xsd:enumeration value="JMSTopic"/>
<xsd:enumeration value="Custom"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="tSensorActionProperty">
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" use="required" type="xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<!-Attributes of a sensor action
-->
<xsd:attributeGroup name="tSensorActionAttributes">
<xsd:attribute name="name" type="xsd:string" use="optional"/>
<xsd:attribute name="enabled" type="xsd:boolean" use="optional"
default="true"/>
<xsd:attribute name="filter" type="xsd:string"/>
<xsd:attribute name="publishName" type="xsd:string" use="required"/>
<xsd:attribute name="publishType" type="tns:tSensorActionPublishType"
use="required"/>
<!-the name of the JMS Queue/Topic or custom java API, ignored for other
publishTypes
-->
<xsd:attribute name="publishTarget" type="xsd:string" use="optional"/>
</xsd:attributeGroup>
<!-The sensor action type. A sensor action consists:
+ unique name
+ effective date
+ expiration date - Optional. If not defined, the probe is active
indefinitely.
+ filter (to potentially suppress data publishing even if a sensor marks
it as interesting). - Optional. If not defined, no filter is
used.
+ publishName A name of a publisher
+ publishType What to do with the sensor data?
+ publishTarget Name of a JMS Queue/Topic or custom publisher.
+ potentially many sensors.
-->
<xsd:complexType name="tSensorAction">
<xsd:sequence>
<xsd:element name="sensorName" type="xsd:string" minOccurs="1"
maxOccurs="unbounded"/>
<xsd:element name="property" minOccurs="0" maxOccurs="unbounded"
type="tns:tSensorActionProperty"/>
</xsd:sequence>
<xsd:attributeGroup ref="tns:tSensorActionAttributes"/>
</xsd:complexType>
D-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
D-7
D-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
<xsd:complexType name="tSensorList">
<xsd:sequence>
<xsd:element name="sensor" type="tns:tSensor" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tRouterData">
<xsd:sequence>
<xsd:element name="header" type="tns:tHeaderInfo"/>
<xsd:element name="payload" type="tns:tSensorData"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tHeaderInfo">
<xsd:sequence>
<xsd:element name="processName" type="xsd:string"/>
<xsd:element name="processRevision" type="xsd:string"/>
<xsd:element name="domain" type="xsd:string"/>
<xsd:element name="instanceId" type="xsd:integer"/>
<xsd:element name="midTierInstance" type="xsd:string"/>
<xsd:element name="timestamp" type="xsd:dateTime"/>
<xsd:element name="sensor" type="tns:tSensor"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tSensorData">
<xsd:sequence>
<xsd:element name="activityData" type="tns:tActivityData" minOccurs="0"/>
<xsd:element name="faultData" type="tns:tFaultData" minOccurs="0"/>
<xsd:element name="adapterData" minOccurs="0" type="tns:tAdapterData"/>
<xsd:element name="variableData" type="tns:tVariableData" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="notificationData" type="tns:tNotificationData"
minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tFaultData">
<xsd:sequence>
<xsd:element name="activityName" type="xsd:string"/>
<xsd:element name="activityType" type="xsd:string"/>
<xsd:element name="data" type="xsd:anyType" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tActivityData">
<xsd:sequence>
<xsd:element name="activityType" type="xsd:string"/>
<xsd:element name="evalPoint" type="xsd:string"/>
<xsd:element name="errorMessage" nillable="true" minOccurs="0"
type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<!-xml type that is provided to sensors for variable Datas. Note the
any element represents variable data.
-->
<xsd:complexType name="tVariableData">
D-9
<xsd:sequence>
<xsd:element name="target" type="xsd:string"/>
<xsd:element name="queryName" type="xsd:string"/>
<xsd:element name="updaterName" type="xsd:string" minOccurs="1"/>
<xsd:element name="updaterType" type="xsd:string" minOccurs="1"/>
<xsd:element name="data" type="xsd:anyType"/>
<xsd:element name="dataType" type="xsd:integer"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tNotificationData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="messageID" type="xsd:string" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="fromAddress" type="xsd:string" minOccurs="0"/>
<xsd:element name="toAddress" type="xsd:string" minOccurs="0"/>
<xsd:element name="deliveryChannel" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tAdapterData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="endpoint" type="xsd:string"/>
<xsd:element name="direction" type="xsd:string"/>
<xsd:element name="adapterType" type="xsd:string"/>
<xsd:element name="priority" type="xsd:string" minOccurs="0"/>
<xsd:element name="messageSize" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-The header of the document contains some metadata.
-->
<xsd:complexType name="tSensorActionHeader">
<xsd:sequence>
<xsd:element name="processName" type="xsd:string"/>
<xsd:element name="processVersion" type="xsd:string"/>
<xsd:element name="processID" type="xsd:long"/>
<xsd:element name="midTierInstance" type="xsd:string"/>
</xsd:sequence>
<xsd:attribute name="actionName" use="required" type="xsd:string"/>
</xsd:complexType>
<!-Sensor Action data is presented in the form of a header and potentially many
data elements depending on how many sensors associated to the sensor action
marked the data as interesting.
-->
<xsd:complexType name="tSensorActionData">
<xsd:sequence>
<xsd:element name="header" type="tns:tHeaderInfo"/>
<xsd:element name="payload" type="tns:tSensorData" minOccurs="1"
maxOccurs="1"/>
D-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</xsd:sequence>
</xsd:complexType>
<!-<xsd:simpleType name="tActivityEvalPoint">
<xsd:restriction>
<xsd:enumeration value="start"/>
<xsd:enumeration value="complete"/>
<xsd:enumeration value="fault"/>
<xsd:enumeration value="compensate"/>
<xsd:enumeration value="retry"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="tNotificationAction">
<xsd:restriction>
<xsd:enumeration value="creation"/>
<xsd:enumeration value="statusUpdate"/>
</xsd:restriction>
</xsd:simpleType>
-->
<!-The process sensor value header comprises of a timestamp
where the sensor was triggered and the sensor metadata
-->
<xsd:complexType name="tProcessSensorValueHeader">
<xsd:sequence>
<xsd:element name="timestamp" type="xsd:dateTime"/>
<xsd:element ref="tns:sensor"/>
</xsd:sequence>
</xsd:complexType>
<!-Extend tActivityData to include more elements
-->
<xsd:complexType name="tProcessActivityData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="evalTime" type="xsd:long" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="retryCount" type="xsd:int" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tVariableData to include more elements
-->
<xsd:complexType name="tProcessVariableData">
<xsd:complexContent>
<xsd:extension base="tns:tVariableData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
Understanding Sensor Public Views and the Sensor Actions XSD D-11
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tFaultData to include more elements
-->
<xsd:complexType name="tProcessFaultData">
<xsd:complexContent>
<xsd:extension base="tns:tFaultData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tAdapterData to include more elements
-->
<xsd:complexType name="tProcessAdapterData">
<xsd:complexContent>
<xsd:extension base="tns:tAdapterData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tNotificationData to include more elements
-->
<xsd:complexType name="tProcessNotificationData">
<xsd:complexContent>
<xsd:extension base="tns:tNotificationData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Copy of tSensorData type with some modified types.
-->
<xsd:complexType name="tProcessSensorData">
<xsd:sequence>
D-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Understanding Sensor Public Views and the Sensor Actions XSD D-13
<!-- actionData elements are produced by the sensor framework and sent to the
appropriate data publishers when sensors 'fire' -->
<xsd:element name="actionData" type="tns:tSensorActionData"/>
<!-- This element is used when the client API is used to query sensor values
stored in the default reports schema -->
<xsd:element name="sensorValues" type="tns:tProcessSensorValueList"/>
</xsd:schema>
D-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
E
E
More information about the Oracle BAM web services is available in Chapter 59,
"Using Oracle BAM Web Services."
E.1 DataObjectOperations10131
The following operations are supported by the DataObjectOperations10131 web
service:
E.1.1 Batch
Batch performs batch operations on a data object.
E-1
DataObjectOperations10131
xmlPayload (xsd:string)
Contains the batch payload for any operations to be performed. For example:
<payload>
<_Employees operation="insert">
<_Salesperson>Tim Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
<_Employees operation="update" keys="_Sales_Number">
<_Salesperson>Tim Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
</payload>
E.1.2 Delete
Delete removes a row from the data object.
E.1.3 Insert
Insert adds rows to the specified data object.
xmlPayload (xsd:string)
The payload is specific to each data object.
<_Employees>
<_Salesperson>Time Bray</_Salesperson>
E-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
DataObjectOperations10131
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E.1.4 Update
Update operation updates existing data with new data in a data object.
keysCSV (xsd:string)
Comma separated column IDs that must be used as keys, for example:
_Sales_Number,_Sales_Area
xmlPayload (xsd:string)
Payload for the update statement and where clause to update rows in a data object.
For example:
<_Employees>
<_Sales_Area>Asia Pacific</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E.1.5 Upsert
Upsert operation updates existing data with new data in an existing row in a data
object. If the row does not exist a new row is created.
keysCSV (xsd:string)
Comma separated column IDs that must be used as keys, for example:
_Sales_Number,_Sales_Area
xmlPayload (xsd:string)
Payload for the insert or update statement and where clause to upsert rows in a data
object. For example:
<_Employees>
<_Salesperson>Time Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
Oracle BAM Web Services Operations
E-3
DataObjectOperationsByName
E.2 DataObjectOperationsByName
The following operations are supported by the DataObjectOperations10131,
DataObjectOperationsByName, and DataObjectOperationsByID web services.
E.2.1 Delete
Delete removes a row from the data object.
xmlPayload (xsd:string)
Payload for the where clause to delete rows in a data object. For example:
<DataObject Name="Employees" Path="/Samples">
<Contents>
<Row>
<Column Name="Salesperson" Value="Greg Guan" />
</Row>
</Contents>
</DataObject>
E.2.2 Get
Get fetches the details from a data object per the specifications in the XML payload
Get is only available in DataObjectOperationsByName web service.
xmlPayload (xsd:string)
The payload specifies what to get from the data object.
For the DataObjectOperationsByName web service the data object name is specified in
the payload, for example:
<DataObject Name="Employees" Path="/Samples">
<Contents>
E-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
DataObjectOperationsByName
<Row>
<Column Name="Salesperson" Value="Greg Masters"/>
</Row>
</Contents>
</DataObject>
E.2.3 Insert
Insert adds rows to the specified data object.
E.2.4 Update
Update operation updates existing data with new data in a data object.
xmlPayload (xsd:string)
Payload for the update statement and where clause to update rows in a data object.
For example:
<DataObject Name="Employees" Path="/Samples">
<Contents>
<Row>
<Column Name="Salesperson" Value="Greg Guan" />
</Row>
</Contents>
</DataObject>
E.2.5 Upsert
Upsert operation updates existing data with new data in an existing row in a data
object. If the row does not exist a new row is created.
E-5
DataObjectOperationsByID
xmlPayload (xsd:string)
Payload for the insert or update statement and where clause to upsert rows in a data
object. For example:
<DataObject Name="Employees" Path="/Samples">
<Contents>
<Row>
<Column Name="Salesperson" Value="Greg Guan" />
<Column Name="Sales Area" Value="Northeast" />
<column Name="Sales Number" Value="5671" />
</Row>
</Contents>
</DataObject>
E.3 DataObjectOperationsByID
The following operations are supported by the DataObjectOperations10131,
DataObjectOperationsByName, and DataObjectOperationsByID web services.
E.3.1 Batch
Batch performs batch operations on a data object.
xmlPayload (xsd:string)
Contains the batch payload for any operations to be performed. For example:
<payload>
<_Employees operation="insert">
<_Salesperson>Tim Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
<_Employees operation="update" keys="_Sales_Number">
E-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
DataObjectOperationsByID
<_Salesperson>Tim Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
</payload>
E.3.2 Delete
Delete removes a row from the data object.
keysCSV (xsd:string)
Comma separated column IDs that must be used as keys, for example:
_Sales_Number,_Sales_Area
xmlPayload (xsd:string)
Payload for the where clause to delete rows in a data object. For example:
<_Employees>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E.3.3 Insert
Insert adds rows to the specified data object.
xmlPayload (xsd:string)
The payload is specific to each data object.
For the DataObjectOperationsByName web service the data object name is specified in
the payload, for example:
<_Employees>
<_Salesperson>Time Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E-7
DataObjectOperationsByID
E.3.4 Update
Update operation updates existing data with new data in a data object.
keysCSV (xsd:string)
Comma separated column IDs that must be used as keys, for example:
_Sales_Number,_Sales_Area
xmlPayload (xsd:string)
Payload for the update statement and where clause to update rows in a data object.
For example:
<_Employees>
<_Sales_Area>Asia Pacific</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E.3.5 Upsert
Upsert operation updates existing data with new data in an existing row in a data
object. If the row does not exist a new row is created.
keysCSV (xsd:string)
Comma separated column IDs that must be used as keys, for example:
_Sales_Number,_Sales_Area
xmlPayload (xsd:string)
Payload for the insert or update statement and where clause to upsert rows in a data
object. For example:
<_Employees>
<_Salesperson>Time Bray</_Salesperson>
<_Sales_Area>EMEA</_Sales_Area>
<_Sales_Number>12345</_Sales_Number>
</_Employees>
E-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
DataObjectDefinition Operations
E.4.1 Create
Create creates a new data object. By specifying columnar elements, you can create
calculated and lookup fields in addition to regular fields ass show in the examples.
Element
/DataObject/@External
/DataObject/@Name
/DataObject/@Path
/DataObject/@Version
/DataObject/@TipText
/DataObject/Layout/Column/@Name
/DataObject/Layout/Column/@Type
/DataObject/Layout/Column/@Nullable
/DataObject/Layout/Column/@Public
E-9
DataObjectDefinition Operations
Table E1
Element
/DataObject/Layout/Column/@MaxSize
/DataObject/Layout/Column/@Precision
/DataObject/Layout/Column/@Scale
/DataObject/Layout/Column/@TipText
Column description
When you construct the XML payload for the Create operation, and the data object
version is lower than 12, use PrimaryKey instead of PrimaryKeyID, ForeignKey
instead of ForeignKeyID, LookupField instead of LookupFieldID, and provide name
values instead of IDs for those fields.
E-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
DataObjectDefinition Operations
E.4.2 Delete
Delete removes a data object definition and its contents.
E.4.3 Get
Get retrieves an existing data object definition.
ManualRuleFire Operations
xmlPayload (xsd:string)
An XML description of the data object is returned. The schema used is the same
definition as described for the Create and Update operations. You can use this
operation to find the ID values of the data object and any columns.
Example E4 xmlPayload for Get Operation
<DataObject Version="14" Name="Employees" Path="/Samples" External="0">
<Layout>
<Column Name="Salesperson" ID="_Salesperson" Type="string" MaxSize="100"
Nullable="1" Public="1" />
<Column Name="Sales Area" ID="_Sales_Area" Type="string" MaxSize="100"
Nullable="1" Public="1" />
<Column Name="Sales Number" ID="_Sales_Number" Type="integer" Nullable="1"
Public="1" />
<Column Name="Timestamp" ID="_Timestamp" Type="timestamp" Nullable="0" />
Public="1" />
<Indexes />
</Layout>
</DataObject>
E.4.4 Update
Update updates the definition of an existing data object. If a specified column exists in
the original definition, the new column definition overwrites the old one. If columns in
the existing definition are not specified in the new definition, their definitions are
removed. The data object index definition can be updated as well.
E-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
ManualRuleFire Operations
E.5.1 FireRuleByName
Use this operation to manually launch a rule.
This web service takes a string parameter, which should have user name, followed by
a period (.), followed by the alert name. For example:
user_name.alertname
The period is used as a separator between the user name and the alert name. The web
service always treats last period in the string as the separator, allowing the user name
to contain periods. For example
user.nema.alerrtname
It follows then that the alert names cannot contain a period. If you must use the
ManualRuleFire web service with an alert containing a period in its name, the alert
must be renamed so that it does not contain any periods.
ManualRuleFire Operations
E-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
F
Oracle BAM Alert Rule Options
This appendix describes the events, conditions, and actions that are used in defining
Oracle Business Activity Monitoring (Oracle BAM) alert rules.
This appendix includes the following sections:
For information about modifying alerts when the user is a member of the
administrative role, see Section 60.2.5, "What You May Need to Know About
Modifying Alerts."
F.1 Events
Events launch the rule and trigger the action. Each rule contains only one event. Oracle
BAM provides the following events:
Events
select time
Set the times of day between which the rule is valid and the alert is launched.
select date
Set the date on which the rule is valid and the alert is launched.
select time
Set the time of day at which the rule is valid and the alert is launched.
select report
Select the report to monitor for changes.
run as <user_name> (This option appears only if the user creating the alert is a
member of the administrator role.)
Select the Oracle BAM user who the selected report runs as. You can select only
one run as user. The default run as user is the logged in Oracle BAM user who is
creating the alert.
Only recipients who have security permissions that are the same or higher than
the run as user receive the notification for report changes, honoring row level
F-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Events
security as implemented by the Oracle BAM Architect in the data objects used in
the report.
Names that are preceded with a hash (#) are distribution lists.
If there are changes in a reports data object rows that none of the alert recipients
have permissions to access, no recipients are notified.
Note:
run as <user_name> (This option appears only if the user creating the alert is a
member of the administrator role.)
Select the Oracle BAM user who the selected report runs as. You can select only
one run as user. The default run as user is the logged in Oracle BAM user who is
creating the alert.
Only recipients who have security permissions that are the same or higher than
the run as user receive the notification for report changes, honoring row level
security as implemented by the Oracle BAM Architect in the data objects used in
the report.
Names that are preceded with a hash (#) are distribution lists.
If there are changes in a reports data object rows that none of the alert recipients
have permissions to access, no recipients are notified.
select report
Select the report to monitor for changes.
Row Filter - Create a filter on a field in the data object to express a condition
that, when met, launches the rule. All of the functionality available in report
filters is provided. See "Filtering Data" in Oracle Fusion Middleware User's Guide
for Oracle Business Activity Monitoring for more information.
Events
Group Filter - The Group Filter is similar to the Row Filter in that it provides
all of the filtering functionality available in report filters. The special feature
here is that it allows filters to be created on a field where a summary function
has been applied. See "Filtering Data" in Oracle Fusion Middleware User's Guide
for Oracle Business Activity Monitoring for more information about building
filter expressions.
Group - Choose one or more fields on which to create a grouping, adding
further complexity to any filters created in the Row Filter or Group Filter tabs.
run as <user_name> (This option appears only if the user creating the alert is a
member of the administrator role.)
Select the Oracle BAM user who the selected report runs as. You can select only
one run as user. The default run as user is the logged in Oracle BAM user who is
creating the alert.
Only recipients who have security permissions that are the same or higher than
the run as user receive the notification for report changes, honoring row level
security as implemented by the Oracle BAM Architect in the data objects used in
the report.
Names that are preceded with a hash (#) are distribution lists.
If there are changes in a reports data object rows that none of the alert recipients
have permissions to access, no recipients are notified.
Note:
Row Filter - Create a filter on a field in the data object to express a condition
that, when met, launches the rule. All of the functionality available in report
filters is provided. See "Filtering Data" in Oracle Fusion Middleware User's Guide
for Oracle Business Activity Monitoring for more information.
Group Filter - The Group Filter is similar to the Row Filter in that it provides
all of the filtering functionality available in report filters. The special feature
here is that it allows filters to be created on a field where a summary function
has been applied. See "Filtering Data" in Oracle Fusion Middleware User's Guide
for Oracle Business Activity Monitoring for more information about building
filter expressions.
Group - Choose one or more fields on which to create a grouping, adding
further complexity to any filters created in the Row Filter or Group Filter tabs.
run as <user_name> (This option appears only if the user creating the alert is a
member of the administrator role.)
F-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Actions
Select the Oracle BAM user who the selected report runs as. You can select only
one run as user. The default run as user is the logged in Oracle BAM user who is
creating the alert.
Names that are preceded with a hash (#) are distribution lists.
Only recipients who have security permissions that are the same or higher than
the run as user receive the notification for report changes, honoring row level
security as implemented by the Oracle BAM Architect in the data objects used in
the report.
If there are changes in a reports data object rows that none of the alert recipients
have permissions to access, no recipients are notified.
F.2 Conditions
Conditions are optional settings for constraining the time period in which the alert is
fired. You can select any number and combination of conditions. Oracle BAM provides
the following conditions:
F.3 Actions
Actions are the results of the conditions and events of the rule expression having been
met. You can configure any number and combination of actions. Oracle BAM provides
the following actions:
Send a report via email and escalate to another user after a specific amount of time
Launch a rule
Oracle BAM Alert Rule Options F-5
Actions
F.3.3 Send a report via email and escalate to another user after a specific amount of
time
Select a report to send to the specified user. Select a secondary recipient to receive the
message if the first recipient does not respond within the specified time period. The
secondary recipient can be a single user or a distribution list.
When the condition of the alert rule is met, a report link is sent to the recipient. To
respond to this alert, the recipient must click the report link and view the report. If the
recipient does not view the report, it is escalated to the secondary user (or distribution
list).
Recipients can be selected from Oracle BAM users, or, if a property is set in Oracle
BAM, external e-mail accounts. See Section 60.9, "Sending Alerts to External E-mail
Accounts" for more information.
F-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Actions
Enter a subject and message to send to the recipient. You can also select links to
reports to send in the message body as shown in Figure F1.
To configure the parameter values that are passed to the report when it is opened
by the recipient:
1. Click set parameters in the rule expression.
2.
In the Alert Action Parameter Creation and Edit dialog box, populate the User and
Report fields with either predefined values or dynamically from a Data Object
field. Use the buttons to set the field values. Select Field enables you to select a
field in a data object as a value.
Actions
User field
If you populate this field using the Select User button, the recipients are
selected from Oracle BAM users listed in Oracle BAM Administrator as shown
in Figure F3.
Report field
If you populate this field with the Select Report button, the value that appears
in this field is the display name of the report.
If you populate this field from a Data Object, the value must be the report ID
of that report, and not the display name. To get the report ID, click the report
and click the Copy Shortcut link. A window opens with a link such as:
http://myServer/oraclebam/ReportServer/default.aspx?Event=ViewReport&
ReportDef=1&Buttons=False
In this link the ReportDef value, 1, is the report ID of the report Emp_Report.
Every report in Oracle Business Activity Monitoring has a unique report ID.
F-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Actions
3.
Enter the parameter name in the Name field, and click Select Field to select the
field on which the parameter acts.
Key in the parameter value, or select the field from the Field Selection dialog box,
and click OK.
For special values use the underscore (_), for example, _ALL_, _BLANK_, and _
NULL_.
Actions
The selected field ID appears in the Value text box. Click OK to confirm and
return to the parameters list.
F.3.5 Send a parameterized message for every matching row in a data object
This action can pick up recipients, message content, and the message subject from
rows of a static data object. You can specify filter conditions in the configuration screen
to choose data object rows for conditional notification. This action can be configured
with any event, condition, or action.
When this action is invoked, the rows in the data object that match the filter criteria are
used to construct an e-mail message (using the data object parameters specified in the
action) which is sent out to the recipients. Message creation is similar to that in
Section F.3.4, "Send a parameterized message."
To configure the action:
1. Click the this data field has a condition of X link and select the data object and
filter condition to select the desired rows.
F-10
Actions
Note: The data object and filter conditions must be selected first so
that the data object fields appear.
2.
Click the create message link, and compose the e-mail message, with data object
fields if required, similar to Section F.3.4, "Send a parameterized message".
3.
Click the set parameters link and select a recipient (in User) and a report
(optional), similar to Section F.3.4, "Send a parameterized message".
4.
If any reports that are dependent upon the data object from which data is being
deleted are open at the time the Delete rows from a Data Object action executes,
the active data is stopped on the viewsets and reloaded after deletion is complete.
Also, if a user attempts to open a report while the delete action for a dependent
data object is in process, the report gets stuck or the outcome may be undefined. It
is recommended that users do not open reports dependent on the data object
while this action is in process. The reports continue to receive active data when the
action is finished.
In addition, during Delete rows from a Data Object execution, any alerts that are
dependent on that data object are temporarily disabled internally. While this
action is being run, any new alert created using that data object, or any dependent
existing alerts that are disabled and reenabled, results in the system getting stuck.
It is recommended that users do not create, disable, or reenable any alerts
dependent on the data object while this action is in process. The alerts continue to
function normally after the action is finished.
Enter the web service or WSIL endpoint URL. The URL must begin with the http
scheme and must end in a valid extension (?WSDL, .WSDL or .WSIL).
For example:
http://host_name:port_
number/OracleBAMWS/WebServices/DataObjectOperationsByID?WSDL
http://api.google.com/GoogleSearch.wsdl
Actions
http://host_name:port_number/inspection.wsil
If it is a secure web service select the box and enter the required credentials.
Oracle BAM cannot determine if the web service is hosted on a
server which is behind a secure server. It is your responsibility to
indicate whether the web service is behind an HTTP basic
authentication based server, and you must enter valid credentials if
they are required.
Note:
If it is a secure web service check the Secure Web Service checkbox and enter the
required credentials.
3.
Click Display Services to display the available services of the URL entered in the
field.
4.
The Endpoint URL field, which is initially disabled and empty, is populated after
you enter the WSDL/WSIL and credentials, get the list of operations, and select an
operation.
It is populated with the endpoint URL defined in the WSDL file of the web service.
If you find this endpoint URL outdated (for example, the web service
implementation moved to a different endpoint but you do not have the new
WSDL, but know the new endpoint URL) or incorrect, or want to override it, you
can edit this URL. When the web service is invoked by Oracle BAM Event Engine,
the configured endpoint URL is used to invoke the web service.
5.
6.
Click OK to close the Alert Web Service - Parameter Mapping dialog box and the
Alert Web Service Configuration dialog box.
See Section F.3.9.1, "How to Use Call a Web Service: An Example" for a specific
example.
If the web service does not respond to the call, then there are
no logs available pertaining to the non-response or failure.
Note:
F-12
Actions
Log in to Oracle BAM web applications, and open Oracle BAM Active Studio.
3.
4.
5.
In the Select an Event list, select the first option: In a specific amount of time.
6.
Click select time interval in the Rule Expression panel, and select 1 Second as the
time.
7.
8.
In the Select an Action list, select the action Call a Web Service.
9.
where host_name and port_number are substituted with your Oracle BAM
instance's host name and port number.
11. Select the Secure Web Service checkbox, and provide the credentials.
12. Click Display Operations, and in the operations listed, select the operation Insert.
This populates the endpoint URL of your web service. If the endpoint your of your
web service has changed, or you want to override it with some other
implementation, provide the new endpoint URL, otherwise, leave it as it is.
13. Click Map Parameters to provide the values that map to the parameters in this
web service.
The web service operation in this example requires a value for only one parameter,
an XML payload containing the row to insert in the data object.
Enter the following text in the xmlpayload value and click.
<DataObject Name="Employees" Path="/Samples"><Contents><Row><Column
Name="Salesperson" Value="Greg Guan Gan" /><Column Name="Sales Area"
Value="Northeast" /><Column Name="Sales Number" Value="1234"
/></Row></Contents></DataObject>
14. Click OK to close the Alert Web Service Configuration dialog, and click OK in the
/Samples/Employees data object to verify that the new row with Salesperson
name Greg Guan Gan is inserted in the data object.
Frequency Constraint
F-14
G
G
Command
Parameters
clear
-name itemname
[-type [dataobject|folder|distributionlist]]
For more information about clear see Section G.2.1, "Clear."
Parameters
delete
[-name itemname]
[-type [dataobject|folder|report|rule|securityfilters|
distributionlist|ems|eds|all]]
[-match pattern]
[-regex regularexpression]
[-all [0|1]]
[-systemobjects [0|1]]
For more information about delete see Section G.2.2, "Delete."
export
-file file_name
[-name itemname]
[-type [dataobject|folder|report|rule|securityfilters|
distributionlist|ems|eds|all]]
[-match pattern]
[-regex regularexpression]
[-all [0|1]]
[-systemobjects [0|1]]
[-dependencies [0|1]]
[-layout [0|1]]
[-contents [0|1]]
[-permissions [0|1]]
[-owner [0|1]]
[-header [0|1]]
[-footer [0|1]]
[-append [0|1]]
[-preview [0|1]]
For more information about export see Section G.2.3, "Export."
import
-file file_name
-continueonerror
[-delay milliseconds]
[-updatelayout]
[-mode [preserveid|update|overwrite|append|rename|error]]
[-preserveowner]
[-setcol col_name/[null|now|value:override_value]]
[-preview]
For more information about import see Section G.2.4, "Import."
rename
-name itemname
-newname newitemname
[-type [dataobject|folder|report|rule|distributionlist|ems|
eds]]
For more information about rename see Section G.2.5, "Rename."
G-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
G.2.1 Clear
Clears the contents of an item in the Active Data Cache.
What it means to be cleared depends upon the item type:
For Data Objects, all existing rows within the Data Object are deleted.
For Distribution Lists, all members (users and groups) are removed from the
distribution list.
Table G2
Parameter
Description
-name itemname
-type itemtype
folder
distributionlist
G.2.2 Delete
Deletes an item from the Active Data Cache.
Table G3
Parameter
Description
-all [0|1]
Controls whether all items of the specified type are deleted (see
Example G5).
A nonzero or omitted value means delete all items of the
specified type, a zero (0) value means only delete the named (or
matched) items. Zero is assumed if this parameter is omitted.
-match pattern
-name itemname
Description
-regex regularexpr
-systemobjects [0|1]
-type itemtype
folder
rule
distributionlist
This command deletes a data object named TestDO. Note that dataobject type is
assumed if the type parameter is not specified.
icommand -cmd delete -name TestDO
Example G3
For any ICommand operation on alerts, the value of the type parameter is rule. This
command deletes a rule named MyAlert.
icommand -cmd delete -type rule -name "MyAlert"
Example G4
To delete security filters defined on a data object, the name of the data object must be
specified, instead of name of the security filter. This command deletes all security
filters defined on the data object MyDataObject.
icommand -cmd delete -type securityfilters -name "MyDataObject"
Example G5
This command deletes all items except systemobjects (data objects in the System
folder).
icommand -cmd delete -type all
G-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
G.2.3 Export
Exports information about one or more objects in the Active Data Cache to an XML
file. See Section G.5, "Sample Export File" for an example of an exported data object.
Table G4
Parameter
Description
-all [0|1]
-append [0|1]
-contents [0|1]
Description
-dependencies [0|1]
-footer [0|1]
-header [0|1]
-layout [0|1]
G-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
-match pattern
-name itemname
-owner [0|1]
-permissions [0|1]
-preview [0|1]
-regex regularexpr
-systemobjects [0|1]
Description
-type itemtype
Note that the type parameter was not included in this example. By default
dataobject is assigned to type if it is not specified.
Example G8
Note that the data object name was not preceded by the slash (/). When a Data Object
is in the root Data Objects folder, a slash is not required.
Example G9
In the first case, the private:owner/Report prefix is used in the name parameter
because the user exporting the folder is not the folder owner.
icommand -cmd export -name "/private:bamadmin/Report/TestMainFolder/TestSubFolder"
-type folder -file C:\FolderExportTest.xml
In the second case, the private:owner/Report prefix was not used in the name
parameter because the user exporting the folder is the folder owner.
icommand -cmd export -name "/TestMainFolder/TestSubFolder" -type folder -file
C:\FolderExportTest.xml
Example G10 Exporting a Folder from Shared Reports
icommand -cmd export -name "/public/Report/MainFolderInShared" -type folder -file
C:\FolderExportTest2.xml
G-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Note that in the name parameter the name of the Data Object is specified rather than
the name of the security filter.
Example G17 Exporting a Distribution List
icommand -cmd export -name MyDistList -type distributionlist -file
C:\MyDistList.xml
The dependent reports are automatically determined and exported first. They are
imported again when you import the specified report.
Example G23 Using Append Parameter in Export
In the first case (the incorrect example), Append is used without setting the Header
and Footer parameters (by default Header and Footer are set to 1).
icommand -cmd export -type dataobject -name "/Samples/Call Center" -file do.xml
icommand -cmd export -type dataobject -name "/Samples/Employees" -file do.xml
-append
icommand -cmd export -type dataobject -name "/Samples/Film Sales" -file do.xml
-append
The output from these commands is as follows. Notice that an XML header and
closing tags are included with each append to the file. If this file is used for importing
data into Oracle BAM, only the first object is imported. As soon as the first
</OracleBAMExport> is read at line 4, the import stops.
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
<exported object/>
</OracleBAMExport>
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
<exported object/>
</OracleBAMExport>
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
<exported object/>
</OracleBAMExport>
In the second case (the correct example), The Header and Footer parameters are
specified to produce the necessary output.
icommand -cmd export -type dataobject -name "/Samples/Call Center" -file do2.xml
-header 1 -footer 0
//only the footer is supressed in the first command
icommand -cmd export -type dataobject -name "/Samples/Employees" -file do2.xml
-append 1 -header 0 -footer 0
//both the header and the footer are suppressed in the intermediate commands
icommand -cmd export -type dataobject -name "/Samples/Film Sales" -file do2.xml
-append 1 -header 0 -footer 1
//only the header is suppressed in the last commands
The output file produced by these commands can import the objects into Oracle BAM
Server.
<?xml version="1.0"?>
<OracleBAMExport Version="2020">
<exported object>
<exported object>
</OracleBAMExport>
G.2.4 Import
Imports the information from an XML file to an object in the Active Data Cache. The
object may be created, replaced, or updated.
G-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
If the object does not exist, it is created if possible. For Data Objects, the input file must
contain layout information to create the Data Object, and if the file contains no content
information, then an empty Data Object is created.
If the user running ICommand is not an administrator, Reports are always imported to
the private folders of the user running ICommand. If the path information in the
import file exactly matches existing private folders of the user running ICommand, the
imported report is placed in that location. Otherwise, it is placed into the root of that
user's private folders.
If the user running ICommand is an administrator, then the preserveowner option
may be used to allow Folders, Reports and Rules to be imported with their original
ownership and to their original location.
Table G5
Parameter
Description
-file file_name
-preserveowner
-preview [0|1]
Description
-mode mode
overwrite
If the item exists, replaces it with the imported item.
rename
If the item exists, changes the name of the imported item.
The new name is computed automatically and reported in
a message.
error
If the item exists, terminates the import with an error.
overwrite
If the item exists, replaces it with the imported item.
rename
If the item exists, changes the name of the imported item.
The new name is computed automatically and reported in
a message.
append
If the item exists, appends the users in the imported list to
the existing list.
error
If the item exists, terminates the import with an error.
preserveid
This option is important because some other items, such as
Reports, point to the Data Objects they use by ID, not by
name.
Data Object Usage:
If the imported Data Object does not exist and must be
created, ICommand attempts to assign the Data Object the
same internal ID that the exported Data Object had. If it
cannot, the import is terminated with an error.
Report Usage:
If the imported Report does not exist and must be created,
ICommand attempts to assign the Report the same internal
ID that the exported Report had. If it cannot, the import is
terminated with an error.
G-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
update
Typically, when ICommand imports a Data Object, it
creates a new Data Object or locates the existing Data
Object and inserts the imported rows into that Data Object.
In update mode, ICommand instead attempts to locate
existing matching rows by Row ID, and updates those
existing rows with the values in the import file.
Unmatched rows are inserted. For matching Row IDs in
the import file that have no data columns specified, the
rows are deleted from the existing Data Object.
Description
-updatelayout
G.2.5 Rename
Renames an item in the Active Data Cache.
Table G6
Parameter
Description
-name itemname
-newname newitemname
-type itemtype
rule
G-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For any ICommand operation on alerts, the value of the type parameter is rule. This
command renames a rule named MyAlert.
icommand -cmd rename -type rule -name "MyAlert" -newname "MyRenamedAlert"
The output of this sample command file is shown in Section G.4, "Format of Log File."
G-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
[ErrorSource="ICommandEngine",ErrorID="ICommandEngine.DOExist"]]]>
</Error>
</ICommandLog>
In Example G32, continueonerror only applies to the command that deletes Data
Object A. If this command fails, then ICommand outputs the error and continues. But
if any other command fails, ICommand stops immediately.
Example G32 Enabling Command-Level ContinueOnError Mode
<OracleBAMCommands>
<Delete id="1" type="dataobject"
<Delete id="2" type="dataobject"
<Delete id="3" type="dataobject"
<Delete id="4" type="dataobject"
</OracleBAMCommands>
name="Data
name="Data
name="Data
name="Data
Object
Object
Object
Object
A" continueonerror="1"/>
B"/>
C"/>
D"/>
G-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Regular Expressions
Note:
Table G7 contains the complete list of metacharacters and their behavior in the
context of regular expressions.
Table G7
Character
Description
Matches the position at the end of the input string. If the RegExp
object's Multiline property is set, $ also matches the position
preceding '\n' or '\r'.
{n}
{n,}
{n,m}
(pattern)
Regular Expressions
Description
(?:pattern)
(?=pattern)
(?!pattern)
x|y
[xyz]
[^xyz]
[a-z]
[^a-z]
\b
\B
\cx
\d
\D
\f
\n
\r
G-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Regular Expressions
Description
\s
\S
\t
\v
\w
\W
\xn
\num
\n
\nm
\nml
Matches octal escape value nml when n is an octal digit (0-3) and
m and l are octal digits (0-7).
\un
Regular Expressions
G-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
H
Normalized Message Properties
This appendix describes how to set normalized message properties that enable you to
propagate these properties through message headers.
This appendix includes the following sections:
H-1
A normalized message is simplified to have only two parts, properties and payload.
Typically, properties are name-value pairs of scalar types. To fit the existing complex
headers into properties, properties are flattened into scalar types.
The user experience is simplified while manipulating headers in design time, because
the complex properties are predetermined. In the Mediator Editor or Oracle BPEL
Designer, you can manipulate the headers with some reserved key words.
However, this method does not address the properties that are dynamically generated
based on your input. Based on your choice, the header definitions are defined. These
definitions are not predetermined and therefore cannot be accounted for in the list of
predetermined property definitions. You cannot design header manipulation of the
dynamic properties before they are defined. To address this limitation, you must
generate all the necessary services (composite entry points) and references. This
restriction applies to services that are expected to generate dynamic properties. Once
dynamic properties are generated, they must be stored for each composite. Only then
can you manipulate the dynamic properties in the Mediator Editor or Oracle BPEL
Designer.
For more information on normalized message properties, see Oracle Fusion Middleware
User's Guide for Technology Adapters and Oracle Fusion Middleware User's Guide for Oracle
B2B.
Direction
(Inbound
Data
/Outbound) Type
Range of
Valid
Values
Description
bpel.instanceInde
x1
No
Inbound
String
Any
string, size
limit: 100
bpel.instanceInde
x2
No
Inbound
String
Any
string, size
limit: 100
bpel.instanceInde
x3
No
Inbound
String
Any
string, size
limit: 100
bpel.metadata
Yes
Both
String
Any
string, size
limit: 1000
Property Name
H-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Property Name
Propagatable
(Yes/No)
Direction
(Inbound
Data
/Outbound) Type
Range of
Valid
Values
bpel.priority
Yes
Inbound
String
that can
be read
into an
integer
(1-10). 1
being the
highest
priority
bpel.retryFatalCo
nnection
Yes
Inbound
boolean
true (the
default
value) or
false
bpel.title
No
Inbound
String
Any
string, size
limit: 100
Description
H-3
Table H2
Property Name
Propagatable
(Yes/No)
Direction
(Inbound
Data
/Outbound) Type
Range of
Valid Values
wsa.messageId
No
Inbound
String
URI format
wsa.relatesTo
No
Inbound
String
URI format
This optional
(repeating) element
information item
contributes one
abstract relationship
property value, in the
form of an (IRI,
IRI) pair. The content
of this element (of type
xs:anyURI) conveys
the message ID of the
related message.
wsa.replyToAddress
No
Inbound
String
URI format
Represents a contract
between two
components
communicating
asynchronously.
wsa.replyToPortType
No
Inbound
QName
Any QName
H-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Description
Property Name
Propagatable
(Yes/No)
Direction
(Inbound
Data
/Outbound) Type
Range of
Valid Values
wsa.replyToService
No
Inbound
QName
Any QName
wsa.action
No
Inbound
String
URI format
wsa.to
No
Inbound
String
URI format
Description
H-5
part="NCName" query="string"/>*
</onMessage>
<reply ...>
<bpelx:property name="NCName" expression="string" variable="NCName"
part="NCName" query="string"/>*
</reply>
H-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
I
Interfaces Implemented By Rules Dictionary
Editor Task Flow
This appendix describes the Oracle Business Rules Dictionary Editor Task Flow, which
implements the MetadataDetails and NLSPrefrences interfaces when creating
an ADF-based Web application. The interfaces are defined in the
soaComposerTemplates.jar file.
This appendix includes the following sections:
I-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
} finally {
if (writer != null) {
try {
writer.close();
} catch (IOException ioe) {
System.err.println(ioe);
}
}
}
}
I-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
I-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
J
Oracle User Messaging Service Applications
This appendix describes how to create your own Oracle User Messaging Service
applications using the procedures and code provided.
This appendix includes the following sections:
Section J.1, "Installing and Configuring SOA and User Messaging Service"
Note:
Using Enterprise Manager, go to the SOA Infrastructure menu, and select SOA
Administration > Workflow Config > Mailer tab and set Notification Mode to
ALL.
2.
3.
Set the email address for user weblogic by using the JXplorer LDAP browser.
Refer to "Updating Addresses in Your LDAP User Profile".
4.
J.1.1.1 Installing
Download and install JXplorer from http://www.jxplorer.org.
J.1.1.2 Connecting
1.
2.
Click the domain name link > Security > Embedded LDAP.
Click Save.
Table J1
Field
Value
Host
Port
Protocol
LDAP v3
Security Level
User + Password
User DN
cn=Admin
Password
password
Expand the LDAP tree as follows: domain > myrealm > people > weblogic.
2.
3.
4.
5.
Click Submit.
Note:
J-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Readme.txt.
Release notes
Note:
1.
2.
Create a new application by selecting File > New > General > Applications >
SOA Application. Click OK.
3.
4.
Enter the name for the project and click Next (Figure J2).
5.
Select the Composite With BPEL Process composite template (Figure J3). Click
Finish.
6.
In the Create BPEL Process dialog, enter the BPEL process name as SendMessage
(Figure J4). Click OK.
7.
J-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
8.
You have now created an empty and default BPEL application (Figure J5).
In the Oracle JDeveloper main window you can view the following components of
the application under the Composite.xml tab.
The left box is the definition of a web service client that is used to initiate an
application.
The middle box is a BPEL process that creates and formats the message and
calls the messaging service.
You later create the messaging service resource that is used to
send the message when you create the User Notification BPEL process
(steps 13 - 19).
Note:
9.
Expand the xsd folder in the Application Navigator and open SendMessage.xsd
by double-clicking it.
11. Perform the following modifications to the inputs of this BPEL application:
This XSD element defines the input for the BPEL process.
Select the Source tab (Figure J6), and replace the line above with the following
three lines:
<element name="to" type="string"/>
<element name="subject" type="string"/>
<element name="body" type="string"/>
Figure J6 Modifying the Inputs in the SendMessage.xsd File
J-6 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
14. To enable messaging in this process, drag and drop User Notification from Oracle
15. Click the XPath Expression Builder icon to the right of the To: input box.
16. Modify the expression for the To recipient, as follows:
Click OK.
17. Click the XPath Expression Builder icon to the right of the subject: input box.
18. Modify the expression for the subject as follows:
J-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Click OK.
19. Click the XPath Expression Builder icon to the right of the Notification Message:
input box.
20. Modify the expression for the notification message as follows:
Click OK.
The changes to the inputs are saved and the configuration of the User
Notification Activity is complete. You can now see the User Notification
activity in the BPEL application (Figure J14). The SOA Composite is
complete.
Figure J14 User Notification Activity After Configuration of Inputs
J-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
Specify a name for the connection in the Connection Name field (for example,
SOA_managed_server as shown in Figure J16).
3.
4.
5.
In the Connection dialog, enter the hostname, port and SSL port for the SOA
admin server, and enter the name of the domain for the Oracle WebLogic Server
Domain.
6.
Click Next.
7.
8.
1.
2.
3.
4.
5.
Select an existing connection to an application server from the list (for example,
select the connection SOA_managed_server that was created as described in
Section J.2.3, "Creating a New Application Server Connection").
6.
Click Finish.
7.
8.
Verify that the message Deployment Finished appears in the deployment log
(Figure J17).
Note:
J-12 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Directly at http://server:port/sdpmessaging/userprefs-ui
Through the Worklist applications Preferences > Notification tab at:
http://server:port/integration/worklistapp
4.
Set a channel as the default by expanding the device folder, and then clicking Set
as Default adjacent to the selected channel.
A check mark appears next to the selected channel, designating it as the default
means of receiving notifications. All messages sent to that user are sent to that
channel.
Open a web browser window and login to Oracle Enterprise Manager for the SOA
domain. For example, http://host:port/em.
2.
In Enterprise Manager, expand the SOA folder in the navigation tree, and click the
deployed SendMessageProj composite application. Click the Test button to
launch the test client page.
Oracle User Messaging Service Applications J-13
3.
In the Input Arguments section provide the input values for invoking
SendMessageProj.
Enter the following values:
4.
Note:
J-14 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Readme.txt.
Release notes
The left box is the definition of a web service client that is used to initiate an
application.
The middle box is a BPEL process that creates and formats the message and
calls the messaging service.
The right box is the messaging service resource that is used to send the
message.
2.
3.
Deploy the project by following the instructions in Section J.2.4, "Deploying the
Project".
4.
5.
Verify that the message Deployment Finished appears in the deployment log.
You have successfully deployed the application.
Before you can run the sample you must configure any additional drivers in
Oracle User Messaging Service and configure a default device for the user
receiving the message in User Messaging Preferences, as described in the
following sections.
Refer to Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite for more
information.
Note:
Open a web browser window and log in to Oracle Enterprise Manager for the
SOA domain. For example, http://host:port/em.
J-16 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
In Enterprise Manager, expand the SOA folder in the navigation tree, and click the
deployed SendEmailWithAttachmentsProj composite application. Click the Test
button to launch the test client page.
3.
In the Input Arguments section provide the input values for invoking
SendEmailWithAttachmentsProj.
Enter the following values:
To send text files such as HTML, XML, or plain text files, the following values
can be used for the attachmentMimeType entry:
Note:
4.
attachmentURI: the URL from where the SOA server downloads the file
2.
3.
4.
Enter the name for the project and click Next (Figure J22).
5.
Select the Composite With BPEL Process composite template (Figure J23). Click
Finish.
6.
In the Create BPEL Process dialog, enter the BPEL process name as
SendEmailWithAttachments (Figure J24). Click OK.
J-18 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
7.
8.
The left box is the definition of a web service client that is used to initiate an
application.
The middle box is a BPEL process that creates and formats the message and
calls the messaging service.
You later create the messaging service resource that is used to
send the message when you create the User Notification BPEL process
(steps 13-19).
Note:
9.
11. Perform the following modifications to the inputs of this BPEL application:
Select the Source tab, and replace the lines above with the following:
<element name="process">
<complexType>
<sequence>
<element name="to" type="string"/>
<element name="subject" type="string"/>
<element name="body" type="string"/>
<element name="attachmentName" type="string"/>
<element name="attachmentMimeType" type="string"/>
<element name="attachmentURI" type="string"/>
</sequence>
</complexType>
</element>
This xsd element defines the input for the BPEL process.
12. Save the project.
13. Select the SendEmailWithAttachments.bpel editor screen.
14. Drag and drop an Email activity from Oracle Extensions located in the
J-20 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
15. In the Edit Email window, leave the From account as Default.
Figure J27 Edit Email Window
16. To create the expression for To, select the XPath Expression Builder and perform
Under BPEL variables select Variables > Process > Variables >inputVariable
> payload > client:process > client:to.
Click OK.
This expression (as shown in Figure J28) takes the data from the web service and
maps it to the business email of the local SOA user.
Figure J28 Expression Builder for the To Path
J-22 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
bpws:getVariableData('inputVariable','payload','/client:process/client:body')
21. In the Edit Email dialog (Figure J29), select the Attachments tab and use the add
22. To create the expression for Name element of the attachment, click the Browse
button near the Name field to open the XPath Expression Builder and perform the
following steps:
a.
Select getVariableData from BPEL Extension Functions and click Insert Into
Expression.
b.
Under BPEL variables select Variables > Process > Variables >inputVariable
> payload > client:process > client:attachmentName.
c.
Click Insert Into Expression. Ensure that the parentheses are matched.
d.
Click OK.
Browse button near the Name field to open the XPath Expression Builder and
perform the following steps:
a.
Select getVariableData from BPEL Extension Functions and click Insert Into
Expression.
b.
Under BPEL variables select Variables > Process > Variables >inputVariable
> payload > client:process > client:attachmentMimeType.
c.
Click Insert into Expression. Ensure that the parentheses are matched.
d.
Click OK.
button near the Name field to open the XPath Expression Builder and perform the
following steps:
a.
Select readFile from BPEL XPath Extension Functions and click Insert Into
Expression.
b.
Under BPEL variables select Variables > Process > Variables >inputVariable
> payload > client:process > client:attachmentURI.
c.
Click Insert into Expression. Ensure that the parentheses are matched.
d.
Click OK.
The BPEL fragment with an assign activity with multiple copy rules is generated. One
of the copy rules copies the attachment.
To view the default copy rules that were generated, and create new copy rules to
transform the data, perform the following:
1.
Expand the Email node by selecting the plus sign icon (Figure J30).
J-24 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
2.
2.
Add the following to the appropriate Body Part in the multipart content (look for
correct <BodyPart> tag within the <MultiPart>):
<ContentEncoding
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
J-26 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
</BodyPart>
<BodyPart xmlns="http://xmlns.oracle.com/ias/pcbpel/
NotificationService">
<MimeType xmlns="http://xmlns.oracle.com/ias/pcbpel/
NotificationService"/>
<ContentBody xmlns="http://xmlns.oracle.com/ias/pcbpel/
NotificationService"/>
<BodyPartName xmlns="http://xmlns.oracle.com/ias/pcbpel/
NotificationService"/>
<ContentEncoding xmlns="http://xmlns.oracle.com/ias/pcbpel/
NotificationService"/>
</BodyPart>
</MultiPart>
</ContentBody>
</Content
3.
To send the text with base64 encoding, add the following <copy> element:
<copy>
<from expression="string('base64')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/
ns1:ContentEncoding"/>
</copy>
4.
You can now deploy and run the application as described in Section J.3.2, "Running the
Pre-Built Sample."
J-28 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
K
Oracle SOA Suite Properties Road Map
This appendix describes Oracle SOA Suite design time and runtime configuration
properties and provides references to documentation that describes how to configure
these properties.
This appendix includes the following sections:
Property Name
Description
completionPersistPolicy
disableAsserts
globalTxMaxRetry
globalTxRetryInterval
inMemoryOptimization
reenableAggregationOnCo
mplete
The number of instances to create and use to route messages in a BPEL process.
keepGlobalVariables
Whether the server can keep global variable values in the instance store when
the instance completes,
oneWayDeliveryPolicy
sensorActionLocation
Description
sensorLocation
transaction
idempotent
nonBlockingInvoke
validateXML
Oracle B2B
K.2.2 Oracle BPEL Process Manager and Oracle Web Services Addressing Message
Header Properties
Oracle BPEL Process Manager and Oracle Web Services Addressing rely extensively on
header support to solve customers integration needs.
K-2 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about available Oracle BPEL Process Manager and Oracle Web
Services Addressing message header properties, see Appendix H, "Normalized
Message Properties."
Property
Description
See...
endpointURI
oracle.composite.f
aultPolicyFile
oracle.composite.f
aultBindingFile
passThroughHeader
rolesAllowed
streamIncomingAtta
chments
and
streamOutgoingAtta
chments
Description
See...
oracle.webservices
.local.optimizatio
n
oracle.soa.local.o
ptimization.force
one.way.returns.fa
ult
mtomThreshold
Property
Description
See...
retryInterval
retryCount
Retries an activity a
specified number of times.
You can also enter adapter rejected message properties in the fault policy framework
file during design time.
For more information, see Section "Error Handling" of Oracle Fusion Middleware User's
Guide for Technology Adapters.
K-4 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
SOA Infrastructure
Oracle Mediator
Cross references
Oracle B2B
Service and reference binding components (JCA adapters, web services, and
Oracle Service Registry)
Audit level
Payload validation
For more information about available SOA Infrastructure properties, see Chapter
"Configuring the SOA Infrastructure" of Oracle Fusion Middleware Administrator's Guide
for Oracle SOA Suite and Oracle Business Process Management Suite.
Dispatcher threads
For more information about available Oracle BPEL Process Manager properties, see
Chapter "Configuring BPEL Process Service Components and Engines" of Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
The workflow session time out and custom class path URL values
The dynamic assignment and task escalation functions of the assignment service
For more information about available human workflow notification and task service
properties, see Chapter "Configuring Human Workflow Service Components and
Engines" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and
Oracle Business Process Management Suite.
Resequencer locker thread sleep, maximum groups locked, and worker threads
For more information about available Oracle Mediator properties, see Chapter
"Configuring Oracle Mediator Service Components and Engines" of Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
For more information about available cross reference properties, see Chapter
"Managing Cross-References" of Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
For more information about available service and reference binding component
properties, see Chapter "Configuring Service and Reference Binding Components" of
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
SOA Infrastructure
Oracle Mediator
Note:
MBean Browser properties for the SOA Infrastructure. Properties that display for
modifying include, but are not limited to, the following:
The HTTP protocol URL published as part of the SOAP address of a process in the
WSDL file
The HTTPS protocol URL published as part of the SOAP address of a process in
the WSDL file
For more information about available SOA Infrastructure System MBean Browser
properties, see Chapter "Configuring the SOA Infrastructure" of Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
The extra BPEL class path to include when compiling BPEL-generated Java
sources
The maximum number of times a failed expiration call (wait/onAlarm) is retried
before failing
The delay between expiration retries
The size of the block of instance IDs to allocate from the dehydration store during
each fetch
The maximum time a request and response operation takes before timing out
For more information about available Oracle BPEL Process Manager System MBean
Browser properties, see Chapter "Configuring BPEL Process Service Components and
Engines" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and
Oracle Business Process Management Suite.
K-8 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
For more information about available human workflow notification and task service
System MBean Browser properties, see Chapter "Configuring Human Workflow
Service Components and Engines" of Oracle Fusion Middleware Administrator's Guide for
Oracle SOA Suite and Oracle Business Process Management Suite.
K-10 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
Index
A
abs function
description, B-8
access points, 63-6, 64-8, 65-10
access policies
on task content, 29-69
accessibility options
Oracle BPM Worklist, 1-10
Oracle SOA Composer, 1-10
action types, 29-49
actionable emails, 34-33
not sent during runtime when digital signatures
are enabled, 34-33
activities
Annotations tab, A-4
assert, A-11
Assertions tab, 12-60, A-5
assign, A-8
bind entity, A-11
bypassing execution of, 11-12
compensate, A-12
compensateScope, A-13
copying and pasting between BPEL projects, A-6
copying and pasting in the same BPEL
project, A-6
Correlations tab, A-5
create entity, A-14
definition, 4-10
dehydrate, A-14
Documentation tab, A-5
email, A-15
empty, A-16
exit, A-17
flow, A-17
flowN, A-18
forEach, A-19
Headers tab, A-5
if, A-20
IM, A-21
invoke, A-21
Java embedding, A-22
overview, 4-10, A-2
partner link, A-23
phase, A-24
pick, A-25
Index-1
addQuotes function
description, B-15
ADF bindings
files for, 54-5
using to invoke a composite from a JSP/Java
class, 37-15
ADF bindings filter, 35-2
ADF Model layer, introduced, 54-1
ADF task flow for human tasks, 30-3
ADF, using Oracle BAM, 54-4
ADF-BC services
binding component, 2-11, 2-19
definition, 37-13
adfBindings bindings filter, 35-2
adf-desktop-integration.jar, 35-2
adfdiExcelDownload download filter, 35-3
adfdiRemote servlet, 35-3
ADFLibraryFilter filter, 35-3
admin.server.host parameter, 3-22
admin.server.port parameter, 3-23
advanced formatting, message sources, 56-10
aggregate functions in calculations, 55-5
alerts
history, 60-10
Oracle BAM
about, 60-1
actions, F-5
activating, 60-4
activity, 60-10
administrative role users, 60-2, 60-5
conditions, F-5
creating, 60-3
dependencies, 60-9
events, F-1
frequency constraint, F-14
history, 60-10
messages, 60-8
parameterized, F-7
templates, 60-7
web services, 60-11
alidateFodConfigSettings ant script, 3-23
Annotations tab
in activities, A-4
ant scripts
activating all composites in a partition, 43-61
activating an application, 43-55
assigning the default version to a SOA composite
application, 43-56
compile-deploy-all, 3-24
compiling a SOA composite application, 43-45
creating a partition in the SOA
Infrastructure, 43-58
deleting a partition, 43-59
deploying a SOA composite application, 43-47
executing a test case, 43-44
exporting a SOA composite application into a SAR
file, 43-49
exporting postdeployment changes of a composite
into a JAR file, 43-50
exporting shared data of a given pattern into a JAR
Index-2
file, 43-52
listing all available partitions in the SOA
Infrastructure, 43-57
listing all composites in a partition, 43-58
listing the deployed SOA composite
applications, 43-57
managing composites, 43-43
packaging a SOA composite application into a
composite SAR file, 43-46
removing a top-level shared data folder, 43-53
retiring all composites in a partition, 43-61
retiring an application, 43-56
seedBAMServerObjects, 3-24
seedDemoUsers, 3-24
seedFodJmsResources, 3-24
server-setup-seed-deploy-test, 3-24
starting all composites in a partition, 43-60
starting an application, 43-54, 43-55, 43-56, 43-57
stopping all composites in a partition, 43-60
stopping an application, 43-54
undeploying a SOA composite application, 43-48
validateFodConfigSettings, 3-23
appendToList function
description, B-17
Application Navigator
location of in Oracle JDeveloper, 4-8
application roles
definition, 27-5
application template, 35-2
AQ adapter
definition, 37-10
arrays
in transformations, 40-28
manipulating, 6-47
maxOccurs attribute, 6-47
SOAP-encoded arrays, 6-48
statically indexing into, 6-47
AspectJ classes
configuring with the spring service
component, 52-31
assert activity
capabilities, A-11
assertion conditions
creating, 12-60
disabling, 12-63
expressions not evaluating to an XML schema
boolean type throw a fault, 12-59
log events in the instance audit trail, 12-59
multiple, 12-57
throwing faults, 12-53
use of built-in and custom XPath functions and
$variable references, 12-58
assertion tests
overview, 44-2
assertions
creating value asserts, 44-18
in composite test suites, 44-4
Assertions tab
creating assertion conditions, 12-60
in activities, A-5
assign activity
adding to an asynchronous service, 8-6
assigning a literal or XML fragment to a target
node, A-9
bpelx extensions in BPEL 1.1, 6-24
bpelx extensions in BPEL 2.0, 6-24
capabilities, A-8
changing copy rules to bpelx extension
types, A-9
copying data, 6-14, A-8
creating a bpelx:rename extension rule on a target
node, A-9
creating an XPath expression on a target
node, A-8
description, 6-3
for data manipulation, 6-2, A-8
formatting the email message body as
HTML, 17-9
in asynchronous services, 8-6
limitations on passing large schemas, 6-5
recasting a target node, A-9
renaming a target node, A-9
selecting an extension type in BPEL 1.1, A-9
selecting an extension type in BPEL 2.0, A-9
selecting the ignoreMissingFromData
attribute, A-10
selecting the insertMissingToData attribute, A-10
selecting the keepSrcElementName
attribute, A-10
splitting into two activities, A-11
using multiple bpelx:append settings, A-11
using the Copy Rules tab, 6-23, A-8
assign extension attributes
ignoreMissingFromData, 6-36
insertMissingToData, 6-36
keepSrcElementName, 6-36
using, 6-36
assignment service
configuration, 34-37
deploying a custom assignment service, 34-45
dynamic assignment functions, 34-38, 34-39,
34-40, 34-41
dynamically assigning task participants, 34-42
example of implementation, 34-43
implementing, 34-43
asynchronous interaction with a notification timer
BPEL process as the client, 5-6
BPEL process as the service, 5-6
definition, 5-5
asynchronous interaction with a timeout
BPEL process as the client, 5-5
BPEL process as the service, 5-5
definition, 5-4
asynchronous interactions
BPEL process as the client, 5-4
BPEL process as the service, 5-4
definition, 5-3
returning faults, 12-35
asynchronous processes
dehydration store, 8-9
asynchronous services
assign activities, 8-6
calling, 8-2
correlation IDs, 8-8
invoke activities, 8-3, 8-8
parallel flows, 10-1
partner links, 8-2, 8-7
receive activities, 8-5, 8-8
WS-Addressing, 8-8
attachments
adding MTOM attachments to web
services, 45-10
attaching a URL file, 32-35
in end-to-end streaming, 45-3
in SOAP, 45-3
MIME, 45-4
optimization enabled, 45-7
options for file and FTP adapters, 45-9
Oracle B2B, 45-10
performance overhead and pass through
attachments, 45-6
properties for streaming attachments, 45-7
reading and encoding SOAP attachment
content, 45-7
sending streaming attachments, 45-7
sending with the notification wizard, 17-7
sharing attachments using synchronous
flows, 45-8
streaming, 45-4
task attachments with email notifications, 34-35
transforming attachments with the
ora:doStreamingTranslate XPath
function, 45-9
using WordML style sheets, 29-56
writing attachments using an outbound file
adapter, 45-9
attribute labels
internationalization, 34-19
attributes
manipulating, 6-22
audit level
setting, 45-14
authenticate function
description, B-16
auto mapping
in transformations, 40-31
with confirmation in transformations, 40-33
automated testing
of BPEL process service components, 44-1, 44-23
of SOA composite applications, 2-30, 44-1
B
B2BSee Oracle B2B
B2BX12OrderGateway project, 3-7
bam.server.host parameter, 3-21
bam.server.password parameter, 3-22
bam.server.port parameter, 3-21
bam.username parameter, 3-22
batching
Index-3
Index-4
using, 6-25
bpelx:assert extension
expressions not evaluating to an XML schema
boolean type throw a fault, 12-59
multiple assertions, 12-57
throwing faults based on a condition, 12-55
use of built-in and custom XPath functions and
$variable references, 12-58
use of faultName and message attributes, 12-57
bpelx:conversationId extension, 8-11
bpelx:copyList extension
changing a copy rule to, A-9
copying a node list or a node, B-18
description, 6-33
using, 6-34, 6-35
bpelx:dehydrate name extension
description, A-14
bpelx:detailLabel extension, 16-5
bpelx:eventName extension
routing events to the same instance, 9-16
bpelx:exec extension, 14-2, 14-8
built-in methods, 14-4
embedding SDOs, 14-8
bpelx:flowN extension, 10-15
bpelx:for extension, 15-8
bpelx:fromProperties extension, H-6
bpelx:gnoreMissingFromData extension
using, 6-36
bpelx:headerVariable extension, 6-56
description, 6-56
bpelx:inputProperty extension, H-5
bpelx:insertAfter extension
changing a copy rule to, A-9
description, 6-27
using, 6-28, 6-29
bpelx:insertBefore extension
changing a copy rule to, A-9
description, 6-26
using, 6-26, 6-27
bpelx:insertMissingToData extension
using, 6-36
bpelx:invokeAsDetail extension, 16-4
bpelx:outputProperty extension, H-5
bpelx:postAssert extension, 12-54
bpelx:preAssert extension, 12-55
bpelx:receiveSignal extension, 16-5
bpelx:remove extension
creating, A-9
description, 6-29
using, 6-30, 6-31
bpelx:rename extension
adding, A-9
description, 6-31
using, 6-31, 6-33
bpelx:rollback extension, 13-3
bpelx:sdoCapable extension
declaring SDO-based variables, 6-11
bpelx:signal extension, 16-4
bpelx:skipCondition extension
bypassing activity execution, 11-12
Index-5
Index-6
C
calculated fields, 55-5
calculations
aggregate functions, 55-5
datetime functions, 55-5
expressions, 55-5
string functions, 55-5
callback classes
specifying business events, 29-78
specifying on task status, 29-76
callbacks
class loading, 34-46
task routing and customization in BPEL
callbacks, 29-80
using with spring, 52-5
viewing, 28-15
case sensitivity
human workflow, 34-50
in group names, 29-8
catch branch
creating, 12-42, A-33
definition, 12-40
fault handling, 12-35
catchAll branch
definition, 12-40
channels
deleting a channel does not remove an integrated
partner link, 17-4
email, 17-4
IM, 17-9
SMS, 17-10
voice mail, 17-12
character set encoding
changing, 29-67
chunking
with the file and FTP adapters, 45-13
class paths
for clients using remote Enterprise
JavaBeans, 33-6
for clients using SOAP, 33-6
clearing data objects, 55-18
clearTaskAssignees function
description, B-57
compare function
description, B-9
compare-ignore-case function
description, B-9
compensate activity
capabilities, A-12
definition, 12-48
fault handling, 12-48
compensateScope activity
capabilities, A-13
only supported in BPEL 2.0 projects, A-13
using, 12-50
compilation
increasing memory to recover from errors, 43-70
compile-deploy-all ant script, 3-24
completionPersistPolicy property
description, C-2
complex structures
processing large XML documents, 45-13
complex type
variables, 6-15
Component Palette
introduction, 2-5
location of in Oracle JDeveloper, 4-8
componentType file
definition, 2-4
composite sensors
adding, 50-2
adding a property, 50-9
adding a variable, 50-8
adding an expression, 50-9
adding to binding components, 50-2
adding to service components that subscribe to
business events, 50-2
definition, 50-1
monitoring during runtime, 50-12
restrictions on use, 50-2
composite test
assertions overview, 44-2
BPEL process testing, 44-23
creating test suites, 44-5
creating value asserts, 44-18
definition, 44-1
deploying test suites, 44-31
emulating inbound messages, 44-9
emulations overview, 44-2
naming limitations on test suites and test
cases, 44-5
test case overview, 44-1
test suite assertions, 44-4
test suite components, 44-3
test suite emulations, 44-3
test suites overview, 44-2
test suites process initiation, 44-3
XML assert, 44-2
composite.xml file
definition, 2-4, 2-6
deployment descriptors, C-4, C-6
opening through a SOA-MDS connection, 43-8
registering sensors and sensor actions, 18-14
concat function
description, 6-20
conditional branching logic
definition, 11-1
use of XPath expressions, 11-1
using switch activities, 11-2
using while activities, 11-8
conditional processing
with xsl choose, 40-27
with xsl if, 40-26
configuration plans
cannot edit XSLT artifacts, 43-9
creating, 43-12
creating with the WLST utility, 43-15
definition, 43-9
use cases, 43-11
configuration properties
Index-7
Index-8
D
data control, Oracle BAM
about, 54-1
aggregates, 54-16
calculated fields, 54-9
creating, 54-4
field selection, sorting, 54-11
filters, 54-12
flat query, 54-6
group query, 54-6
groups, 54-15
parameters, 54-7
query type, 54-5
time groups, 54-15
data controls
creating, 54-4
displayed on the Data Controls panel, 54-5
Data Controls panel
icons defined, 54-5
using to create a user interface, 54-5
data manipulation
accessing fields with complex type variables, 6-15
assigning boolean values, 6-20
assigning date or time, 6-21
assigning literal strings, 6-19
assigning numeric values, 6-18
concatenating strings, 6-20
converting from a string to a structured XML
object type, 6-54
copying data between variables, 6-14
dynamically indexing into a data sequence, 6-51
generating array-equivalent functionality with the
genEmptyElem function, 6-53
initializing variables, 6-13
manipulating arrays, 6-47
manipulating attributes, 6-22
mathematical calculations with XPath
functions, 6-19
statically indexing into a data sequence, 6-47
with assign activities, 6-2, 6-14
with XQuery and XSLT, 6-5
data objects
about, 55-1
adding dimensions, 55-15
calculated column, 55-5
clearing contents, 55-18
contents, 55-9
creating folders, 55-10
datetime column, 55-6
defining, 55-2
deleting, 55-18
dimensions, 55-15
general information, 55-8
indexes, 55-17
layout, 55-9
lookup column, 55-4
moving, 55-17
Oracle Data Integrator, 55-6
organizing, 55-10
permissions, 55-6
folders, 55-11
renaming, 55-17
security filters, 55-13
system, 55-6
viewing, 55-8
data sequences
determining the size, 6-51
dynamically indexing into, 6-51
database
sensor publish type, 18-3
database adapter
definition, 37-10
database views
human workflow, 34-62
DataObjectDefinition web service, 59-3
DataObjectOperations web service, 59-2
date time stamp field, 55-6
dates
assigning, 6-21
datetime functions in calculations, 55-5
day-from-dateTime function
description, B-5
db.adminUser parameter, 3-15
db.demoUser.tablespace parameter, 3-15
debatching
debatching with the file and FTP adapters, 45-12
declarative components
definition, 26-1
using, 26-2
using the business rules dictionary editor
declarative component, 26-28
defining a fault handler, 12-30
dehydrate activity
capabilities, A-14
dehydration store, 8-9
definition, 8-9
deleting cross reference table value, 49-22
xref
markForDelete function, 49-22
deleting data objects, 55-18
deleting folders, 55-12
deployment
anatomy of a composite, 43-3
common configuration plan issues to
check, 43-68
common deployment issues to check, 43-66
creating an application server connection, 43-16
customizing your application for the target
environment, 43-8
in a partition, 43-26
invoking other deployed composites, 2-26
managing deployed composites, 2-27
of a single composite, 43-16
of a task flow, 43-24
of an existing archive, 43-41
of multiple composites, 43-29
of shared metadata across composites, 43-31
of SOA composite applications, 2-26, 2-29
packaging of artifact files, 43-2
postdeployment configuration, 43-63
Index-9
description, C-2
doc function
description, B-19
Documentation tab
in activities, A-5
only available in BPEL 2.0 projects, A-5
domain value maps
add columns, 47-7
add rows, 47-9
cannot be tested during design time in XSLT
Mapper, 40-49
committing changes at runtime with the SOA
Composer, 48-6
creation, 47-4
dvm
lookupValue function, 47-10
lookupValue1M function, 47-11
editing, 47-7
editing at runtime with the SOA Composer, 48-1,
48-4
features, 47-2
one-to-many mapping, 47-4
qualifier order, 47-3
qualifiers, 47-2
one-to-many mapping, 47-4
qualifier order, 47-3
qualifiers, 47-2
saving at runtime with the SOA Composer, 48-5
using, 47-10
using in a transformation, 47-12
using lookupValue functions, 47-14
viewing at runtime with the SOA Composer, 48-3
domain value maps functions
dvm
lookupValue, 47-10
lookupValue1M, 47-11
domain value maps qualifiers, 47-2
download filter, 35-3
durable subscriptions
not supported by the Event Delivery
Network, 41-3
dvm
lookupValue function, 47-10
lookupValue1M function, 47-11
dynamic assignment functions
configuring, 34-40
configuring display names, 34-41
definition, 34-38
implementing, 34-39
dynamic partner links
using, 8-14
dynamic routing decision table
using with two-layer business process
management, 51-6
E
EclipseLink O/X Mapper (OXM)
See OXM
edit domain value maps
Index-10
creating, 58-2
Oracle Data Integrator, 58-2
external routing
routing policy, 29-52
ExternalLegacyPartnerSupplier project, 3-7
F
facets
in the task display form, 30-12
fact types, 29-48
fault bindings, 22-9
fault handling, 12-30
creating, 12-1, 12-30
definition, 12-1
EMS payload error configuration, 56-11
fault policy, 12-12
importing RuntimeFault.wsdl, 12-30
modifying the WSDL files, 12-30
order of precedence in BPEL 2.0, 12-4
returning external faults, 12-35
specifying an assertion condition, 12-53
throwing internal faults, 12-31
using catch branches, 12-35
using compensate activities, 12-48
using empty activities, 12-45
using scope activities, 12-35
using terminate activities, 12-51
using the getFaultAsString function, 12-31
using throw activities, 12-31
fault management framework
associating a fault policy with a fault policy
binding, 12-18
definition, 12-12
designing, 12-13
executing a fault policy, 12-22
using a Java action fault policy, 12-23
fault policy, 22-1
actions, 22-4
associating with a fault policy binding, 12-18
component level, 22-9
composite level, 22-9
conditions, 22-2
definition, 12-12
designing, 12-13
executing, 12-22
in defining in Oracle BPM Suite, 12-27
using a Java action fault policy, 12-23
fault policy bindings
sample file, 12-22
fault sensors
definition, 18-2
fault-bindings.xml, 22-17
fault policy bindings file, 12-13
fault-policies.xml, 22-12
fault policy file, 12-13
faults
categories of faults in BPEL, 12-5
handling and propagating system faults in a
synchronous BPEL process, 12-6
Index-11
Index-12
FTP adapter
chunking, 45-13
debatching, 45-12
definition, 37-11
streaming, 45-13
functions
abs, B-8
add-dayTimeDuration-to-dateTime, B-3
addQuotes, B-15
advanced, B-51
appendToList, B-17
authenticate, B-16
batchProcessActive, B-43
batchProcessCompleted, B-43
BPEL XPath extension, B-15
chaining in transformations, 40-20
clearTaskAssignees, B-57
compare, B-9
compare-ignore-case, B-9
concat, 6-20
copyList, B-18
countNodes, B-18
create-delimited-string, B-10
create-nodeset-from-delimited-string, B-51
createWordMLDocument, B-57
creating user-defined XPath extension
functions, B-73
current-date, B-4
current-dateTime, B-4
current-time, B-5
day-from-dateTime, B-5
descriptions, 40-19
doc, B-19
dynamically setting email addresses and telephone
numbers, 17-12
editing in transformations, 40-20
editing XPath expressions in
transformations, 40-24
ends-with, B-10
examples, 6-4
format, B-43
formatDate, B-22
format-dateTime, B-5
format-string, B-11
functions prefixed with xp20 or orcl, 40-19
genEmptyElem, 6-53, B-44
generateGUID, B-22
generate-guid, B-52
getChildElement, B-44
getContentAsString, B-25
get-content-as-string, B-11
getConversationId, B-25
getCreator, B-25
getCurrentDate, 6-21, B-25
getCurrentDateTime, 6-21, B-26
getCurrentTime, 6-21, B-26
getDefaultRealmName, B-62
getDomain is deprecated, B-15
getElement, B-27
getFaultAsString, 12-31
getGroupIdsFromGroupAlias, B-28
getGroupProperty, B-62
getInstanceId, B-28
getLinkStatus, B-41
get-localized-string, B-12
getManager, B-62
getMessage, B-45
getNodes, B-28
getNodeValue, B-28
getNotificationProperty, B-57
getNumberOfTaskApprovals, B-58
getPreference, B-29
getPreviousTaskApprover, B-58
getProcessId, B-30
getProcessOwnerId, B-30
getProcessURL, B-30
getProcessVersion, B-30
getReportees, B-63
getTaskAttachmentByIndex, B-58
getTaskAttachmentByName, B-59
getTaskAttachmentContents, B-59
getTaskAttachmentsCount, B-59
getTaskResourceBindingString, B-60
getUserAliasId, B-31
getUserProperty, 17-13, B-63
getUserRoles, B-64
getUsersInGroup, B-64
getVariableData, 17-13, B-41
getVariableProperty, B-42
hours-from-dateTime, B-6
implicit-timezone, B-6
in transformations, 40-19
index-within-string, B-12
integer, B-32
isUserInRole, B-65
last-index-within-string, B-13
left-trim, B-13
listUsers, B-32
location of function descriptions, 6-5
lookupGroup, B-65
lookup-table, B-1
lookupUser, B-33, B-65
lookup-xml, B-55
lower-case, B-14
matches, B-14
max-value-among-nodeset, B-45
mediator XPath extension, B-46
minutes-from-dateTime, B-6
min-value-among-nodeset, B-45
month-from-dateTime, B-7
parseEscapedXML, 6-54, B-33
position, 6-47
prefixed with xp20 or orcl, 40-19
processXQuery, B-34
processXSLT, 17-9, B-34
processXSLTAttachment is deprecated, B-15
processXSQL is deprecated, B-15
query-database, B-2
readBinaryFromFile, B-38, B-51
readFile, B-38
right-trim, B-14
search, B-39
seconds-from-dateTime, B-7
selecting an data sequence element, 6-47
sequence-next-val, B-3
SOA XPath extension, B-1
square-root, B-46
subtract-dayTimeDuration-from-dateTime, B-7
timezone-from-dateTime, B-8
upper-case, B-15
using double slashes for directory paths on
Windows can cause errors, B-72
wfDynamicGroupAssign, B-60
wfDynamicUserAssign, B-61
workflow service, B-57
writeBinaryToFile, B-40
year-from-dateTime, B-8
Fusion Order Demo
deploying, 3-12
deploying in a partition, 3-23
installing schema, 3-15
integration with spring, 52-22
introduction, 3-1
running, 3-24
setting up, 3-3
Store Front module, 3-1
WebLogic Fusion Order Demo, 3-2
introduction, 3-2
Fusion Web Application (ADF) application
template, 35-2
FusionOrderDemo_R1PS5.zip, 3-3
FYI assignee
configuring, 29-40
definition, 27-5, 29-40
must first claim an FYI task before dismissing
it, 30-20
tasks are not actionable, 29-68
workflow participant type, 27-5, 29-40
G
genEmptyElem function
description, 6-53, B-44
generateGUID function
description, B-22
generate-guid function
description, B-52
getChildElement function
description, B-44
getContentAsString function
description, B-25
get-content-as-string function
description, B-11
getConversationId function
description, B-25
getCreator function
description, B-25
getCurrentDate function
description, 6-21, B-25
getCurrentDateTime function
Index-13
Index-14
description, B-63
example, 17-13
getUserRoles function
description, B-64
getUsersInGroup function
description, B-64
getVariableData function
description, 6-20, B-41
example, 17-13
throws selectionFailure if result node set size is
greater than one, B-42
using in mathematical calculations, 6-19
getVariableProperty function
description, B-42
global task variable name
specifying in human task activities, 28-12
global variables
in transformations, 40-38
globalTxMaxRetry property
description, C-2
globalTxRetryInterval property
description, C-2
governance
Oracle Enterprise Repository, A-53
Groovy classes
configuring with the spring service
component, 52-31
group names
case sensitive by default, 29-8
group vote
configuring, 29-33
consensus percentage, 29-35
immediately triggering a voted outcome when a
minimum percentage is met, 29-36
specifying group voting details, 29-35
waiting until all votes are in before triggering an
outcome, 29-36
H
headers
normalized message header properties, H-1
SOAP headers, 6-56
Headers tab
in activities, A-5
Healthcare See Oracle Healthcare
heap size
increasing, 40-50, 45-14
History window
location of in Oracle JDeveloper, 4-9
hours-from-dateTime function
description, B-6
HTTP binding
binding component, 2-11, 2-19
configuring with the HTTP Binding Wizard, 37-8
creating your own schema, 37-9
enabling basic authentication, 37-9
in SOA composite applications, 37-5
limitations in SOA composite applications, 37-6
support for HTTPS in inbound and outbound
directions, 37-8
supported inbound and outbound
interactions, 37-6
supported operation types, 37-8
supported XSD types, 37-6
unsupported HTTP headers, 37-7
HTTP headers
unsupported, 37-7
human task
service component, 2-7
human task activity
associating with a BPEL process, 28-7
identification key, 28-13
including the task history of other tasks, 28-13
scope name and global task variable name, 28-12
specifying a task initiator and task priority, 28-10
specifying a task title, 28-9
specifying task parameters, 28-10
task owner, 28-13
viewing BPEL callbacks, 28-15
human task definition
associating with a BPEL process, 28-2
Human Task Editor
abruptly completing a condition, 29-45
accessing the sections of, 29-2
actionable emails, 34-33
allowing all participants to invite other
participants, 29-44
assigning task participants by name or
expression, 29-25, 29-55
bypassing task participants, 29-33, 29-37, 29-40
changing character set encoding, 29-67
configuring the error assignee, 29-54
creating a human task, 28-3
customizing notification headers, 29-69
editing notification messages, 29-66
escalate after policy, 29-60
escalating, renewing, or ending a task, 29-58
escalation and expiration policy overview, 29-58,
29-59
escalation rules, 29-61
expire after policy, 29-59
FYI assignee task participant, 29-40
group voting details, 29-35
inviting additional task participants, 29-33, 29-37,
29-40
making email messages actionable, 29-68
multilingual settings, 29-57, 34-32
never expire policy, 29-59
notification preferences, 29-63
notifying recipients of changes to task
status, 29-64
parallel task participant, 29-33
renew after policy, 29-60
securing notifications, 29-67, 34-35
sending email notifications to groups and
application roles, 29-68
sending task attachments with email
notifications, 29-68
serial task participant, 29-37
I
ICommand
clear, G-3
command line, 61-5
delete, G-3
detailed command descriptions, G-3
export, G-5
sample, G-18
general command and option syntax, 61-2
import, G-10
log, G-17
Index-15
operations, G-1
regular expressions, G-18
remote execution, 61-6
rename, G-14
running, 61-1
sample export file, G-18
summary of commands, G-1
syntax, 61-2
syntax, object names, 61-3
XML file, G-15
ICommand utility, 61-1
ICommand web service, 59-4
idempotence
defining at the partner link operation level, 8-13
idempotent property
description, C-4
identification key
specifying in human task activities, 28-13
identity service
definition, 27-14, 34-12
determining a users local language and time
zone, 32-68
Enterprise JavaBeans, SOAP, and Java
support, 34-2
functions
getDefaultRealmName, B-62
getGroupProperty, B-62
getManager, B-62
getReportees, B-63
getUserProperty, B-63
getUserRoles, B-64
getUsersInGroup, B-64
isUserInRole, B-65
lookupGroup, B-65
lookupUser, B-65
providers, 34-13, 34-14
support for in workflows, 34-12
supported task operations, 34-12
use with JAZN, 34-12, 34-13
use with LDAP, 34-12, 34-13
WSDL file location, 34-2
if activity
capabilities, A-20
defining conditional branching, 11-5
replaces the switch activity in BPEL 2.0, A-3
ignoreMissingFromData attribute
selecting in an assign activity, A-10
using, 6-36
IM activity
capabilities, A-21
notifications support, 17-9
implicit-timezone function
description, B-6
import
source and target schemas into a
transformation, 40-9
indexes
in data objects, 55-17
indexing methods
using XPath, 6-48
Index-16
index-within-string function
description, B-12
inline variables initialization
in BPEL 2.0, 8-5
inMemoryOptimization property
description, C-2
insertMissingToData attribute
selecting in an assign activity, A-10
using, 6-36
instance names
setting the name at design time, 43-6
instances
routing messages to the same instance, 9-13
setting the composite instance name at design
time, 43-6
starting new, 8-9
integer function
description, B-32
integration
of Java and WSDL-based components in the same
composite, 38-1, 52-2, 52-15
interaction patterns
asynchronous interaction with a notification
timer, 5-5
asynchronous interaction with a timeout, 5-4
asynchronous interactions, 5-3
common patterns between a BPEL process and
another application, 5-1, 24-1
multiple interactions, 5-10
of interaction between a BPEL process and another
application, 5-1, 24-1
one request, a mandatory response, and an
optional response, 5-8
one request, multiple responses, 5-6
one request, one of two possible responses, 5-7
one-way message, 5-1
partial processing, 5-9
synchronous interactions, 5-2
Invalid Settings error message, A-53
invoke activity
adding a conversation ID, 8-11
adding to an asynchronous service, 8-3
capabilities, A-21
definition, 4-11, 7-1
in asynchronous services, 8-3, 8-8
in synchronous services, 7-1, 7-5
throwing faults with assertion conditions, 12-53
isUserInRole function
description, B-65
J
JAR
See .JAR Files
.JAR files
adding custom classes and JAR files, 14-6
adf-desktop-integration.jar, 35-2
creating a JAR file for deployment, 43-20
resourcebundle.jar file, 35-2
wsclient.jar, 35-2
Java
support in workflow services, 34-2
Java applications
wrapped as SOAP services, 14-2
Java Connector Architecture (JCA)
definition, 1-3
Java embedding
bpelx:exec extension, 14-4
example, 14-7
import syntax in BPEL 1.1, 14-3
import syntax in BPEL 2.0, 14-3
in a BPEL process, 14-1
Java code snippets in a BPEL 2.0 process, 14-3
Java code snippets into a BPEL process with the
bpelx:exec tag, 14-2
recommendations for incorporating small code
segments, 14-2
using thread.sleep(), 14-8
wrapping Java code as a SOAP service, 14-2
Java embedding activity
capabilities, A-22
using Java embedding in a BPEL process, 14-7
Java interfaces
creating Java interface integration with SOA
composite applications, 38-11
integrating Enterprise JavaBeans and SOA
composite applications, 38-1, 38-3
integration of Java and WSDL-based components
in the same SOA composite application, 52-2
selecting when creating a partner link, 4-12
using with spring service components, 52-2
JAXB
configuring the workflow client, 34-55
support in SOA composite applications, 52-28
JAZN
storing a users local language and time
zone, 32-68
use with identity service, 34-12, 34-13
jdbc.port parameter, 3-15
jdbc.sid parameter, 3-15
jdbc.urlBase parameter, 3-15
jdeveloper.home parameter, 3-15
JMS
definition, 1-3
JMS adapter
definition, 37-11
sensor publish type, 18-3
JMS queue
definition, 18-3
sensor publish type, 18-3
JMS topic
definition, 18-3
sensor publish type, 18-3
join conditions
using in target activities, 10-11
K
keepGlobalVariables property
description, C-2
keepSrcElementName attribute
definition, 6-3
selecting in an assign activity, A-10
using, 6-36
knowledge module
Oracle BAM, 57-3
L
languages
changing
from jazn xml file, 32-71
preferences, 32-68
setting in JAZN, 32-68
setting in LDAP, 32-68
large documents
best practices for handling, 45-1
importing large data sets in Oracle B2B, 45-23
large numbers of mediators in composites, 45-23
limitations on concurrent processing, 45-14
opaque schema for processing large
payloads, 45-14
processing in Oracle B2B, 45-18
setting a default JTA timeout for large
documents, 45-14
setting audit levels, 45-15
use cases for handling, 45-1
using a flow with multiple sequences, 45-22
using a flow with no sequence, 45-23
using a flow with one sequence, 45-22
using assign activities in BPEL and
mediator, 45-15
using large numbers of activities in BPEL processes
(with FlowN), 45-22
using large numbers of activities in BPEL processes
(without FlowN), 45-22
using XSLT transformations for repeating
structures, 45-17
using XSLT transformations on large payloads (for
BPEL and mediator), 45-15, 45-17
large XML documents
processing with complex structures, 45-13
processing with repeating constructs, 45-12
last-index-within-string function
description, B-13
layouts, data object, 55-9
LDAP
storing a users local language and time
zone, 32-68
used with identity service, 34-12, 34-13
left-trim function
description, B-13
listUsers function
description, B-32
literal strings
assigning, 6-19
literal XML
variable initialization, 6-13
local variables
in transformations, 40-38
Index-17
M
managed.server parameter, 3-23
managed.server.port parameter, 3-23
management chains
definition, 29-21
participant lists, 29-25
rule-based, 29-21
ManualRuleFire web service, 59-4
map parameters
creating in transformations, 40-38
map variables
creating in transformations, 40-38
mapped attributes, 32-58, 32-59
using, 32-58
values, 34-18
master and detail processes
creating, 16-7
definition, 16-1
receive signal activity, A-28
signal activity, A-34
matches function
description, B-14
maxOccurs attribute, 6-47, 6-48
setting for transformations, 40-51
max-value-among-nodeset function
description, B-45
mediator creation
specifying operation or event subscription
properties, 19-28
mediator XPath extension functions, B-46
memory
resolving XSLT Mapper memory issues, 40-46
message aggregation
in a BPEL process, 9-13
message filtering, 63-7, 64-11, 65-12
Index-18
message schemas
updating, 2-16
viewing, 2-16
message source advanced formatting, 56-10
message sources, 56-1
message types
support for simple types in a message part, 2-15
MessageFilter, 63-7, 64-11, 65-12
MessageFilterFactory, 63-7, 64-11, 65-12
messages
business event use, 9-16
controlling the number of instances to create to
route messages, 9-14
race conditions, 9-19
receiving, 63-6, 64-8, 65-9
rejecting, 63-7, 64-11, 65-12
routing a message to a new or existing instance
when using correlation sets, 9-17
routing to the same instance, 9-13
using the same operation in entry and midprocess
receive activities, 9-16
MessagingClientFactory, 63-3
MessagingClient.receive, 63-7, 64-9, 65-10
MessagingClient.registerAccessPoint, 63-6, 64-9,
65-10
MessagingClient.registerMessageFilter, 63-7, 64-11,
65-12
metadata
service components, 25-13
Metadata Service (MDS)
creating a SOA-MDS connections, 43-37
MIME
creating composites that use MIME
attachments, 45-4
MIME mapping
Excel workbook, 35-3
MinBPELWait property, 15-13
minimum wait time
MinBPELWait property, 15-13
minOccurs attribute
setting for transformations, 40-51
minutes-from-dateTime function
description, B-6
min-value-among-nodeset function
description, B-45
modes
xref
populateLookupXRefRow function, 49-14
populateXRefRow function, 49-12
populateXRefRow1M function, 49-15
modifying a mediator, 19-29
modifying event subscriptions, 19-29
modifying operations, 19-29
modifying cross reference tables
adding a column, 49-9
modifying mediator event subscriptions, 19-29
modifying mediator operations, 19-29
month-from-dateTime function
description, B-7
MQ adapter
definition, 37-11
MTOM
adding MTOM attachments to web
services, 45-10
using SOAP, 45-2
multilingual settings
specifying in tasks, 29-57, 34-32
multipart WSDLs
adding to a composite, 2-15
myRole attribute
definition, 8-7
N
named templates
creating, 40-21
in functions, 40-21
names and expressions
definition, 29-21
participant list, 29-23
rule-based, 29-21
namespace prefix, B-41
namespaces
BPEL 1.1 prefix, 6-4, B-41
BPEL 2.0 prefix, 6-4, B-41
declaring extension namespaces in BPEL 2.0, 6-58
ensuring the uniqueness of WSDL
namespaces, 2-16
naming conventions
for BPEL projects, 4-2
nonBlockingInvoke property
description, C-4
normalized message header properties
Oracle BPEL Process Manager, H-2
Oracle Web Services Addressing, H-3
NOT operator, 55-5
notification messages
editing, 29-66
notification services
actionable emails, 34-33
configuring the notification channel, 34-31
custom notification headers, 34-37
definition, 27-14
error message support, 34-30
multilingual settings, 34-32
notification contents, 34-29
reliability support, 34-30
sending inbound and outbound
attachments, 34-35
sending inbound comments, 34-35
sending reminders, 34-35
sending secure notifications, 34-35
setting automatic replies to unprocessed
messages, 34-36
specifying participant notification
preferences, 29-63
notifications
allowing the end user to select the notification
channels, 17-14
configuring in Oracle JDeveloper, 17-3
O
onAlarm branch
of pick activities, 15-2, A-26
of scope activities, 15-3, A-27
one request, a mandatory response, and an optional
response
BPEL process as the client, 5-9
BPEL process as the service, 5-9
one request, multiple responses
BPEL process as the client, 5-7
BPEL process as the service, 5-7
one request, one of two possible responses
BPEL process as the client, 5-8
BPEL process as the service, 5-8
one-to-many mapping, 47-4
onEvent branch
creating in a scope activity, 15-16
specifying events to wait for message
arrival, 15-14
one-way invocations
introduction, 13-4
one-way message interactions
BPEL process as the client, 5-2
BPEL process as the service, 5-2
oneWayDeliveryPolicy property
description, 4-5, C-2
setting, 13-4
setting during BPEL process creation, 4-5
setting in high availability environments, C-2
setting to async.cache in high availability
environments, 4-5
one.way.returns.fault
property, K-4
Index-19
onMessage branch
of pick activities, 15-2, A-26
of scope activities, 15-3, A-27
simultaneous onMessage branches in BPEL
2.0, 15-6
operators
AND operator, 55-5
optimization
streaming attachments, 45-7
OR operator, 55-5
Oracle Application Development Framework (ADF)
binding component, 1-5
Oracle Applications adapter
definition, 37-12
Oracle B2B
attachments, 45-10
binding component, 2-11, 2-19
definition, 1-5, 37-12
properties, K-5
streaming, 45-13
Oracle BAM, 53-28
definition, 1-6, 37-12
See Oracle Business Activity Monitoring
Server connection, 54-2
Oracle BAM Adapter, 53-1
Oracle BAM knowledge modules, 57-3
Oracle BAM Server
creating a BPEL sensor, 53-28
creating a BPEL sensor action, 53-29
creating a connection to, 53-24
Oracle BAM Server connection, 53-24
Oracle BPEL Designer
layout, 4-6
Oracle BPEL Process Manager
System MBean Browser properties, K-8
Oracle BPM Worklist
accessibility options, 1-10
See worklist
Oracle Business Activity Monitoring
creating a BPEL sensor action for Oracle BAM
Server, 53-29
creating a BPEL sensor for Oracle BAM
Server, 53-28
creating a connection to Oracle BAM
Server, 53-24
definition
integration with Oracle BPEL Process Manager
sensors, 53-28
message batching limitations, 53-32
overview, 53-28
Oracle Enterprise Manager Fusion Middleware
Control
improving the loading of pages, 45-23
properties, K-5
Oracle Enterprise Repository
design-time governance, A-53
Oracle Healthcare
binding component, 2-11, 2-19
definition, 1-5
Oracle Healthcare Adapter
Index-20
definition, 37-13
Oracle Internet Directory
storing a users local language and time
zone, 32-68
Oracle JDeveloper
adapters, 4-17
configuring notifications, 17-3
creating sensors, 18-3
installing the Oracle SOA Suite extension, 2-1, J-3
location of Application Navigator, 4-8
location of Component Palette, 4-8
location of Designer window, 4-8
location of History window, 4-9
location of Log window, 4-9
location of Property Inspector, 4-9
location of Source window, 4-9
location of Structure window, 4-9
overview of rules designer environment, 25-5
transformations, 40-7
Oracle JDeveloper project
desktop integration, adding, 35-2
Oracle Mediator
define routing rules, 20-5
definition, 19-1
routing rules, 20-1
service component, 2-7
System MBean Browser properties, K-9
wiring two Oracle Mediators can cause an infinite
loop, 2-25
Oracle Mediator Editor, 19-5
environment
Application Navigator, 19-4
History Window, 19-5
Log Window, 19-6
Oracle Mediator Editor, 19-5
Property Inspector, 19-5
Source View, 19-5
Structure Window, 19-6
layout, 19-5
Oracle Mediator error handling
actions, 22-4
conditions, 22-2
fault bindings, 22-9
fault policy, 22-1
introduction, 22-1
using, 22-11
XML schema files, 22-12
Oracle Metadata Services (MDS) repository
definition, 1-8
Oracle Service Bus
invocation by the direct binding service, 39-7
invoking through a direct binding service, 37-14
Oracle Service Bus (OSB)
invocation by the direct binding service, 37-14
Oracle Service Registry
changing endpoint locations in the registry
control, A-50
configuring a SOA project to invoke a service from
the registry, A-44
configuring the inquiry URL, UDDI service key,
P
packaging
of artifact files for deployment, 43-2
pages
improving the loading of pages in Oracle
Enterprise Manager Fusion Middleware
Control, 45-23
parallel
definition, 29-33
workflow participant type, 29-33
parallel blocks
definition, 29-17
parallel branches
customizing the number, 10-12
parallel flows
definition, 10-1
parallel participant types
specifying where to store the subtask
payload, 29-55
parseEscapedXML function
description, 6-54, B-33
partial processing
BPEL process as the client, 5-10
BPEL process as the service, 5-10
definition, 5-9
participant assignments
definition, 27-5
participant lists
rulesets, 29-27
value-based management chains, 29-25
value-based names and expressions, 29-23
participant types
FYI assignee, 27-4, 27-5, 29-40
parallel, 27-4, 29-33
serial, 27-4, 29-37
single approver, 27-4, 29-19
partitions
ant scripts, 43-57
creating, 43-26
default partition, 43-26
deployment in, 43-26
in the Fusion Order Demo, 3-23
issues with deploying the same composite with a
human workflow into multiple
partitions, 43-26, 43-48
selecting a partition during deployment, 43-26
partner link activity
capabilities, A-23
partner links
adding to an asynchronous service, 8-2
creating, 4-13
defining idempotence, 8-13
definition, 4-11
for an inbound adapter, 4-15
for an outbound adapter, 4-14
from an abstract WSDL to call a service, 4-15
from an abstract WSDL to implement a
service, 4-15
from an existing human task, business rule, or
Oracle Mediator, 4-16
in asynchronous services, 8-2, 8-7
in synchronous services, 7-1
Oracle BAM, 53-26
overview, 4-11
specifying a WSDL file, 4-12
using a dynamic partner link at runtime, 8-14
with human tasks or business rules, 4-16
partnerLinkType
definition, 8-6
partnerRole attribute
definition, 8-7
PartnerSupplierComposite project, 3-7
passThroughHeader
property, K-3
permissions
Index-21
copying, 55-7
data objects, 55-6
setting on folders, 55-11
phase activity
BPEL scope creation, 51-4
business rule service component creation, 51-5
capabilities, A-24
mediator service component creation, 51-4
using with two-layer business process
management, 51-3
pick activity
adding correlations on an OnMessage
branch, A-27
capabilities, A-25
code example, 15-5
condition branches, 15-2
creating, 15-3
differences with a receive activity, 15-3
for timeouts, 15-1
onAlarm branch, 15-2, A-26
onMessage branch, 15-2, A-26
simultaneous onMessage branches in BPEL
2.0, 15-6
throwing faults with assertion conditions, 12-53
policies
adding security policies, 2-26
attaching, 42-2
definition, 42-1
overriding client property values, 42-6
overriding policy configuration property
values, 42-6
overriding server property values, 42-8
supported categories, 42-1
populating cross reference tables, 49-10
xref
populateXRefRow1M function, 49-15
portlets
See task list portlets
ports
in synchronous services, 7-1
portType
definition, 8-6
position function
description, 6-47
process definitions
importing in BPEL 2.0, 6-46
process initiation
in BPEL test suites, 44-3
processes
naming conventions, 4-2
processXQuery function
description, B-34
processXSLT function
description, B-34
example, 17-9
processXSLTAttachment function
deprecated, B-15
processXSQL function
deprecated, B-15
projects
Index-22
Q
Qname
fault name, 12-5
qualifier, 47-2
qualifier order, 47-3
qualifier order, 47-3
query-database function
description, B-2
R
race conditions
with message aggregation, 9-19
readBinaryFromFile function
description, B-38, B-51
readFile function
description, B-38
limitation on web server file access requiring
authorization, B-39
reading files from absolute directory paths, B-38
receive activity
adding to an asynchronous service, 8-5
associating with correlation sets, 9-9
capabilities, A-27
create instance, 8-8
creating new instances, 8-9
differences with a pick activity, 15-3
in asynchronous services, 8-5, 8-8
setting timeouts for request-response
operations, 15-7
throwing faults with assertion conditions, 12-53
receive signal activity
capabilities, A-28
Index-23
34-32
specifying stage and participant names, 34-50
Resource Palette
introduction, 2-6
using, 2-14
resourcebundle.jar file, 35-2
rethrow activity
capabilities, A-31
rethrowing faults, 12-33
supported in BPEL 2.0 projects, A-31
retryCount
properties, K-4
retryInterval
properties, K-4
revisions
activating, 2-29
invoking the default revision, 2-21
retiring, 2-29
setting the default revision, 2-29
turning off, 2-28
turning on, 2-28
undeploying, 2-29
right-trim function
description, B-14
roles
for partner links in asynchronous services, 8-7
rolesAllowed
property, K-3
routing policies
available types, 29-43
business rules, 29-43
completing parent subtasks of early completing
subtasks, 29-46
enabling early completion in parallel
subtasks, 29-46
external routing, 29-43, 29-52
routing a task to all participants in the order
specified, 29-43
selecting, 29-41
routing rules, 20-1
define, 20-5
defining, 20-5
filter expression, 20-16
introduction, 20-1
routing slip
definition, 29-32
RPC styles
differences with document-literal styles in WSDL
files, 6-2, 6-55
rulesets
management chains, 29-21
names and expressions, 29-21
participant lists, 29-27
runtime config service
definition, 27-15
Enterprise JavaBeans, SOAP, and Java
support, 34-2
supported task operations, 34-17
WSDL file location, 34-3
runtime exceptions, 12-5
Index-24
runtime faults
definition, 12-5
example, 12-30
RuntimeFault.wsdl file
importing into a process, 12-30
S
samples
business events, 41-1
business rules, 25-23
domain value maps, 47-24
dynamic assignment functions, 34-42
email notifications, 30-31
Hello World, 7-1
human workflow, 29-50, 29-80, 31-15
internationalization of attribute labels, 34-20
iterative design, 29-50
notifications, 17-8
Oracle SOA Suite, 1-9
transformations, 40-22
two-layer business process management, 51-7
workflow event callbacks, 29-80
SAR file
definition, 1-9, 43-3
deploying, 43-18
SCA See Service Component Architecture
sca-build.properties file, 3-21
schema files
creating a transformation map file from imported
schemas, 40-9
replacing in the XSLT Mapper, 40-43
schemas
updating message schemas, 2-16
viewing message schemas, 2-16
scope activity
adding descriptive notes and images, 12-37
capabilities, A-32
creating, 12-38
creating an onEvent branch, 15-15
fault handling, 12-35
re-executing with a replay activity, 12-46
using a fault handler in a scope activity, 12-40
scope name
specifying in human task activities, 28-12
SDO
See Service Data Objects (SDO)
search function
description, B-39
seconds-from-dateTime function
description, B-7
security filters
copying, 55-15
on data objects, 55-13
security model
for workflow services, 34-4
in SOAP web services, 34-5
workflow context on behalf of a user, 34-5
security policies
See policies
Index-25
Index-26
SOA Infrastructure
properties, K-5
System MBean Browser properties, K-7
SOA XPath extension functions, B-1
SOA-MDS connections
opening the composite.xml file, 43-8
soa.only.deployment parameter, 3-22
SOAP
definition, 1-3
reading and encoding SOAP attachment
content, 45-7
security in SOAP web services, 34-5
support in workflow services, 34-2
with attachments, 45-3
SOAP headers, 6-56
receiving in BPEL, 6-56
sending in BPEL, 6-57
SOAP services
performance issues, 14-2
using Java code, 14-2
SOAP-encoded arrays, 6-48
in BPEL 2.0, 6-49
using a wsdl
arrayType attribute inside a schema, 6-49
soa.server.oracle.home parameter, 3-23
socket adapter
definition, 37-11
Source window
location of in Oracle JDeveloper, 4-9
sources
message, 56-1
Sources tab
available only in BPEL 2.0 projects, 10-7, A-6
in activities, A-6
specifying operation or event subscription
properties, 19-28
spring
automatic discovery of an interface class not found
in the classpath, but the source file
exists, 52-17
configuring Aspectj classes, 52-31
configuring Groovy classes, 52-31
contents of componentType file, 52-14
contents of spring context file, 52-7
creating a spring service component in Oracle
JDeveloper, 52-5
EXM files, 52-29
in Fusion Order Demo, 3-7, 52-22
integration
of Java and WSDL-based components in the
same composite, 52-2
introduction, 52-1
invocation errors, 52-31
Java class errors during Java-to-WSDL
conversions, 52-17
JAXB and OXM support, 52-28
logging, 52-18
MIME attachment processing is not
supported, 45-3
service component, 2-7
synchronous requests
not timing out, 7-6
synchronous services
callbacks with the partner link and invoke
activity, 7-1
calling, 7-2
invoke activities, 7-5
ports, 7-1
SyncMaxWaitTime property
in synchronous callbacks, 7-6
synchronous requests not timing out, 7-6
system faults
handling and propagating in a synchronous BPEL
process, 12-6
System MBean Browser
properties, K-7
T
Targets tab
available only in BPEL 2.0 projects, 10-7, A-6
in activities, A-6
task action time limits
specifying, 29-32, 29-37, 29-39
task admin
definition, 27-8
task assignments
dynamic, 27-6
restricting, 29-75
rule-based, 27-6
static, 27-6
task category
specifying, 29-7
task conditions
abruptly completing a condition, 29-45
task deadlines
definition, 27-8
task display form
autogenerated, 30-8
creating, 30-8, 30-25, 30-27
creating a task form with the Custom Task Form
Wizard, 30-11
definition, 28-3, 30-1
deploying, 30-37
displaying, 30-47
generating content for facets, 30-12
registering the library JAR file for custom page
templates, 30-10
.task file
associating with a BPEL process, 28-2, 28-7
definition, 28-2, 28-5
task flow
ADF
task display form for human tasks, 30-3
deploying, 43-24
task history
specifying in human task activities, 28-13
task initiator
definition, 27-8
specifying, 28-10
Index-27
Index-28
specifying, 29-16
task payload data structure
specifying, 29-13
task priority
specifying, 28-10, 29-6
task query service
definition, 27-14
Enterprise JavaBeans, SOAP, and Java
support, 34-2
supported task operations, 34-9
WSDL file location, 34-2
task reminders
setting up, 29-67
task report service
Enterprise JavaBeans, SOAP, and Java
support, 34-2
supported task operations, 34-17
WSDL file location, 34-3
task reviewer
definition, 27-8
task routing service
definition, 27-14
task service
definition, 27-14
Enterprise JavaBeans, SOAP, and Java
support, 34-2
supported task operations, 34-6
WSDL file location, 34-2
task stages
definition, 27-10
task title
specifying, 28-9
tasks
escalating, renewing, or ending a task, 29-58
notifications and reminders, 34-28
TCP tunneling
setting up a TCP listener for asynchronous
services, 8-23
setting up a TCP listener for synchronous
services, 8-22
terminate activity
capabilities, A-36
definition, 12-51
fault handling, 12-51
replaced by the exit activity in BPEL 2.0, A-4
test suites
components, 44-3
creating, 44-5
definition, 44-2
limitations on multibyte character names, 44-5
third party adapter
definition, 37-12
thread.sleep()
using in a Java embedding activity, 14-8
throw activity
capabilities, A-37
rolling back transactions with the bpelx:rollback
extension, 12-32
throwing internal faults, 12-31
time
sheet, 40-7
customizing sample XML generation, 40-51
dictionaries, 40-36
editing functions, 40-20
editing XPath expressions, 40-24
error when mapping duplicate elements, 40-7
functions, 40-19
functions prefixed with xp20 or orcl, 40-19
generating optional elements, 40-51
generating reports, 40-49
global variables, 40-38
ignoring elements, 40-42
linking source target nodes, 40-17
local variables, 40-38
map parameter and variable creation, 40-38
named templates in functions, 40-21
repeating elements, 40-28
replacing schemas, 40-43
rules, 40-6
searching source and target nodes, 40-40
setting constant values, 40-18
setting the maximum depth, 40-51
setting the number of repeating elements, 40-51
testing the map file, 40-47
using arrays, 40-28
using the XSLT Mapper, 40-16
using XQuery and XSLT, 6-5
viewing unmapped target nodes, 40-35
xsl choose conditional processing, 40-27
xsl if conditional processing, 40-26
troubleshooting
deployment, 43-66
spring invocation errors, 52-31
trusted domains
enabling when Oracle SOA Suite and Oracle
Service Bus are in different domains, 39-9
tuning
general recommendations, 45-14
two-layer business process management
definition, 51-1
dynamic routing decision table, 51-6
phase activity, 51-3
use case, 51-7
U
UDDI See Oracle Service Registry
uddiCacheLifetime
property, K-9
undeployment
SOA composite applications, 2-29
Unicode support, 2-2
upper-case function
description, B-15
user directory
selecting notification recipients by browsing the
directory, 17-13
user metadata service
definition, 27-14
Enterprise JavaBeans, SOAP, and Java
Index-29
support, 34-2
supported task operations, 34-15
WSDL file location, 34-3
user notification activity
allowing the end user to select the notification
channels, 17-14
capabilities, A-38
user notifications
definition, 17-14
using domain value maps, 47-10
using domain value maps a transformation, 47-12
using error handling, 22-11
using lookupValue functions, 47-14
using Oracle Mediator error handling, 22-11
V
validate activity
capabilities, A-39
validate syntax (XSD) property
specifying operation or event subscription
properties, 19-28
validateXML property
description, C-4
validation
of XML data with bpelx:validate, 6-37
when loading a process diagram, A-53
variable sensors
definition, 18-2
variables
complex type, 6-15
copying data between, 6-14
element variables in message exchange activities in
BPEL 2.0, 6-38
initializing variables inline in BPEL 2.0, 8-5
initializing with an inline from-spec in BPEL 2.0
projects, 6-15
initializing with expression constants, 6-13
initializing with literal XML, 6-13
ViewController project, 35-2
voice activity
capabilities, A-40
notifications support, 17-12
voice mail
dynamically setting telephone numbers, 17-12
notifications support, 17-12
W
wait activity
capabilities, A-40
creating, 15-13
definition, 15-13
setting an expiration time, 15-13
web services
adding a WSDL file, 2-12
binding component, 2-11, 2-19
connecting with SOAP over HTTP,
DataObjectDefinition, 59-3
DataObjectOperations, 59-2
Index-30
1-5
definition, 37-2
ICommand, 59-4
ManualRuleFire, 59-4
service component, 25-14
WS-Atomic transactions support, 37-2
WSDL files, 25-13
WebLogic Fusion Order Demo application
B2BX12OrderGateway project, 3-7
bin project, 3-7
composite.xml file, 3-7
CreditCardAuthorization project, 3-7
deploying, 3-21
ExternalLegacyPartnerSupplier project, 3-7
OrderAppovalHumanTask project, 3-7
OrderBookingComposite project, 3-7
OrderSDOComposite project, 3-7
overview, 3-6
PartnerSupplierComposite project, 3-7
processing described, 3-8
projects in, 3-7
setting up, 3-3
viewing in Oracle JDeveloper, 3-6
web.xml file, 35-3
wfDynamicGroupAssign function
description, B-60
wfDynamicUserAssign function
description, B-61
while activity
capabilities, A-41
in conditional branching logic, 11-8
wires
adding, 2-21, 2-25
definition, 1-6
deleting, 2-25
using, 2-22
wiring a service component and reference, 2-23
wiring two Oracle Mediators can cause an infinite
loop, 2-25
WLST utility
creating a configuration plan, 43-15
managing composites, 43-42
WordML style sheets
using for attachments, 29-56
workflow context
creating on behalf of a user, 34-5
workflow functions
overview, 34-1
workflow service clients, 33-3
interface, 33-5
workflow services
abruptly completing a condition, 29-45
actionable emails, 34-33
allowing all participants to invite other
participants, 29-44
assigning task participants by name or
expression, 29-25, 29-55
assignment service configuration, 34-37
associating the human task activity with a BPEL
process, 28-7
associating the human task definition with a BPEL
process, 28-2
bypassing task participants, 29-33, 29-37, 29-40
changing character set encoding, 29-67
customizing notification headers, 29-69
editing notification messages, 29-66
Enterprise JavaBeans support, 34-2
escalate after policy, 29-60
escalating, renewing, or ending a task, 29-58
escalation and expiration policy overview, 29-58,
29-59
escalation rules, 29-61
expire after policy, 29-59
functions, B-57
clearTaskAssignees, B-57
createWordMLDocument, B-57
getNotificationProperty, B-57
getNumberOfTaskApprovals, B-58
getPreviousTaskApprover, B-58
getTaskAttachmentByIndex, B-58
getTaskAttachmentByName, B-59
getTaskAttachmentContents, B-59
getTaskAttachmentsCount, B-59
getTaskResourceBindingString, B-60
wfDynamicGroupAssign, B-60
wfDynamicUserAssign, B-61
FYI assignee task participant, 29-40
group voting details, 29-35
identification key, 28-13
identity service, 27-14
including the task history of other tasks, 28-13
inviting additional task participants, 29-33, 29-37,
29-40
Java support, 34-2
making email messages actionable, 29-68
multilingual settings, 29-57, 34-32
never expire policy, 29-59
notification contents, 34-29
notification preferences, 29-63
notification service, 27-14, 34-31
notifications, 34-28
notifying recipients of changes to task
status, 29-64
overview, 34-1
parallel task participant, 29-33
renew after policy, 29-60
routing slip
definition, 29-32
runtime config service, 27-15
scope name and global task variable name, 28-12
securing notifications, 29-67, 34-35
security model, 34-4, 34-5
sending email notifications to groups and
application roles, 29-68
sending task attachments with email
notifications, 29-68
serial task participant, 29-37
setting up reminders, 29-67
sharing attachments and comments with task
participants, 29-36
showing the Oracle BPM Worklist URL in
notifications, 29-67
single approver task participant, 29-19
SOAP support, 34-2
specifying a task initiator and task priority, 28-10
specifying a task title, 28-9
specifying callback classes, 29-76
specifying task parameters, 28-10
support for identity service, 34-12
task attachments with email notifications, 34-35
task category, 29-7
task display form, 28-3, 30-1
.task file
definition, 28-2, 28-5
task metadata service, 27-14
task notifications, 34-28
task outcomes, 29-5
task owner, 28-13
task owner specification through the user
directory, 29-8
task owner specification through XPath
expressions, 29-12
task participants, 29-16
task payload data structure, 29-13
task priority, 29-6
task query service, 27-14
task routing and customization in BPEL
callbacks, 29-80
task routing service, 27-14
task service, 27-14
task title, 29-4
time limits for acting on tasks, 29-32, 29-37, 29-39
user metadata service, 27-14
viewing BPEL callbacks, 28-15
WordML style sheets in attachments, 29-56
worklist
acting on tasks, 32-28
acting on tasks that require a digital
signature, 32-35
administration functions, 32-44
approving tasks, 32-38
assignment rules for tasks with multiple
assignees, 32-44
creating a ToDo list, 32-21
creating and customizing worklist views, 32-16
creating group rules, 32-42
creating user rules, 32-41
customizing the task status chart, 32-20
definition, 32-1
filtering tasks, 32-8
logging in, 32-3
managing messaging channels, 32-54
managing messaging filters, 32-56
managing rules, 32-45
mapping mapped attributes, 32-59
messaging filter rules, 32-53
reports, 32-63, 32-64
rule actions, 32-54
setting a vacation period, 32-39
setting rules, 32-41
specifying notification settings, 32-52
Index-31
X
XML assert
overview, 44-2
XML data in BPEL, 6-2
Index-32
populateLookupXRefRow function
modes, 49-14
parameters, 49-14
populateXRefRow function
modes, 49-12
parameters, 49-12
populateXRefRow1M function, 49-15
modes, 49-15
parameters, 49-15
xsl choose
conditional processing, 40-27
xsl if
conditional processing, 40-26
XSL map
creating from an XSL style sheet, 40-7
XSL style sheet
creating an XSL map, 40-7
XSL transformations
definition, 1-3
XSLT, 6-2, 6-5
XSLT constructs
adding in transformations, 40-25
XSLT Mapper
adding XSLT constructs, 40-25
auto mapping, 40-31
auto mapping with confirmation, 40-33
chaining functions, 40-20
correcting memory errors when generating
reports, 40-50
creating a map file, 40-1
creating a map file from imported schemas, 40-9
creating a new map file, 40-7
creating a transform activity, 40-7
creating an XSL map from an XSL style
sheet, 40-7
customizing sample XML generation for
transformations, 40-51
dictionaries, 40-36
domain value map and cross reference functions
cannot be executed during design
time, 40-49
editing functions, 40-20
editing XPath expressions, 40-24
error when mapping duplicate elements, 40-7
functions, 40-19
functions available with Oracle Mediator and not
BPEL processes, 40-3
functions prefixed with xp20 or orcl, 40-19
generating optional elements, 40-51
generating reports, 40-49
ignoring elements, 40-42
layout in Oracle JDeveloper, 40-1
linking source and target nodes, 40-17
map parameter and variable creation, 40-38
memory issues, 40-46
named templates in functions, 40-21
repeating elements, 40-28
replacing schemas, 40-43
rules, 40-6
searching source and target nodes, 40-40
40-51
Y
year-from-dateTime function
description, B-8
Index-33
Index-34