Oracle SOA 11g Developers Guide
Oracle SOA 11g Developers Guide
Oracle SOA 11g Developers Guide
April 2008
Beta Draft
Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite, 11g Release 1 (11.1.1)
E10224-01
Primary Author: Virginia Beecher, Deanna Bradshaw, Rima Dave, Mark Kennedy, and Alex Prazma
Contributor: Oracle SOA Suite development, product management, and quality assurance teams
The Programs (which include both the software and documentation) contain proprietary information; they
are provided under a license agreement containing restrictions on use and disclosure and are also protected
by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly,
or decompilation of the Programs, except to the extent required to obtain interoperability with other
independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems in
the documentation, please report them to us in writing. This document is not warranted to be error-free.
Except as may be expressly permitted in your license agreement for these Programs, no part of these
Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose.
If the Programs are delivered to the United States Government or anyone licensing or using the Programs on
behalf of the United States 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, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation
and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license
agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial
Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA
94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy and other measures to ensure the safe use of such applications if the Programs are used for such
purposes, and we disclaim liability for any damages caused by such use of the Programs.
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective owners.
The Programs may provide links to Web sites and access to content, products, and services from third
parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites.
You bear all risks associated with the use of such content. If you choose to purchase any products or services
from a third party, the relationship is directly between you and the third party. Oracle is not responsible for:
(a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the
third party, including delivery of products or services and warranty obligations related to purchased
products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from
dealing with any third party.
Alpha and Beta Draft documentation are considered to be in prerelease status. This documentation is
intended for demonstration and preliminary use only. We expect that you may encounter some errors,
ranging from typographical errors to data inaccuracies. This documentation is subject to change without
notice, and it may not be specific to the hardware on which you are using the software. Please be advised
that prerelease documentation is not warranted in any manner, for any purpose, and we will not be
responsible for any loss, costs, or damages incurred due to the use of this documentation.
Contents
iv Beta Draft
3.6 Troubleshooting Applications .................................................................................................. 3-8
3.6.1 Recovering from Faults....................................................................................................... 3-8
3.6.1.1 Design Time Configuration......................................................................................... 3-8
3.6.1.2 BPEL Process and Oracle Mediator Fault Handling Features ............................ 3-10
3.6.1.3 Recovering from Faults in Oracle Enterprise Manager Grid Control Console 3-11
3.6.2 Viewing Log Files ............................................................................................................. 3-11
3.6.2.1 Log File and Location................................................................................................ 3-11
3.6.2.2 Log Level Settings ..................................................................................................... 3-12
3.6.2.3 Setting Logging Levels.............................................................................................. 3-13
3.6.2.4 Writing Logs to Text Files ........................................................................................ 3-15
3.6.2.5 Displaying Debug Information ............................................................................... 3-15
3.6.3 Viewing Deployment Error Files.................................................................................... 3-16
Beta Draft v
4.4.10.1 Creating a Map Parameter ....................................................................................... 4-30
4.4.10.2 Creating a Map Variable........................................................................................... 4-30
4.4.11 Searching Source and Target Nodes .............................................................................. 4-31
4.4.12 Controlling Generation of Unmapped Target Elements............................................. 4-32
4.4.13 Ignoring Elements in the XSLT Document ................................................................... 4-32
4.4.14 Replacing a Schema in the XSLT Mapper ..................................................................... 4-32
4.4.15 Using Type Substitution in the XSLT Mapper ............................................................. 4-33
4.5 Testing the Map........................................................................................................................ 4-35
4.5.1 Test XSL Map Window .................................................................................................... 4-36
4.5.2 Generating Reports........................................................................................................... 4-38
4.5.2.1 Correcting Memory Errors When Generating Reports........................................ 4-39
4.5.3 Sample XML Generation ................................................................................................. 4-39
4.6 Summary ................................................................................................................................... 4-40
vi Beta Draft
6 Creating Routing Rules
6.1 Introduction to Routing Rules .................................................................................................. 6-1
6.2 Defining Routing Rules.............................................................................................................. 6-2
6.2.1 Creating Dynamic Routing Rules...................................................................................... 6-4
6.2.2 Creating Static Routing Rules ............................................................................................ 6-4
6.2.2.1 Specifying Target Service ............................................................................................ 6-4
6.2.2.2 Specifying Expression for Filtering Messages.......................................................... 6-7
6.2.2.3 Specifying Sequential or Parallel Execution .......................................................... 6-13
6.2.2.4 Using Semantics Validation ..................................................................................... 6-13
6.2.2.5 Creating Transformations ........................................................................................ 6-14
6.2.2.6 Assigning Values ....................................................................................................... 6-16
6.2.2.7 Callback, Synchronous Reply, and Fault Handling ............................................. 6-19
6.2.3 Callback, Synchronous Reply, and Fault Handling..................................................... 6-19
6.3 Use Case .................................................................................................................................... 6-19
6.3.1 Step-By-Step Instructions for Creating the CustomerRouter Use Case.................... 6-20
6.3.1.1 Task 1: Creating an Oracle JDeveloper Application and Project........................ 6-20
6.3.1.2 Task 2: Creating CustomerRouter Mediator ......................................................... 6-22
6.3.1.3 Task 3: Creating a File Adapter Service ................................................................. 6-22
6.3.1.4 Task 4: Creating External References ..................................................................... 6-25
6.3.1.5 Task 5: Specifying Routing Rules ............................................................................ 6-26
6.3.1.6 Task 6: Configuring Oracle Application Server Connection............................... 6-34
6.3.1.7 Task 7: Deploying CustomerRouterProject ........................................................... 6-35
6.3.2 Running and Monitoring the CustomerRouterProject Application.......................... 6-36
Beta Draft ix
12 Manipulating XML Data in BPEL Processes
12.1 Use Cases for Manipulating XML Data in BPEL................................................................. 12-1
12.2 Introduction to Manipulating XML Data in BPEL Concepts ............................................ 12-2
12.2.1 How XML Data Works in BPEL ..................................................................................... 12-2
12.2.2 About Data Manipulation and XPath Standards ......................................................... 12-2
12.3 Delegating XML Data Operation to Data Provider Services ............................................. 12-4
12.3.1 Addressing XML Data Operation Challenges.............................................................. 12-5
12.3.2 How the Entity Variable Works ..................................................................................... 12-6
12.3.2.1 Inbound Direction ..................................................................................................... 12-6
12.3.2.2 Outbound Direction .................................................................................................. 12-7
12.3.3 Example of Defining an Entity Variable........................................................................ 12-7
12.3.3.1 Create an Entity Variable and Choose a Partner Link ......................................... 12-7
12.3.3.2 Create a Binding Key ................................................................................................ 12-8
12.4 Initializing a Variable with Expression Constants or Literal XML................................... 12-9
12.5 Copying Between Variables ................................................................................................. 12-10
12.6 Accessing Fields Within Element-Based and Message Type-Based Variables ............. 12-10
12.7 Assigning Numeric Values................................................................................................... 12-11
12.8 Mathematical Calculations with XPath Standards ........................................................... 12-11
12.9 Assigning String Literals....................................................................................................... 12-12
12.10 Concatenating Strings ........................................................................................................... 12-12
12.11 Assigning Boolean Values .................................................................................................... 12-13
12.12 Assigning Date or Time ........................................................................................................ 12-13
12.13 Manipulating Attributes ....................................................................................................... 12-14
12.14 Manipulating XML Data with bpelx Extensions ............................................................... 12-14
12.14.1 bpelx:append ................................................................................................................... 12-15
12.14.2 bpelx:insertBefore ........................................................................................................... 12-15
12.14.3 bpelx:insertAfter ............................................................................................................. 12-16
12.14.4 bpelx:remove ................................................................................................................... 12-17
12.14.5 bpelx:rename and XSD Type Casting .......................................................................... 12-18
12.14.6 bpelx:copyList ................................................................................................................. 12-19
12.15 Validating XML Data with bpelx:validate ......................................................................... 12-20
12.16 Manipulating XML Data Sequences That Resemble Arrays ........................................... 12-20
12.16.1 Statically Indexing into an XML Data Sequence That Uses Arrays ........................ 12-21
12.16.2 Determining Sequence Size ........................................................................................... 12-22
12.16.3 Dynamically Indexing by Applying a Trailing XPath to an Expression ................ 12-22
12.16.3.1 Dynamic Indexing Example................................................................................... 12-22
12.16.3.2 Using the bpelx:append Extension to Append New Items to a Sequence...... 12-23
12.16.3.3 Merging Data Sequences ........................................................................................ 12-24
12.16.3.4 Generating Functionality Equivalent to an Array of an Empty Element........ 12-24
12.16.4 Limited Support for SOAP-Encoded Arrays .............................................................. 12-25
12.17 Converting from a String to an XML Element................................................................... 12-25
12.18 Differences Between Document-Style and RPC-Style WSDL Files ................................ 12-26
12.19 Manipulating SOAP Headers in BPEL ............................................................................... 12-27
12.19.1 Receiving SOAP Headers in BPEL ............................................................................... 12-27
12.19.2 Sending SOAP Headers in BPEL.................................................................................. 12-28
x Beta Draft
13 Invoking a Synchronous Web Service from BPEL Processes
13.1 Use Case for Synchronous Web Services.............................................................................. 13-1
13.2 Introduction to Synchronous Service Concepts .................................................................. 13-2
13.2.1 Establishing the Partner Link.......................................................................................... 13-2
13.2.1.1 Defining the Partner Link in the BPEL Code......................................................... 13-2
13.2.1.2 Using the WSDL File to Enable the Web Services to Work with a BPEL Process
Service Component 13-3
13.2.2 Using the Invoke Activity to Perform a Request ......................................................... 13-4
13.3 Calling a Synchronous Service............................................................................................... 13-5
13.4 Summary ................................................................................................................................... 13-6
Beta Draft xi
14.4.6.1 Creating Property Aliases for NameCorr ............................................................ 14-23
14.4.6.2 Creating Property Aliases for IDCorr................................................................... 14-24
14.4.7 Step 7: Reviewing WSDL File Content ........................................................................ 14-25
14.5 Summary ................................................................................................................................. 14-25
Beta Draft xv
26.6.5.2 Configuring the Single Approver Participant Type ........................................... 26-24
26.6.5.3 Configuring the Group Vote Participant Type ................................................... 26-27
26.6.5.4 Configuring the Management Chain Participant Type ..................................... 26-31
26.6.5.5 Configuring the Sequential List of Approvers Participant Type...................... 26-34
26.6.5.6 Configuring the FYI Assignee Participant Type ................................................. 26-37
26.6.5.7 Configuring the External Routing Service Participant Type............................. 26-38
26.6.5.8 Allowing All Participants to Invite Other Participants...................................... 26-40
26.6.5.9 Adding Reviewers ................................................................................................... 26-40
26.6.5.10 Routing Tasks to All Participants in the Specified Order.................................. 26-40
26.6.5.11 Abruptly Completing a Condition........................................................................ 26-41
26.6.5.12 Advanced Task Routing Using Business Rules .................................................. 26-42
26.6.6 Escalating, Renewing, or Ending the Task.................................................................. 26-46
26.6.6.1 Introduction to Escalation and Expiration Policy............................................... 26-47
26.6.6.2 Never Expire Policy................................................................................................. 26-49
26.6.6.3 Expire After Policy .................................................................................................. 26-49
26.6.6.4 Renew After Policy.................................................................................................. 26-50
26.6.6.5 Escalate After Policy................................................................................................ 26-51
26.6.6.6 Specifying a Due Date............................................................................................. 26-52
26.6.7 Specifying Participant Notification Preferences......................................................... 26-53
26.6.7.1 Notifying Recipients of Changes to Task Status ................................................. 26-54
26.6.7.2 Editing the Notification Message .......................................................................... 26-55
26.6.7.3 Setting Up Reminders ............................................................................................. 26-55
26.6.7.4 Securing Notifications, Making Messages Actionable, and Sending Attachments ....
26-56
26.6.8 Specifying Advanced Settings ...................................................................................... 26-57
26.6.8.1 Specifying Escalation Rules.................................................................................... 26-58
26.6.8.2 Specifying WordML Style Sheets for Attachments ............................................ 26-59
26.6.8.3 Specifying Style Sheets for Attachments.............................................................. 26-59
26.6.8.4 Specifying Multilingual Settings ........................................................................... 26-59
26.6.8.5 Overriding Default Exception Management ....................................................... 26-60
26.6.8.6 Specifying Callback Classes on Task Status ........................................................ 26-61
26.6.8.7 Allowing Task and Routing Customization in BPEL Callbacks....................... 26-62
26.6.8.8 Specifying a Workflow Signature Policy ............................................................. 26-62
26.6.8.9 Specifying Access Rules on Task Content............................................................ 26-63
26.6.9 Specifying Annotations.................................................................................................. 26-68
26.6.10 Exiting the Human Task Editor and Saving Your Changes ..................................... 26-69
26.7 Associating the Human Task Service Component with a BPEL Process ...................... 26-69
26.7.1 Associating a Human Task with a BPEL Process....................................................... 26-69
26.7.2 Defining the Human Task Activity Title, Initiator, Priority, and Parameter Variables ....
26-70
26.7.2.1 Specifying the Task Title......................................................................................... 26-71
26.7.2.2 Specifying the Task Initiator and Task Priority .................................................. 26-72
26.7.2.3 Specifying Task Parameters ................................................................................... 26-72
26.7.3 Viewing the Generated Human Task Activity ........................................................... 26-73
26.7.3.1 BPEL Callbacks ........................................................................................................ 26-75
26.7.4 Defining the Human Task Activity Advanced Features .......................................... 26-77
26.7.4.1 Specifying a Scope Name and a Global Task Variable Name........................... 26-78
26.7.4.2 Specifying a Task Owner........................................................................................ 26-78
xx Beta Draft
31 Human Task and Microsoft Excel Integration
31.1 Invoking a BPEL Process from Excel Workbook................................................................. 31-1
31.2 Attaching Excel Workbooks to E-mail Notifications .......................................................... 31-2
34 Creating Alerts
34.1 Introducing Alerts.................................................................................................................... 34-1
37 Using ICommand
37.1 Introducing ICommand .......................................................................................................... 37-1
37.2 Executing ICommand.............................................................................................................. 37-1
37.3 General Command and Option Syntax ................................................................................ 37-2
37.3.1 Specifying the Command ................................................................................................ 37-2
37.4 Object Name Syntax ................................................................................................................ 37-2
37.5 Command-line-only Parameters............................................................................................ 37-3
37.6 Running ICommand Remotely .............................................................................................. 37-4
37.7 Summary of Individual Commands ..................................................................................... 37-5
37.8 Detailed Command Descriptions .......................................................................................... 37-6
37.8.1 Export ................................................................................................................................. 37-6
37.8.2 Import ............................................................................................................................... 37-10
37.8.3 Delete ................................................................................................................................ 37-13
37.8.4 Rename ............................................................................................................................. 37-14
37.8.5 Clear.................................................................................................................................. 37-15
37.9 Format of Command File...................................................................................................... 37-15
37.9.1 Inline Content.................................................................................................................. 37-16
37.9.2 Command IDs ................................................................................................................. 37-16
37.9.3 Continue On Error .......................................................................................................... 37-17
37.10 Format of Log File.................................................................................................................. 37-17
37.11 Sample Export File................................................................................................................. 37-18
37.12 Regular Expressions .............................................................................................................. 37-19
37.13 Using ICommand Web Service............................................................................................ 37-21
37.13.1 Differences between the ICommand Web Service and the ICommand Command-Line
Utility 37-22
37.13.2 Using the ICommand Web Service .............................................................................. 37-22
37.13.3 Security Issues ................................................................................................................. 37-23
37.13.3.1 IIS Security (HTTP 401 error) [remove for 11g?] ................................................ 37-23
37.13.3.2 Active Data Cache Security.................................................................................... 37-23
Index
Audience
This manual is intended for anyone who is interested in using Oracle SOA Suite.
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation
accessible, with good usability, to the disabled community. To that end, our
documentation includes features that make information available to users of assistive
technology. This documentation is available in HTML format, and contains markup to
facilitate access by the disabled community. Accessibility standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For more information, visit the Oracle Accessibility
Program Web site at
http://www.oracle.com/accessibility/
Beta Draft
TTY Access to Oracle Support Services
Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services
within the United States of America 24 hours a day, seven days a week. For TTY
support, call 800.446.2398.
Related Documents
For more information, see the following Oracle resources:
■ Oracle BPEL Process Manager Administrator’s Guide
Printed documentation is available for sale in the Oracle Store at
http://oraclestore.oracle.com/
To download free release notes, installation documentation, white papers, or other
collateral, visit the Oracle Technology Network (OTN). You must register online before
using OTN; registration is free and can be done at
http://www.oracle.com/technology/membership/
To download Oracle BPEL Process Manager documentation, technical notes, or other
collateral, visit the Oracle BPEL Process Manager site at Oracle Technology Network
(OTN):
http://www.oracle.com/technology/bpel/
If you already have a username and password for OTN, then you can go directly to the
documentation section of the OTN Web site at
http://www.oracle.com/technology/documentation/
See the Business Process Execution Language for Web Services Specification, available at the
following URL:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us
/dnbizspec/html/bpel1-1.asp
See the XML Path Language (XPath) Specification, available at the following URL:
http://www.w3.org/TR/1999/REC-xpath-19991116
See the Web Services Description Language (WSDL) 1.1 Specification, available at the
following URL:
http://www.w3.org/TR/wsdl
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
Beta Draft
Beta Draft
Beta Draft
Part I SOA Suite Introduction
This part introduces the components that comprise Oracle SOA Suite and how these
components interact in a SOA composite application. This section also introduces the
SOA Composite Editor that you use to design SOA composite applications. An
introduction into the life cycle of a SOA composite application is also provided.
This part contains the following chapters:
■ Chapter 1, "Service-Oriented Architecture and Oracle SOA Suite"
■ Chapter 2, "Introduction to the SOA Composite Editor"
■ Chapter 3, "Life Cycle of an Application"
Beta Draft
Beta Draft
1
1 Service-Oriented Architecture and Oracle
SOA Suite
See Also:
■ Chapter 2, "Introduction to the SOA Composite Editor" for details
on using the SOA Composite Editor to create an SOA composite
application
1-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Oracle SOA Suite Components
■ Simple Object Access Protocol (SOAP) — Provides the default network protocol
for message delivery.
See Also:
■ Section 1.4, "Introduction to an SOA Composite Application Using
SCA Technologies" on page 1-11
■ Chapter 2, "Introduction to the SOA Composite Editor" for
additional details about these key building blocks
■ The following URL for SCA and SDO specifications and related
material:
http://www.osoa.org
BI
BPEL Human BAM CEP
Task
ODI
Business EDI
Mediator
Rules
ebXML
Service / Event Delivery API
Registry HL7
Policy Manager
RosettaNet
Transformation
Service Infrastructure
MDS
Optional Adapters
Oracle Mediator (Mediator), Oracle Business Rules (Business Rules), and Oracle
Adapters plug into the Service Infrastructure, a normalized transport infrastructure,
making up the Enterprise Service Bus (ESB). With the addition of the Oracle BPEL
Process Manager (BPEL) and Human Task service components, the suite forms a
complete Business Process Management (BPM) platform. Oracle Business Activity
Monitoring (BAM) and Complex Event Processing (CEP) consume data transported
over the Service Infrastructure, providing powerful business insight capabilities.
Separately licensable products, such as Oracle Business Process Analysis Suite (BPA),
Oracle Business Intelligence (BI), Oracle Data Integrator (ODI), and other adapters
interoperate with Oracle SOA Suite components.
1-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Oracle SOA Suite Components
■ CICS
■ VSAM
■ IMS/TM
■ IMS/DB
1-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Oracle SOA Suite Components
1.3.2.1 About Using Oracle ESB with Oracle BPEL Process Manager
SOA architects have traditionally had to choose between an ESB and a BPM platform,
such as Oracle BPEL Process Manager, upon starting a new SOA project. An ESB was
seen as a lightweight, fast, stateless transport and connectivity tool, while BPM
provided some of these features along with more logic capabilities, often at the cost of
lesser performance.
With the Oracle SOA Suite, such a choice is no longer necessary. One SOA composite
application can be started as an ESB project and then enhanced with orchestration
logic using BPEL, all in a single set of artifacts, deployed on a single server. Architects
no longer need to worry about what to run where, and what patterns will require what
product when starting a new SOA project.
A typical SOA composite application uses a Mediator to create an inbound interface
that could then filter and route messages to various BPEL processes. In turn, BPEL
process would use other Mediators to fan out the results.
caches all the necessary individual, seemingly unrelated events and tries to correlate
them into specific patterns.
Users write queries using Continuous Query Language (CQL).
The potential applications of Oracle Complex Event Process are numerous, from
electronic trading and risk management to intrusion detection and compliance
monitoring.
The data provided from complex event processing queries has many uses, including
real-time Oracle BAM dashboards.
1-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Oracle SOA Suite Components
through Oracle Enterprise Manager Grid Control Console, are available in the
distribution at SOA_ORACLE_HOME/archives/applications. [[Question: Is this
location correct??]]
See Also: Section 1.3.1.3, "Oracle Adapters" on page 1-5 for details
about separately licensed adapters
these services to potential consumers, you use Oracle Application Server UDDI
Registry. The Oracle Application Server UDDI Registry meets the core service
management needs of any enterprise:
■ Enables service providers to publish and advertise their offerings
■ Allows service consumers to find, access, and invoke services that meet defined
criteria
■ Provides critical features for SOA governance
1-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to an SOA Composite Application Using SCA Technologies
BPEL
Process Business Oracle Human CEP Service Engines
Manager Rules Mediator Task (Containers that host the
component business logic)
UDDI
Service Infrastructure
(Picks up SOAP message
from binding component
and determines the
MDS intended component
target)
Table 1–1 describes the operability of the SOA composite application shown in
Figure 1–2. References are made to sections that provide additional details.
1-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to an SOA Composite Application Using SCA Technologies
See Also:
■ Section 1.2, "Introduction to Oracle SOA Suite" on page 1-1 for a
definition of the SCA assembly model
■ Section 2.2, "Creating an SOA Project in Oracle JDeveloper" on
page 2-10 for a tutorial that uses the functionality described in
Table 1–1
See Also:
■ Chapter 2, "Introduction to the SOA Composite Editor" for details
about using service and reference binding components in an SOA
project in Oracle JDeveloper
■ Section 1.3.1.4, "Business Events and the Events Delivery
Network" on page 1-6
■ Chapter 8, "Business Events and the Event Delivery Network" for
details about creating and using business events
1-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
How to Use This Guide
processing rules of these service components. Service engines process the message
information received from the Service Infrastructure.
The following service components are available. There is a corresponding service
engine of the same name for each service component. All service engines can interact
together in a single composite.
■ BPEL process — for process orchestration and storage of synchronous or
asynchronous process. You design a business process that integrates a series of
business activities and services into an end-to-end process flow.
■ Business rules — for designing a business decision based on rules.
■ Human task — for modeling a workflow that describes the tasks for users or
groups to perform as part of an end-to-end business process flow.
■ Mediator — for routing events (messages) between different components.
(provides enterprise service bus (ESB) functionality)
■ Complex Event Processing — for continuous queries on event streams
See Also: The following sections for additional details about service
components hosted by the service engines:
■ Section 2.1.3, "Introduction to Service Components" on page 2-6
■ Section 2.2.3, "Task 3: Adding a Service Component" on page 2-14
1-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
2
2 Introduction to the SOA Composite Editor
Figure 2–1 Key Entities of SCA Projects in the SOA Composite Editor
Order DB
Credit Java
Require Approval?
Human
BPEL Task
Process Service Service
Component Component
Customer Java
Manufacturer
· Operation1
· Operation2
Order Approval · Operation3
· Operation4
Business
Rule
Service
Component
Manufacturing
BPEL
Process
Service
Component
The layout shown in Figure 2–1 appears in the SOA Composite Editor during
design-time. See Figure 2–3 on page 2-10 for an example of an application in the SOA
Composite Editor.
Table 2–1 briefly describes the entities shown in Figure 2–1 and provides references to
sections that provide more specific details.
2-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the SOA Composite Editor
See Also:
■ Chapter 1, "Service-Oriented Architecture and Oracle SOA Suite"
for specific descriptions of SCA concepts
■ Oracle Fusion Middleware Administrator’s Guide for SOA Suite for
details about managing and monitoring the SOA composite
application from Oracle Enterprise Manager Fusion Middleware
Control Console
See Also:
■ Section 1.4.3, "Deployed Service Archives" on page 1-15 for
additional details about binding component services
■ Figure 2–3 on page 2-10 for an example of a service in Oracle
JDeveloper
■ Section 2.2.5, "Task 5: Adding a Service" on page 2-18 for an
example of creating a service in Oracle JDeveloper
2-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the SOA Composite Editor
Composite
Service
(Service1)
Wire
Wire
C1 Wire
Y C2
Reference
(WriteFile)
Service Service
Component Component
Type: BPEL Type: BPEL
(SayHello) (SayGoodbye)
The SOA composite application is described in the composite.xml file. This file is
automatically created when you create an SOA project and describes the entire SOA
composite. There is one composite.xml file per SOA project.
The contents of the composite.xml file for the composite shown in Figure 2–2 are
described below.
In the initial lines of the file, the service binding component that provides the entry
point to the composite is defined. For this example, a binding component Web service
named Service1 is defined. The Web service binding port for delivering messages
and policy management details are also defined.
<composite name="SayHello">
. . .
. . .
<service name="Service1">
<interface.wsdl
interface="http://xmlns.oracle.com/SayHello#wsdl.interface(SayHello)"/>
<binding.ws port=
"http://xmlns.oracle.com/SayHello#wsdl.endpoint(Service1/
SayHello_pt)"/>
</service>
In the following lines, a BPEL process service component named SayHello (C1 in
Figure 2–2) is defined:
<component name="SayHello">
<implementation.bpel src="SayHello.bpel"/>
</component>
In the following lines, a second BPEL process service component named SayGoodbye
(C2 in Figure 2–2) is defined:
<component name="SayGoodbye">
<implementation.bpel src="SayGoodbye.bpel"/>
</component>
</reference>
In the remaining lines of the file, the communication (or wiring) between service
components is described:
■ The Web service is wired to the SayHello BPEL process service component
(represented by C1 in Figure 2–2). Wiring enables Web service message
communication with this specific BPEL process.
■ The SayHello BPEL process service component (represented by C2 in Figure 2–2)
is wired to the SayGoodbye BPEL process service component.
■ The SayGoodbye BPEL process is wired to the WriteFile binding component
reference. This is the reference to the external partner in the outside world.
<wire>
<source.uri>Service1</source.uri>
<target.uri>SayHello/client</target.uri>
</wire>
<wire>
<source.uri>SayHello</source.uri>
<target.uri>SayGoodbye/client</target.uri>
</wire>
<wire>
<source.uri>SayGoodbye/WriteFile1</source.uri>
<target.uri>WriteFile</target.uri>
</wire>
2-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the SOA Composite Editor
See Also:
■ Section 1.4.2, "Service Engines and Service Components" on
page 1-14
■ Section 2.2.3, "Task 3: Adding a Service Component" on page 2-14
for an example of creating a service component in the SOA
Composite Editor
■ Section 2.2.4, "Task 4: Editing a Service Component" on page 2-16
for an example of editing a service component in Oracle
JDeveloper
■ Chapter 5, "Getting Started with Oracle Mediator" for mediator
design details
■ Chapter 11, "Getting Started with Oracle BPEL Process Manager"
for Oracle BPEL Process Manager design details
■ Chapter 26, "Designing Human Tasks" for human task design
details
■ Oracle Fusion Middleware User’s Guide for Oracle Business Rules for
business rule design details
2-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the SOA Composite Editor
See Also: Section 11.5, "Partner Link Creation and the SOA
Composite Editor" on page 11-15 for details about how creating
partner links in the BPEL process of Oracle JDeveloper impacts the
services and references in the SOA Composite Editor
See Also:
■ Section 1.4.3, "Deployed Service Archives" on page 1-15
■ Section 2.2.7, "Task 7: Adding a Reference" on page 2-22 for an
example of adding a reference in Oracle JDeveloper
2-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
Field Value
Application Name Enter an application name (for this example,
MySOAApplication is entered).
Application Template Select No Template [All Technologies].
5. Accept the default values for all remaining settings, and click OK.
The Create Project window appears.
6. Enter a name for the project (for this example, MySOAProject), click OK.
2-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
The following example describes the procedures to perform when a BPEL process is
dropped into the canvas workspace.
1. Select SOA from the Component Palette.
2. Drag a BPEL Process from the Service Components list into the canvas
workspace.
The Create BPEL Process window appears.
2-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
Field Value
Name Enter a name (for this example, SayHello is
entered).
Namespace Accept the default value.
Template Select Synchronous BPEL Process.
See Also: The online help for additional details
about available templates.
Expose as Composite Service Deselect this check box. This creates a standalone
BPEL process. If you select this check box, a BPEL
process and inbound Web service binding
component are each created and connected
together.
4. Note that the Input and Output fields also appear in the Create BPEL Process
window. These fields enable you to select or import specific input and output
schemas from the Type Chooser window or SCA Resource Lookup window,
respectively. For this example, the default schemas are used, which consist of
string input and output values. This schema defines the structure of the message
to submit.
The SCA Resource Lookup window also provides access to the Resource Palette,
which provides a single window from which to share and access schemas in
multiple applications.
5. Accept the default values for all remaining settings.
6. Click OK.
The BPEL process displays in the canvas workspace. The single arrow in a circle
indicates this is a synchronous, one-way BPEL process service component. An
asynchronous process is indicated by two arrows in a circle, with each pointing in
the opposite direction. The two arrows represent an interface and callback
interface.
You can more fully define the content of your BPEL process now or at a later time.
For this top-down example, the content is defined now.
7. Select Save All from the File main menu.
2.2.3.1 What You May Need to Know About Adding and Deleting a Service
Component
Note the following details about adding service components:
■ A service component can be newly created or used from another service
component. For example, you can create a human task within the BPEL process
service component of Oracle JDeveloper or use a human task that was already
created in the SOA Composite Editor or deployed to a server. The reference and
the wire is created to the newly created service component.
■ The Resource Palette can be used to browse for service components defined in the
SOA Composite Editor as well as those deployed. A reference and wire is created
when a service component from the SOA Composite Editor or from the deployed
list is used.
Note the following details about deleting service components:
■ You can delete a service component as follows:
– Right-clicking it and selecting Delete from the context menu
– Highlighting it and selecting Delete from the View main 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.
2-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
3. Drag and drop an Assign activity into the canvas workspace below the
receiveInput receive activity.
4. Double-click the Assign activity.
5. Click the Copy Operation tab.
6. Select Copy Operation from the drop-down list.
7. Enter the appropriate details. For this example, the following details are entered.
Field Value
From
■ Type Expression
■ Variables concat('Hello
',bpws:getVariableData('inputVariable','payload','/client:SayHelloPro
cessRequest/client:input'))
Note: Press Ctl and then the space bar to access the XPath Expression
Builder. Scroll through the list of values that appears and double-click
the value you want. As you enter information, a red underscore can
appear. This means you are being prompted for additional information.
Either enter additional information, or press the Esc key and delete the
trailing slash to complete the input of information.
To
■ Type Variable
Field Value
■ Variables Expand and select Variables > Process > Variables > outputVariable >
payload > client:SayHelloProcessResponse > client:result
8. Click OK to close the Create Copy Operation window and the Assign window.
9. Double-click composite.xml in the Application Navigator or single-click
composite.xml above the canvas workspace.
This returns you to the SOA Composite Editor.
10. Select Save All from the File main menu.
Field Value
Name Enter a name for the service (for this example, Service1 is entered).
2-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
Field Value
Type Select the type (message direction) for the Web service. Since you
dragged the Web service to the left swim lane, 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
partner link in the outside world.
Since this example describes how to create an entry point to the SOA
composite application, Service is selected.
4. Select the WSDL file for the service. There are three methods for selection:
a. Click the first icon to the right of the WSDL File field, and select an existing
WSDL file from the local file system (for this example, SayHello.wsdl is
selected). Note that the File button at the top of the window is automatically
selected.
b. Click the first icon to the right of the WSDL File field, and select Resource
Palette at the top of the window. This enables you to use existing WSDL files
from other applications.
c. Click the second icon to the right of the WSDL File field to automatically
generate a WSDL file from a schema.
Field Value
Port Type Disabled, since there is only one port type and no choice can be
made. This field would be enabled if there was more than one
port type from which to choose.
Callback Port Type Disabled, since this WSDL file is for a synchronous service.
7. Click OK.
2-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
2.2.5.1 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 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 new partner link that can be connected to a receive or an
on-message activity.
Note the following detail about deleting services:
■ When a service provided by a service component is deleted, all references to that
service component are invalidated and the wires removed.
– A component has the right to reject a new interface. For example, a mediator
can only have one inbound service. Therefore, it rejects attempts to create a
second service.
– You cannot drag an outbound service (external reference) to a business rule
because business rules do not support references. When dragging a wire, the
user interface does highlight the interfaces that are valid targets.
■ 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.
The service and reference must match, meaning the interface and the callback
must be the same.
1. Drag and drop a wire from the Service1 reference handle to the SayHello BPEL
process interface.
2.2.6.1 What You May Need to Know About Adding and Deleting Wires
Note the following detail about adding wires:
■ A service component can be wired to another service component if its reference
matches the service of the target service component. Note that the match implies
the same interface and callback interface.
Note the following detail about deleting wires:
■ When a wire is deleted, the component's reference is automatically deleted and the
component is notified so that it can clean up (delete the partner link, clear routing
rules, and so on).
2-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
See Also: Section 11.5, "Partner Link Creation and the SOA
Composite Editor" on page 11-15 for details about how creating
partner links within a BPEL process service component impacts how
partner links display in the SOA Composite Editor
2.2.7.1 What You May Need to Know About Adding and Deleting References
Note the following details about adding references:
■ The only way to add a new reference in the SOA Composite Editor is by wiring
the service component to the desired 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.
Note the following details about deleting references:
■ When a reference for a service component is deleted, the associated wire is also
deleted and the service component is notified so 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.
3. Double-click the SayHello BPEL process and note that the WriteFile reference
displays as a partner link in the right swim lane.
2-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an SOA Project in Oracle JDeveloper
The Update Interface window appears. This window shows all schemas used by
the interface’s WSDL and enables you to choose a new schema for a selected
message part.
2. Use one of the following methods to select the message schema to update.
■ Double-click the message schema row.
■ Select a row and click the Update icon in the upper right corner above the
table.
The Type Chooser window appears.
3. Select a new schema element, and click OK.
4. Click OK in the Update Interface window. This updates the interface WSDL to use
the new schemas.
2.2.9.1 What You May Need to Know About Updating Message Schemas of
Components
■ It is possible that several operations (or an input and an output) can use the same
WSDL message. In this case, the same message is seen in multiple rows of the
table. If you update the schema in one row, the change appears in the other rows.
See Also:
■ Section 3.5, "Testing Applications" on page 3-8 for instructions on
testing a SOA composite application
■ Section 3.6, "Troubleshooting Applications" on page 3-8 for
instructions on troubleshooting application errors
2-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
3
3 Life Cycle of an Application
This chapter provides details about the entire life cycle of an application.
This chapter contains the following topics:
■ Section 3.1, "Introduction to Application Life Cycles"
■ Section 3.2, "Methods for Designing Applications"
■ Section 3.3, "Considerations for Collaborative Development"
■ Section 3.4, "Deploying Applications"
■ Section 3.5, "Testing Applications"
■ Section 3.6, "Troubleshooting Applications"
3-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying Applications
Field Value
Revision ID Enter the revision ID value to use. This value is added to the JAR
file name of the deployed SAR profile name.
Revision Check Box Select this check box if you want to use the specified revision ID
value continually without being prompted again during
deployment.
If you do not select this check box, you are prompted to specify a
revision number when the application profile is deployed.
This functionality is similar to the BPEL process versioning feature
of previous releases, but at the higher SOA composite application
level.
7. Click OK to close the SAR Deployment Profile Properties window and the Project
Properties window.
Field Value
Archive Type Select OAR File. This type must be selected. An OAR file is an
Oracle Application archive file.
Name Enter a deployment profile name.
Note: You can change the deployment profile name at a later time by
selecting the General tab in the OAR Deployment Profile Properties
window and changing the name in the Application name field.
5. Click OK.
The deployment profile displays in the Application Properties window.
3-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying Applications
6. Click Edit.
7. Click Application Assembly.
All SOA projects in this application display in the Java EE Modules section. For
this example, there is only one application (named sca_MySOAComposite).
8. Select the SOA projects to include in the deployment profile.
You must select a project. Otherwise, the generated EAR file is empty. The EAR file
is what is deployed to Oracle Application Server.
9. Click OK to close the OAR Deployment Profile Properties and Application
Properties windows.
4. Provide a response when prompted for the revision number of the application.
5. Click OK.
The Deployment Plan window appears.
6. Perform the following procedures based on the component to which you are
deploying:
■ If you are deploying to a standalone OC4J instance, do not modify any
parameters.
■ If you are deploying to the Middleware Administration Server (MAS), click
MDS Configuration and select the Metadata Service (MDS) repository.
7. Click OK.
8. If you are deploying an application profile that was previously deployed, you are
prompted to undeploy and redeploy the new version of the profile. If you select
not to redeploy, deployment does not proceed any further.
3-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying Applications
9. View the messages that display in the Log window at the bottom of Oracle
JDeveloper.
If deployment is successful, the following files are created:
■ An EAR file under the application_name > deploy folder in Windows
Explorer with a naming convention of deployment_profile_name.ear (for
example, MyDeployProfile.ear).
■ JAR files for each of the SOA projects in the EAR file are created under the
deploy folder in Oracle JDeveloper with a naming convention of sca_project_
name_revision_number_.ear (for example, sca_MySOAComposite_rev1.0.jar)
This JAR file can also be viewed in the project_name > deploy directory in
Windows Explorer:
You are now ready to run your application from Oracle Enterprise Manager Grid
Control Console.
If deployment is unsuccessful, view the messages that display in the Log window
and take corrective actions. See Section 3.6.3, "Viewing Deployment Error Files" on
page 3-16 for details about files that are provided for debugging deployment
errors.
See Also: Oracle Fusion Middleware Order Demo Developer's Guide for
Oracle SOA Suite for additional information on debugging
applications
3-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Troubleshooting Applications
3.6.1.1.1 fault-policies.xml This file defines fault conditions and their corresponding
actions. Each fault policy consists of condition and action sections. Both sections
enable you to define one or more fault conditions and actions, respectively. Each fault
condition specifies a particular fault or group of faults, which it attempts to handle,
and the corresponding action for it.
. . .
. . .
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
name="bpelx:remoteFault">
<condition>
<!-- Condition with a filter criteria -->
<test>$fault.code/code="WSDLReadingError"</test>
<action ref="ora-terminate"/>
</condition>
<condition>
<!-- Catch all condition for remoteFault -->
<action ref="ora-java"/>
</condition>
</faultName>
. . .
. . .
All actions defined in the condition section must be associated with an action in the
action section.
Each action has a user-defined unique ID and is based on a system-defined action.
Action IDs must be unique across a fault policy. Each action ID can have its own set of
attributes. The following syntax shows several attributes, including retryCount and
retryInterval. Available system actions are retry, human intervention (recoverable
from Oracle Enterprise Manager Grid Control Console), replay, rethrow, Java callout
and abort. The following syntax shows examples of retry and Java callout.
. . .
<Actions>
<Action id="ora-retry">
<!-- User defined unique id -->
<retry>
<!-- System defined action -->
<retryCount>3</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff/>
<!-- System defined action atttributes -->
<retryFailureAction ref="ora-java"/>
<retrySuccessAction ref="ora-java"/>
</retry>
</Action>
<Action id="ora-java">
<javaAction
className="com.oracle.bpel.client.config.faultpolicy.TestJavaAction"
defaultAction="ora-terminate"
propertySet="prop-for-billing">
<returnValue value="ABORT" ref="ora-terminate"/>
<returnValue value="RETRY" ref="ora-retry"/>
The order of precedence for fault bindings resolution is reference binding component,
port type, service component, and composite, if all are defined in the same
fault-bindings.xml file. If you have only defined a fault policy on a single
composite in the fault-bindings.xml file, all service components, port types, and
reference binding components of that composite use the same fault policy.
3-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Troubleshooting Applications
Note:
■ The fault policy framework, if defined, takes precedence over the
fault handling features of BPEL processes described in this
section.
■ Business faults (defined through the WSDL file) in Oracle
Mediator are currently handled through routing rules (as was the
case in 10.1.3).
3.6.1.3 Recovering from Faults in Oracle Enterprise Manager Grid Control Console
After defining your fault policy in the fault-policies.xml and fault-bindings.xml files,
you perform fault recovery for a SOA composite application from Oracle Enterprise
Manager Grid Control Console.
3.6.2.1.1 log_handlers section The log_handlers section displays at the top of the
j2ee-logging.xml file. The BPEL process, human task, business rule, Oracle Mediator,
and notification service use the OC4J log handler properties (oc4j-handler):
. . .
. . .
<log_handlers>
<log_handler name='oc4j-handler'
class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='../log/oc4j'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
<property name='encoding' value='UTF-8'/>
<property name='supplementalAttributes' value='J2EE_APP.name,J2EE_
MODULE.name,WEBSERVICE.name,WEBSERVICE_PORT.name'/>
</log_handler>
The path value specifies the directory in which to write log information. In this
example, the directory is ORACLE_HOME\j2ee\home\log\oc4j. Logging output is
always written to a file named log.xml file.
The maxFileSize value specifies the maximum size of the log file. The maxLogSize
value specifies the maximum number of log files. For example, if maxFileSize is set to
10 MB and maxLogSize is set to 20 MB, you can have two log files that add up to 20
MB in size. When this limit is reached, the files are recycled and restarted at 0 MB.
3.6.2.1.2 loggers section The loggers section lets you set the logging properties and
levels for individual components. In the following example, Web services auditing
logging is set to NOTIFICATION:1.
<loggers>
. . .
. . .
<logger name='oracle.webservices.management.auditing' level='NOTIFICATION:1'
useParentHandlers='false'>
<handler name='oracle-webservices-management-auditing-handler'/>
</logger>
3-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Troubleshooting Applications
3.6.2.3.1 Setting BPEL Process Logging BPEL process logging is enabled by specifying
the properties described in Table 3–3 on page 3-14. For example, you add the following
block of code for the oracle.orabpel.system and oracle.orabpel.domain
properties to the loggers section and set their logging levels to NOTIFICATION:1 as
follows:
<loggers>
. . .
The console-handler setting for both of these properties enables you to also output
logging information to a DOS window or Linux shell.
Table 3–3 describes the BPEL process properties that you can add to the loggers
section.
3-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Troubleshooting Applications
3.6.2.3.2 Setting Human Task, Business Rule, and Notification Service Logging Human task,
business rule, and notification service logging is enabled by adding the following
block of code for the oracle.orabpel.services property. In the following
example, the logging level for this property is set to NOTIFICATION:1:
<loggers>
.......
<logger name="oracle.bpel.services" level="NOTIFICATION:1"
useParentHandlers="false">
<handler name="oc4j-handler"/>
<handler name="console-handler"/>
</logger>
</loggers>
</logging_configuration>
3.6.2.3.3 Setting Oracle Mediator Logging Oracle Mediator logging is enabled by adding
the following block of code for the oracle.tip.mediator.dispatch property. In
the following example, the logging level for this property is set to NOTIFICATION:1:
<loggers>
.......
<logger name='oracle.tip.mediator.dispatch' level='NOTIFICATION:1'
useParentHandlers='false'>
<handler name='oc4j-handler'/>
<handler name="console-handler"/>
</logger>
class='java.util.logging.ConsoleHandler'
formatter='oracle.core.ojdl.logging.SimpleFormatter' level=’TRACE:1’/>
3-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Part II Enterprise Service Bus Infrastructure
This part describes the components that comprise the Enterprise Service Bus
Infrastructure.
This part contains the following chapters:
■ XSLT Mapper
– Chapter 4, "XSLT Mapper and Transformations"
■ Oracle Mediator
– Chapter 5, "Getting Started with Oracle Mediator"
– Chapter 6, "Creating Routing Rules"
– Chapter 7, "Oracle Mediator Error Handling"
■ Oracle Business Events
– Chapter 8, "Business Events and the Event Delivery Network"
■ Domain-Value Maps
– Chapter 9, "Working with Domain Value Maps"
■ Cross References
– Chapter 10, "Working with Cross References"
Beta Draft
Beta Draft
4
4 XSLT Mapper and Transformations
This chapter describes features of the XSLT Mapper. The XSLT Mapper enables you to
create data transformations between source schema elements and target schema
elements in either Oracle BPEL Process Manager or Oracle Mediator. This chapter
provides step-by-step instructions for mapping a sample purchase order schema to an
invoice schema.
This chapter includes the following sections:
■ Section 4.1, "Introduction to the XSLT Mapper"
■ Section 4.2, "Creating an XSL Map File"
■ Section 4.3, "Using the XSLT Mapper"
■ Section 4.4, "Testing the Map"
■ Section 4.5, "Use Case for Transformation"
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 Figure 4–1 (for example, type, cardinality, and so on).
The Component Palette in the upper right of Figure 4–1 is the container for all
functions provided by the XSLT Mapper. The mapper pane or canvas 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 Mapper 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 tabs at the bottom of the mapper
pane.
While in design view, the following pages from the Component Palette can be used:
■ General — Commonly used XPath functions and XSLT constructs
■ Advanced — More advanced XPath functions such as database and
cross-reference functions
4-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the XSLT Mapper
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 4–3.
The 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 4–3. This results in a value-of
statement in the XSLT, as shown in Example 4–1.
■ The First and Last name fields from the source tree in Figure 4–3 are concatenated
together 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 4–2:
■ Note the inserted XSLT for-each construct in the target tree in Figure 4–3. For each
HighPriorityItems/Item in the source tree, a ShippedItems/Item element is
created in the target tree and ProductName and Quantity are copied for each. The
XSLT shown in Example 4–3 is generated:
4-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the XSLT Mapper
The line linking Item in the source tree to the for-each construct in the target tree
in Figure 4–3 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.
Note that the XPath expressions in the value-of statements below the for-each
construct are relative to the XPath referenced in the for-each. In general, the XSLT
Mapper creates relative paths within for-each statements.
If you need to 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 mapper does not modify it.
The entire XSLT map generated for this example is shown in Example 4–4:
Subsequent sections of this chapter describe how to link source and target
elements, add XSLT constructs, and create XPath expressions in design view.
Note: You can also create an XSL map file from an XSL stylesheet.
Click New > General > XML > XSL Map From XSL Stylesheet from
the File main menu in Oracle JDeveloper.
4.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.
1. Drag and drop a transform activity from the Component Palette into your BPEL
process diagram. Figure 4–4 provides an example.
4-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an XSL Map File
4.2.2 How to Create an XSL Map File from Imported Source and Target Schema Files in
Oracle BPEL Process Manager
The following steps provide a high level overview of how to create an XSL map in
Oracle BPEL Process Manager using a po.xsd and invoice.xsd file.
1. In Oracle JDeveloper, select the application project in which you want to create the
new XSL map.
2. Import the po.xsd and invoice.xsd files into the project (for example, by
right-clicking Schemas and selecting Import Schemas in the Structure section of
Oracle JDeveloper).
3. Right-click the selected project and select New.
The New Gallery window appears.
4. In the Categories tree, expand General and select XML.
5. In the Items list, double-click XSL Map.
The Create XSL Map File window appears. This window enables you to create an
XSL map file that maps a root element of a source schema file or WSDL file to a
root element of a target schema file or WSDL file.
– 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).
4-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an XSL Map File
6. Enter a name for the XSL map file in the File Name field.
7. Under Source, expand Project Schema Files > po.xsd > PurchaseOrder as the root
element for the source.
8. Under Target, expand Project Schema files > invoice.xsd > Invoice as the root
element for the target. Figure 4–6 provides an example.
9. Click OK.
A new XSL map is created, as shown in Figure 4–7.
10. Save and close the file now or begin to design your transformation. Information on
using the XSLT Mapper is provided in Section 4.1, "Introduction to the XSLT
Mapper" on page 4-1.
11. Drag and drop a transform activity from the Component Palette into your BPEL
process.
12. Double-click the transform activity.
4-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an XSL Map File
The appropriate Transformation Map window 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 4–9 appears.
If the routing rule includes a synchronous reply or fault, the Reply Transformation
Map window or Fault Transformation Map window contains the Include Request
in 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.
5. Click OK.
4-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
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 4.1, "Introduction to the XSLT Mapper" on page 4-1 for an overview
of using the XSLT Mapper.
You can directly launch the XSLT Mapper by double-clicking on a data transformation
icon in a mediator icon in the Design tab. If the transformation exists, the XSLT
Mapper opens for you to update the transformation file. If the transformation file has
not been specified yet, the Request Transformation Map window displays and enables
you to create a new transformation file or select an existing transformation map file for
update.
4. Click Select in the Source Schema section to select a schema for the new source.
The Type Chooser window 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 window.
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 4–13 to
view the structure of the underlying schema.
4-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
For more information about the fields, see the online Help for the Set Text dialog.
and named templates. The extension functions are prefixed with xp20 or orcl and
mimic XPath 2.0 functions.
Perform the following steps to view function definitions and use a function:
1. Select a category of functions (for example, String Functions) from the
Component Palette.
2. Right-click an individual function (for example, lower-case).
3. Select Help. A dialog with a description of the function appears, as shown in
Figure 4–16. You can also click a link at the bottom to access this function’s
description at the World Wide Web Consortium at www.w3.org.
4. Drag a concat function into the mapper pane. This function enables you to connect
the source parameters from the source tree to the function and the output of the
function to the node on the target tree.
5. Concatenate PurchaseOrder/ShipTo/Name/First and
PurchaseOrder/ShipTo/Name/Last. Place the result in Invoice/ShippedTo/Name
by dragging threads from the first and last names and dropping them on the left
side on the concat function. Also drag a thread from the ShippedTo name and
connect it to the right side on the concat function, as shown in Figure 4–17.
4-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
For more information about how to add, remove, and reorder function parameters, see
the online Help for the Edit Function dialog.
For more information about including templates defined in external files, see
Section 4.3.6.6, "Including External Templates with xsl:include."
1. Create an XML extension function configuration file. This file defines the functions
and their parameters. For example, the XML code shown in Example 4–5 is from
the SampleExtensionFunctions.xml file.
</functions>
</extension-functions>
4-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
JDeveloper class path. For example, to use the sample functions, copy
SampleExtensionFunctions.jar to the patches directory.
4. Go to Tools > Preferences > XSL Map in Oracle JDeveloper and add your
extension function configuration XML file name to the User Defined Extension
Functions Config File field. (For example, to use the sample functions, add
SampleExtensionFunctions.xml).
5. Restart Oracle JDeveloper.
New functions appear in the Component Palette under the User Defined page in
the User Defined Extension Functions group. If you are using the sample
functions, replaceChar() and toKilograms() appear under the User Defined page
in the User Defined Extension Functions group when an XSL map is open.
6. If the XSL generated by the XSLT Mapper is to be used by Oracle Application
Server, add the JAR file to the Oracle Application Server class path. For OC4J,
copy the JAR file to the following location:
$INSTANCE_HOME/OC4JComponent/oc4j_soa/applib
When you double-click the icon, the Edit XPath Expression window appears, as shown
in Figure 4–21. You can press the Ctrl key and then the spacebar to invoke the XPath
Building Assistant.
4-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
For more information about using the XPath Building Assistant, see the online Help
for the Edit XPath Expression dialog.
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. In previous sections, the following methods for mapping
elements and attributes were described:
■ Creating a simple copy by linking nodes
■ Adding functions
■ Adding XPath expressions
Each of these methods creates 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.
The following sections describe specific steps for inserting each supported XSLT
construct.
■ Section 4.3.6.1, "Using Conditional Processing with xsl:if"
■ Section 4.3.6.2, "Using Conditional Processing with xsl:choose"
■ Section 4.3.6.3, "Creating Loops with xsl:for-each"
■ Section 4.3.6.5, "Copying Nodes with xsl:copy-of"
■ Section 4.3.6.6, "Including External Templates with xsl:include"
4-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
4-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
The behavior of the auto map can be tuned by altering the settings in Oracle
JDeveloper preferences or by right-clicking the transformation window and selecting
Auto Map Preferences. This displays the window shown in Figure 4–27.
4-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
For more information on the fields, see the online Help for the Auto Map dialog.
4-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
For more information about the fields, see the online Help for the Auto Map dialog.
4-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
■ Variables are created in the target tree, and are either global or local. Where they
are defined in the target tree determines if they are global or local.
– Global variables are defined immediately below the <target> node and
immediately above the actual target schema (for example, POAcknowledge).
Right-click on the <target> node to create a global variable.
– Local variables are defined on a specific node below 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.
3. Click OK.
window. 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 position selected.
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.
4-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
The first match found is highlighted, and the Find window 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.
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 following syntax:
<elements-to-ignore>
<element name="myElement"/>
<element name="myOtherElementWithNS" namespace="NS"/>
</elements-to-ignore>
4-34 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the XSLT Mapper
</complexType>
<complexType name="USAddress">
<complexContent>
<extension base="ipo:Address">
<sequence>
<element name="state" type="string"/>
<element name="zip" type="positiveInteger"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="UKAddress">
<complexContent>
<extension base="ipo:Address">
<sequence>
<element name="postcode" type="string"/>
</sequence>
<attribute name="exportCode" type="positiveInteger" fixed="1"/>
</extension>
</complexContent>
</complexType>
3. Select Substitute a type derived from type to display a list of possible global types
for substitution. To remove a substitution, select Make no Substitution. If you
select Make no Substitution, note the following details:
■ If no type was substituted for the base type and this is the first time you are
seeing this window, the behavior is the same as clicking Cancel.
■ If a type was substituted earlier and you are returning to this window, a
warning message appears indicating that if you continue, your mappings are
removed. Click Yes to continue. All mappings under the node are removed
and you can continue from there.
4. Click OK.
The originally-selected element becomes uneditable in design view and appears
grayed out in the tree. The type that is substituted is indicated. For example, the
tree shown in Figure 4–36 indicates that the billTo element, which was defined as
the Address type, has now been substituted with the USAddress type.
5. Switch to source view and note that the code shown in Example 4–8 appears for
the billTo element:
6. Add your own mapping code below the comment. Example 4–9 provides an
example.
4-36 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Testing the Map
</state>
<zip>
<xsl:value-of select="/ipo:purchaseOrder/billTo/zip"/>
</zip>
</billTo>
7. Switch back to design view. Your code is preserved, and not removed. However,
the code is only editable in source view.
Note that no features are provided to perform type substitution on the source schema.
However, it is possible to create an XPath statement referencing nodes in the source
tree that are not defined in the XSD. This XPath should not create an error, but should
be kept as a constant XPath expression. An XPath of this type can be created using the
xpath-expression function under the Advanced page/Advanced Function group of
the Component Palette.
1. Choose to allow a sample source XML file to be generated for testing or click
Browse to specify a different source XML file in the Source XML File field.
When you click OK, the source XML file is validated. If validation passes,
transformation occurs, and the target XML file is created.
If validation fails, no transformation occurs and a message displays on-screen.
2. Select the Generate Source XML File check box to create a sample XML file based
on the map source XSD schema.
3. Select the Show Source XML File check box 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 tables 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 check
box if you want to generate a file.
b. If the Parameters Without Schema table appears, you can specify a value by
selecting the Specify Value check box and making appropriate edits to the
Type and Value columns.
4. Enter a file name in the Target XML File field or browse for a file name in which to
store the resulting XML document from the transformation.
5. Select the Show Target XML File check box to display the target XML file for the
test. The target XML file displays in an Oracle JDeveloper XML editor.
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.
4-38 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Testing the Map
7. Click OK.
The test results shown in Figure 4–39 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.
For more information about the fields, see the online Help for the Generate Report
dialog.
In addition, you can also unselect the Open Report option on the Generate Report
window before generating the report.
4-40 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Case for Transformation
than the value of the maxOccurs attribute for a particular element, the number of
occurrences created for that particular element is the maxOccurs value, not the
specified number.
■ Generate optional elements
If selected, any optional element (its attribute minOccurs set to a value of 0) is
generated the same way as any required element (its attribute minOccurs set to a
value greater than 0).
■ 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.
4-42 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
5
Getting Started with Oracle Mediator
5
This chapter provides an overview of Oracle Mediator and describes how to create an
Oracle Mediator service component by using a service invocation or an event
subscription as entry point.
This chapter includes the following topics:
■ Introduction to Oracle Mediator
■ Overview of Mediator Designer Environment
■ Creating a Mediator Component
■ Generating a WSDL File
■ Specifying Operation or Event Subscription Properties
■ Modifying a Mediator component
■ Deleting a Mediator component
Beta Draft 1
5.2 Overview of Mediator Designer Environment
You can create a Mediator component in the SOA Composite Application of Oracle
JDeveloper and then design it by using the Mediator Editor, which is displayed, when
you double-click a Mediator component in SOA Composite Editor.
Figure 5–1 shows the Mediator Editor along with Application Navigator, Structure,
and Messages windows.
Each section of the view shown in Figure 5–1 enables you to perform specific design
and deployment tasks. The following list describes these sections and their
functionality:
■ Application Navigator
The Application Navigator shown in the upper left part of Figure 5–1 displays the
Mediator component files. Figure 5–2 shows the files that appear under the SOA
Content folder when you create a Mediator component in a SOA Composite
application.
■ History Window
The History window enables you to perform tasks as viewing the revision history
of a file and viewing read-only and editable versions of a file side-by-side. Click
Beta Draft 3
History at the bottom of the Design window shown in Figure 5–1 to open the
History window. Figure 5–3 shows the History view for a Mediator component
file.
■ Property Inspector
The Property Inspector shown at the bottom of Figure 5–1 enables you to view
details about Mediator component properties.
■ Structure Window
The Structure Window shown in the lower left part of Figure 5–1 provides a
structural view of the data of a Mediator component.
■ Log Window
The Log Window displays messages about the status of validation and
compilation.
Beta Draft 5
5.3.3 Creating a Mediator with One-Way Interface Definition
A Mediator component supports one-way interaction. In a one-way interaction, the
client sends a message to the service, and the service does not need to reply.
5.3.3.2 What Happens When You Create a Mediator Component with One-Way
Interface Definition
A Mediator component for one-way interaction with port types defined for input
message is created. Figure 5–5 shows how a Mediator created with one-way interface
looks like in Mediator Editor. The arrows to the left of the execute operation in
Figure 5–5, represent a one-way operation.
5.3.4.2 What Happens When You Create a Mediator Component with Synchronous
Interface Definition
A Mediator component with port types defined for request message is created. In a
synchronous interaction, because the response is sent to the same port as request, only
one port is defined. Figure 5–5 shows how a Mediator created with synchronous
interface looks like in Mediator Editor. The arrows to the left of the execute operation
in Figure 5–5, represent a synchronous operation.
Beta Draft 7
5.3.5.1 How to Create a Mediator with Asynchronous Interface Definition
You can create a Mediator for asynchronous interaction by using the Asynchronous
Inteface template in the Create Mediator dialog.
5.3.5.2 What Happens When You Create a Mediator Component with Asynchronous
Interface Definition
A Mediator component for asynchronous interaction with port types defined for
request and response message is created. Figure 5–6 shows how a Mediator created
with asynchronous interface looks like in Mediator Editor. The Port Type field displays
the port on which the request message is sent. Callback Port Type displays the port on
which the response is sent. The arrows to the left of the execute operation in
Figure 5–6, represent an asynchronous operation.
7. Select one or more events in the Event field as shown in Figure 5–7, and click OK.
Beta Draft 9
■ immediate: Events are delivered on the same thread and on the same
transaction as the caller.
9. Enter a security role under which an event subscription is run. By default, event
subscription runs under the security of the event publisher $publisher.
10. To filter the event, perform any of the following:
The Filter column of the Create Mediator dialog box is populated as shown in
Figure 5–9.
A Mediator component is created as shown in Figure 5–10. An icon on the left side
indicates that Mediator component is configured for an event subscription.
Beta Draft 11
5.4 Defining Interface for an Empty Mediator Component
You can define the interface of an empty mediator by subscribing to events or by
defining services.
To subscribe to events:
1. Double-click the Mediator component in SOA Composite Editor.
The Mediator editor is displayed.
2. Click Add to the right of Event Subscriptions.
The Subscribed Events dialog box is displayed.
3. Click Add.
The Event Chooser dialog box is displayed.
4. Click Search to the right of the Event definition field and select an .edl file.
The Event field is populated with the events defined in the .edl file.
5. Select one or more events and click OK.
6. In the Consistency list, select a level of delivery consistency for the event.
7. In the Run as Roles field, enter a security role under which an event subscription is
run.
8. Double-click the Filter field to specify an expression for filtering the event.
9. Click OK.
You can also use the Define Service option in the Mediator Editor to define services for
a mediator component.
Beta Draft 13
To define service for a Mediator component in Mediator Editor:
1. Double-click the Mediator component in SOA Composite Editor.
The Mediator editor is displayed.
2. Click Add to the right of WSDL File.
The Define Service dialog box is displayed, as shown in Figure 5–14.
3. Click Find Existing WSDLs to use an existing WSDL file or Generate WSDL
From Schema(s) to create a new WSDL file.
2. Expand the Project Schema Files and Project WSDL Files nodes to locate the
schema that you want to use.
You can also import a schema XSD file or WSDL file into a project by using the
Import Schema File or Import WSDL icons respectively.
Beta Draft 15
Note: If you want to use a schema XSD file that resides on your local
file system, then ensure that the XSD file, and any XSD files that it
imports, all reside in the Oracle JDeveloper project directory.
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.
3. Select the root element of the XSD file and click OK.
4. In the Operation Name field, enter the operation name. For example:
executeQuery
Oracle JDeveloper converts the specified operation into an operation element in
the WSDL file.
Beta Draft 17
Figure 5–18 Refresh WSDL Dialog with Updated Operations
3. Click OK.
4. From the File menu, select Save All.
3. Click OK.
4. From the File menu, select Save All.
Beta Draft 19
20 Product Title/BookTitle as a Variable Beta Draft
6
Creating Routing Rules
6
This chapter provides an overview of mediator routing rules and describes how to
specify routing rules for an Oracle Mediator service component (Mediator
component).
This chapter includes the following topics:
■ Section 6.1, "Introduction to Routing Rules"
■ Section 6.2, "Defining Routing Rules"
■ Section 6.3, "Creating CustomerRouter Mediator for Routing Messages"
When you configure routing rules, you can specify the following details:
■ Target service
The service to which the message should be sent. See Section 6.2.1.1, "Specifying
Target Service" for more information about how to invoke a target service.
■ Filter expression
The filter expression to be applied. A filter expression specifies that the contents
(payload or headers) of a message be 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. See Section 6.2.1.2,
"Specifying Expression for Filtering Messages" for information about how to
specify filter expressions.
■ Execution type
Beta Draft 1
Specify the way in which routing rules are executed. You can specify either of the
following execution types: sequential or parallel.
See Section 6.2.1.3, "Specifying Sequential or Parallel Execution" for information
about how to specify an execution type.
■ Schematron based validations
Specify the schematron files for validating different parts of an inbound message.
See Section 6.2.1.4, "Using Semantics Validation" for information about how to
perform schematron based validations.
■ Transformations
Document transformation to be applied. You can use transformation to set a value
on the target payload. You can perform transformation by using mappings or by
assigning values.
The XSLT mapper enables you to transform data from one XML schema to
another, thus enabling data interchange among applications using different
schemas. However, to set the target message properties irrespective of the source
properties, payload part or constants, you can use the assign value feature. See
Section 6.2.1.5, "Creating Transformations" and Section 6.2.1.6, "Assigning Values"
for information about how to create transformations.
■ Reply, callback, and fault handlers
You can specify how to handle synchronous reply, callback, and fault messages.
See Section 6.2.1.7, "Handling Response Messages" for information about
synchronous reply, callback, and fault messages handling.
The icons in the Routing Rules panel are summarized in Figure 6–2.
Beta Draft 3
6.2.1.1 Specifying Target Service
A target service specifies the next service to which a mediator should send the
message and the operation to perform on that message when it reaches the target
service.
You can specify multiple routings to one inbound operation or event. Each routing is
mapped to one target service invocation or event. Therefore, if you want to specify
multiple service invocations or raise multiple events, you must specify one routing
rule for each target service operation. For example, based on a message payload, you
want to invoke an operation from the following operations defined in a service:
■ insert
■ update
■ updateid
■ delete
You need to create four routings, one for each operation. Later, when you specify a
filter expression, you can specify which target service and operation is applied to each
message instance on the basis of the message payload as shown in Figure 6–3.
2. Click Service.
3. In the Target Services dialog, navigate to, and then select an operation provided
by a service, as shown in Figure 6–5.
4. Click OK.
Beta Draft 5
The Event field is populated with the events defined in the selected file as shown
in Figure 6–6.
5. Select an event.
6. Click OK.
The Expression Builder dialog contains the components and controls that assist you in
designing a filter expression. Briefly, you 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.
The following list describes each of the fields in the Expression Builder dialog:
■ Expression field
You can enter the filter expression – either manually, or by using the Variable field
and the Functions palette in this field.
The icons on the upper right side of this field enable you to undo the last edit
made, redo the last edit made, or clear the entire Expression field, respectively.
■ Variables field
This field contains the message defined for a Mediator component. Oracle
JDeveloper parses the Mediator component WSDL file and presents the message
definition in the Variables field. The input message is stored in the $in variable.
You can use $in.properties to access properties of an input message.
An input message can consists of multiple parts. You can use $in.<partname>
to access a part of an input message.
■ Functions Palette
This list enables you to select different functions to include in an expression. When
you select a function, a preview of how that function will appear when added to
the Expression field is presented in the Content Preview field, and a description of
the function is presented in the Description field.
Beta Draft 7
■ Content Preview
This field indicates how a value selected from the Variables field or Functions
palette will appear when it is inserted into the Expression field.
■ Description
This field provides a description of a value selected from the Variables field or
Functions palette.
To specify a filter expression on a message payload, follow these steps:
1. In the Routing Rules panel, click the Add Filter Expression icon, shown in
Figure 6–2.
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, CustomerID
element is shown selected in Figure 6–8.
4. From the Function list, select the function that you want 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 6–9. When you select a function
within the Logical Functions list, a description of that function is presented in the
Description box.
5. Click Insert Into Expression.
The XPath expression for the selected function is inserted in to the Expression
field.
6. Complete the expression. In this example, a value of 1001 is entered, as shown in
Figure 6–10.
Beta Draft 9
Figure 6–10 Sample Expression Builder Dialog – Value Entered
7. You can edit the expression manually, or use the expression editing icons, which
are summarized in Figure 6–11.
8. Click OK.
The expression is added to the Routing Rule panel.
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.
6. Click OK.
The Validation dialog is updated, as shown in Figure 6–13.
Beta Draft 11
7. Click Add to specify a schematron file for another message part or click OK.
When you select this option, an $initial variable is created which contains the
original message of a synchronous interaction as shown in Figure 6–15.
An initial message can also consists of multiple parts. You can use
$initial.<partname> to access a part of the initial message.
For information about the Data Mapper tool, see Chapter 4, "XSLT Mapper and
Transformations".
To set the properties of the target message, perform the following tasks:
1. Click Add in the Assign Values dialog.
The Assign Value dialog is displayed as shown in Figure 6–17.
■ Constant: Select this option to assign a constant value to the target message.
Beta Draft 13
3. In the To section, select any of the following options:
■ Property: Select this option to copy the value to a message property.
■ Expression: Select this option to copy the value to an expression. When you
click the Invoke Expression Builder icon to the right of Expression field, the
Expression Builder dialog is displayed. The Variable field of the Expression
Builder dialog contains an $out variable which contains the output message.
You can use $out.properties to access properties of an output message
and $out.<partname> to access a part of an output message.
Figure 6–18 shows a sample Assign Value dialog in which a constant value
output.csv is specified as the name for an outbound file written by a file
adapter service.
4. Click OK in the Assign Value dialog. The Assign Values dialog is populated as
shown in Figure 6–19.
5. Click OK. The expression is added to Assign Values field of the Routing Rules
panel.
Beta Draft 15
Figure 6–20 Overview of CustomerRouter Use Case
4. In the Application Name field, enter CustomerRouter, and then click OK.
The Create Project dialog is displayed.
5. In the Project Name field, enter CustomerRouterProject and click OK.
6. Right-click in the Applications Navigator pane and select New.
The New Gallery dialog is displayed.
7. From the Categories navigator, select SOA Tier.
8. From the Items list, select SOA Composite.
9. Click OK.
The Create SOA Composite dialog is displayed.
10. From the Composite Template list, select Empty Composite and then click OK.
Oracle JDeveloper is displayed, as shown in Figure 6–22. The Applications
Navigator is updated with the new application and project and the Design Tab
contains, a blank palette.
Beta Draft 17
Figure 6–22 Oracle JDeveloper – Application and SOA Project Added
Beta Draft 19
Figure 6–23 Type Chooser - CustomerData
Beta Draft 21
Figure 6–25 Mediator Component with Adapter Services and References
3. In the Routing Rules section, click Add to the extreme right side of ReadFile.
The Target Type dialog is displayed.
4. Select Service.
The Target Services dialog is displayed.
5. Navigate to CustomerRouterProject, References, USCustomer and select
WriteFile as shown in Figure 6–28.
Beta Draft 23
6. Click OK.
The Routing Rules panel is displayed, as shown in Figure 6–29.
7. Click the filter icon next to the <<Filter Expression>> field to create a filter
expression for this routing rule.
The Expression Builder dialog is displayed.
8. In the Variables field, navigate to Variables, in, CustomerData and then select
Country.
9. Double-click Country.
The Country node is added in the Expression text field as shown in Figure 6–30.
12. Click the icon to the right of the Using Transformation field.
The Request Transformation Map dialog is displayed, as shown in Figure 6–32.
Beta Draft 25
Figure 6–32 Request Transformation Map
14. Drag and drop the imp1:CustomerData source element to imp1:Customer target
element.
The Auto Map Preferences dialog is displayed.
15. From the During Auto Map options, deselect Match Elements Considering their
Ancestor Names.
The Auto Map Preferences dialog is shown in Figure 6–34.
Figure 6–36 shows how the mediator editor would appear after you have specified
CanadaCustomer reference as target service.
Beta Draft 27
Figure 6–36 Routing Rules Panel with Target Services Defined
After performing all the steps mentioned in this section, the SOA composite editor
would appear as shown in Figure 6–20.
6. Click Next.
The Connection Authentication page is displayed.
7. Enter the following details:
■ Username: Accept the default value of oc4jadmin.
■ Password: Enter welcome1.
8. Click Next. The Create Application Server Connection page is displayed.
9. Enter the local host name on which the Oracle SOA Suite infrastructure is
installed.
10. Click Next.
11. Click Test Connection.
The following message should appear:
Success!
If the test is unsuccessful, ensure that Oracle Application Server is running, and
retry the test.
12. Click Next.
Beta Draft 29
6.3.2 Running and Monitoring the CustomerRouterProject Application
After deploying the CustomerRouterProject application, you can run it by
copying the input xml files to the input folder. Based on the payload, the files will be
written to the specified output directories.
For monitoring the running instance, you can use the SOA Console at the following
URL:
http://hostname:8888/SOAConsole
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure.
In the SOA Console, you can click the CustomerRouterProject to see the project
dashboard as shown in Figure 6–38.
You can also navigate through the Last 5 instances section to open the instance of your
choice.
To view the detailed execution trail of the CustomerRouter mediator, click the
instance id in the instance column. The Audit Trail page is displayed as shown in
Figure 6–39.
Beta Draft 31
32 Product Title/BookTitle as a Variable Beta Draft
7
7Oracle Mediator Error Handling
Oracle Mediator provides sophisticated error handling capabilities that enables you to
configure an Oracle Mediator service component(mediator component) for error
occurrences and corresponding corrective actions. This chapter describes how to
handle errors with Oracle Mediator.
This chapter contains the following topics:
■ Introduction to Oracle Mediator Error Handling
■ Using Error Handling
■ XML Schema Files for Error Handling
Beta Draft 1
<condition>
<action ref="ora-retry"/>
</condition>
</faultName>
<Actions>
<Action id="ora-retry">
<retry>
<retryCount>3</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff/>
<retryFailureAction ref="ora-java"/>
<retrySuccessAction ref="ora-human-intervention"/>
</retry>
</Action>
</Actions>
</faultPolicy>
</faultPolicies>
7.1.1.1 Conditions
Conditions identify error or fault conditions along with reference to the actions to be
taken. You can use conditions to identify the action 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 retry. Similarly, for
another error occurring because schema validation is failing, you can edit the payload
and resubmit the process.
Conditions are defined in the fault-policies.xml file, as shown in the following
example:
<Conditions>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:2101">
<condition>
<action ref="ora-java"/>
</condition>
</faultName>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:TYPE_FATAL_MESH">
<condition>
<action ref="ora-retry"/>
</condition>
</faultName>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
name="medns:3501">
<condition>
<action ref="ora-retry-crm-endpoint"/>
</condition>
</faultName>
</Conditions>
You can specify an action for an error type or error group while defining the
conditions in a fault policy. In the previous example, medns:2101 refers to a specific
error whereas medns:TYPE_FATAL_MESH refers to an error group. An error group
Beta Draft 3
7.1.1.2 Actions
Actions specify the tasks that should be performed when an error occurs. Oracle
Mediator provides a list of actions that you can use in a fault policy. These predefined
actions are described in the following list:
■ Human intervention: This action can be applied only in case of errors that occur
while executing asynchronous routing rules. You can perform the following
functions:
– Retry: You can use this option to retry the process. For example, if a service is
not available, then you might want to try accessing it again.
– Change payload and resubmit: You can select this option to change the
payload and resubmit it. This is useful in case of data errors such as data
validation and data transformation. You can change message payload by
using the SOA Console.
– Abort the flow: You can select this option to end the process.
■ Retry: This action enables you to retry the error in following ways:
– ’N’ times: Retry is performed ’N’ number of times. Each time a retry is carried
out, the retry count is stored in the mediator instance table to keep track of the
retry count.
– With constant delay/exponential back off: Retry handler computes the retry
interval based on the configuration in the policy file. Exponential back off
increases the retry interval exponentially for each retry attempt.
■ Java call out: This action enables you to call a customized class that implements
oracle.tip.mediator.common.error.management.recovery interface.
■ Abort: This action enables you to abort the flow.
Fault policies can be created at the following levels:
■ Composite: You can define one fault policy for all mediator components in a
composite.
■ Component: You can define fault policy for a mediator component exclusively. A
component-level fault policy overrides the composite-level fault policy.
Human intervention is the default action for errors, which do not have a fault policy
defined.
Beta Draft 5
<xs:complexType name="faultNameType">
<xs:sequence>
<xs:element name="condition" type="tns:conditionType"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:QName"/>
</xs:complexType>
<xs:complexType name="ActionType">
<xs:choice>
<xs:element name="retry" type="tns:RetryType"/>
<xs:element ref="tns:rethrowFault"/>
<xs:element ref="tns:humanIntervention"/>
<xs:element ref="tns:abort"/>
<xs:element ref="tns:replayScope"/>
<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"/>
Beta Draft 7
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>
<xs:attribute name="name" type="tns:idType" use="required"/>
</xs:complexType>
<xs:complexType name="PropertyValueType">
<xs:simpleContent>
<xs:extension base="tns:idType">
<xs:attribute name="name" type="tns:idType" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:element name="faultPolicy">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:Conditions"/>
<xs:element ref="tns:Actions"/>
<xs:element ref="tns:Properties" minOccurs="0"/>
<!--Every policy has on Conditions and and one Actions, however,
Properties is optional -->
</xs:sequence>
<xs:attribute name="id" type="tns:idType" use="required"/>
<xs:attribute name="version" type="xs:string" default="2.0.1"/>
</xs:complexType>
<xs:key name="UniqueActionId">
<xs:selector xpath="tns:Actions/tns:Action"/>
<xs:field xpath="@id"/>
</xs:key>
<xs:key name="UniquePropertySetId">
Beta Draft 9
</xs:complexType>
</xs:element>
<xs:simpleType name="nameType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="componentType">
<xs:annotation>
<xs:documentation>Bindings for a component. Overrides composite level
binding.</xs:documentation>
</xs:annotation>
<xs:attribute name="dn" type="tns:nameType" use="required"/>
<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>
This chapter describes how to publish and subscribe to business events in a SOA
composite application. Business events consist of message data sent as the result of an
occurrence in a business environment. When a business event is published, other
service components can subscribe to it.
This chapter includes the following sections:
■ Section 8.1, "Introduction to Business Events"
■ Section 8.2, "Creating Business Events in Oracle JDeveloper"
Beta Draft Business Events and the Event Delivery Network 8-1
Introduction to Business Events
<event-definition name="bugCreated">
<content element="ns0:bugCreatedInfo"/>
</event-definition>
<event-definition name="bugUpdated">
<content element="ns0:bugUpdatedInfo"/>
</event-definition>
</definitions>
8-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Business Events
Notes:
■ BPEL processes cannot directly publish events. However, you can
use a BPEL process to invoke Oracle Mediator and have Oracle
Mediator send the event.
■ There are two implementations of the EDN: JMS and AQ
(provides support for PL/SQL APIs).
Beta Draft Business Events and the Event Delivery Network 8-3
Creating Business Events in Oracle JDeveloper
Note: If you want to use a business event with a BPEL process, you
must use Oracle Mediator to subscribe to the event. This is because
BPEL can only publish, and not subscribe, to events.
8-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Business Events in Oracle JDeveloper
a. Click the icon above the canvas workspace in the SOA Composite Editor.
Figure 8–1 provides an example.
b. Select New > SOA Tier > Service Components > Event Definition from the
File main menu.
The Event Definition Creation wizard appears.
3. Enter the following details.
Field Value
Name Enter a name.
Directory Accept the default directory path or enter a specific
value.
Namespace Accept the default namespace or enter a specific
value for the namespace in which to place the
event.
4. Click Finish.
The Events editor appears. The events you define are saved in the event_
definition_name.edl file.
5. Click the + sign to add an event.
The Add an Event window appears.
6. Enter the following details.
Field Value
Element Click the flashlight icon to select the payload
(typically an XSD file).
Event Enter a name.
7. Click OK.
The added event now appears in the Events section.
8. Click the x next to event_definition_name.edl to close the Events 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 MDS and you are returned to the SOA
Composite Editor. Figure 8–2 shows that the event displays for browsing in the
Resource Palette in Oracle JDeveloper.
Beta Draft Business Events and the Event Delivery Network 8-5
Creating Business Events in Oracle JDeveloper
8-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Business Events in Oracle JDeveloper
9. Click Source.
The source code in Example 8–2 provides details about the subscribed event of the
Oracle Mediator service component.
Beta Draft Business Events and the Event Delivery Network 8-7
Creating Business Events in Oracle JDeveloper
While not explicitly demonstrated in this example, you can define XPath filters on
events. In Example 8–3, the event is accepted for delivery only if the initial deposit
is greater than 50000:
You can also subscribe to an entire namespace of events. In Example 8–4, all events
in the namespace http://bigbank.com/events are available for subscription.
8-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Business Events in Oracle JDeveloper
<component name="BigNewAccountNotifier">
<implementation.mediator src="BigNewAccountNotifier.mplan"/>
<business-events>
<subscribe xmlns:sub1="http://xmlns.oracle.com/Project1/EventDefinition1"
name="pub1:NewAccount" consistency="oneAndOnlyOne">
</subscribe>
</business-events>
</component>
If you define an XPath filter on the subscribed event, the syntax can look as shown
in Example 8–6:
<component name="BigNewAccountNotifier">
<implementation.mediator src="BigNewAccountNotifier.mplan"/>
<business-events>
<subscribe xmlns:sub1="http://xmlns.oracle.com/Project1/EventDefinition1"
name="sub1:NewAccount" consistency="oneAndOnlyOne"/>
<filter>
<xpath xmlns:be="http://oracle.com/fabric/businessEvent"
xmlns:ns1="http://xmlns.oracle.com/singleString"
<xpath expression= "/be:business-event/be:content/
pub1:AccountInfo/Details[@initialDeposit > 50000]" />
</filter>
</subscribe>
</business-events>
Beta Draft Business Events and the Event Delivery Network 8-9
Creating Business Events in Oracle JDeveloper
11. Design a second service component to publish the event, such as a BPEL process
or a second mediator service component.
SOA composite application design is now complete.
For more information about creating ADF BC business events, see Oracle Fusion
Applications Developer Standards and Guidelines.
8-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
9
9 Working with Domain Value Maps
This chapter describes how to use domain value maps to enable mapping of
vocabulary in one domain to another.
This chapter includes the following topics:
■ Introduction to Domain Value Maps
■ Creating Domain Value Maps
■ Using Domain Value Map Functions
■ Domain Value Map Use Case
Each domain value map typically holds a specific category of mappings among
multiple applications. For example, one domain value map might hold mappings for
city codes and another might hold mappings for state codes.
Beta Draft 1
■ Qualifier Order Support
■ One-to-Many Mapping Support
You can also specify multiple qualifiers for a domain value map. For example, as
shown in Table 9–3, BELG to Belgrade mapping can also be qualified with state
name.
Qualifiers are used only to qualify the mappings. Therefore, the qualifier values can
not be looked up.
In this example, the State qualifier has a qualifier value as 2 and the Country
qualifier has a qualifier value as 1.
Level of
Step 3 State=" ", Country=" ", CityCode=KN_USA Generalization
As shown in Figure 9–1, the lookup mechanism sets the higher order qualifier STATE
to the exact lookup value Arkansas and uses Canada|"" for the lower order
qualifier Country.
When no match is found, the lookup mechanism sets the higher order qualifier, STATE
to value "" and sets the next higher qualifier Country to an exact value Canada.
When no match is found, the lookup mechanism sets the value of the previous higher
order qualifier Country to value "". One matching row is found where CityCode is
KN_USA and Kensington is returned as value.
Table 9–4 provides a summary of these steps.
Beta Draft 3
9.2 Creating Domain Value Maps
You can create one or more domain value maps, in a SOA Composite application of
Oracle JDeveloper and then at run time, use it to look up for column values.
Note: You can later add more domains to a domain value map by
using the domain value map editor.
7. In the Domain Value field, enter a value corresponding to each domain. For
example, enter BO for CityCode domain and Boston for CityName domain as
shown in Figure 9–2.
8. Click OK.
The domain value map editor is displayed, as shown in Figure 9–3.
All .dvm files are based on the following schema definition (XSD) file:
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Copyright (c) 2006, Oracle. All rights reserved. -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://xmlns.oracle.com/dvm"
xmlns:tns="http://xmlns.oracle.com/dvm"
Beta Draft 5
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:element name="dvm">
<xsd:annotation>
<xsd:documentation>The Top Level Element
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="description" minOccurs="0" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The DVM Description. This is optional
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="columns">
<xsd:annotation>
<xsd:documentation>This element holds DVM's column List.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="column" minOccurs="2" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>This represents a DVM Column
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:attribute name="name" use="required" type="xsd:string"/>
<xsd:attribute name="qualifier" default="false"
type="xsd:string"
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
Beta Draft 7
9.3.3 Reordering the Columns in a Domain Value Map
You can move a column from one position to another. This feature is provided to
support user preferences, it has no effect on how the domain value map is used at run
time.
9.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.
■ Usage 1
dvm:lookupValue(dvmMetadataURI as string, SourceColumnName as string,
SourceValue as string, TargetColumnName as string, DefaultValue as string) as
string
Example:
dvm:lookupValue(’C:\dvms\cityMap.dvm’,’CityCodes’,’BO’, ’CityNames’,
’CouldNotBeFound’)
■ Usage 2
dvm:lookupValue(dvmMetadataURI as string, SourceColumnName as string,
SourceValue as string, TargetColumnName as string, DefaultValue as string,
(QualifierSourceColumn as string, QualifierSourceValue as string)*) as string
Example:
dvm:lookupValue (’C:\dvms\cityMap.dvm',’CityCodes’,’BO’,’CityNames’,
’CouldNotBeFound’, ’State’, ’Massachusetts’)
Arguments
■ dvmMetadataURI - The domain value map URI.
■ SourceColumnName - The source column name.
■ SourceValue - The source value (an XPath expression bound to the source
document of the XSLT transformation).
9.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 source
column is equal to the source value.
dvm:lookupValue1M(dvmMetadataURI as string, SourceColumnName as string,
SourceValue as string,(TargetColumnName as string)?)as DocumentFragment
Arguments
■ dvmMetadataURI - The domain value map URI.
■ SourceColumnName - The source column name.
■ 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.
Example
dvm:lookupValue1M
(’C:\dvms\cityMap.dvm',’CityCodes’,’BO’,’CityShortNames’,’CityAbbreNames’)
Beta Draft 9
Figure 9–5 Domain Value Map Functions in Component Palette
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. Double-click the lookupValue1M icon.
The Edit Function – lookupValue1M dialog is displayed as shown in Figure 9–6.
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 MDS
and also from 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
8. Click OK.
The XSLT mapper window is displayed with lookupValue1M function icon.
9. From the File menu, click Save All.
Beta Draft 11
To use the lookupValue function in the Expression Builder dialog:
1. In the Functions list, select DVM Functions.
This expression, also shown in Figure 9–8, looks up a domain value map for city
name equivalent of a city code. The value of the city code depends upon the value
specified at the run time.
Beta Draft 13
11. From the File menu, click Save All.
13. Repeat Step 9 through Step 12 to create another qualifier named StandardCode
with qualifier order as 2.
14. Click Add and then select Add Row.
Repeat this step to add two more rows.
15. Enter the following information in the newly added rows of the domain value
map table:
The domain value map editor would appear as shown in Figure 9–9.
16. From the File menu, click Save All and close the domain value map editor.
Beta Draft 15
11. Click Import Schema File.
The Import Schema File dialog is displayed.
12. Click Search and select the Order.xsd file present in the Samples folder.
Beta Draft 17
Figure 9–12 shows the WriteCommonOrder reference in SOA Composite Editor.
Beta Draft 19
Figure 9–16 Adding lookupValue Function to imp1:listOfOrder To imp1:listOfOrder.xsl
29. From the File menu, click Save All and close the listOfOrder_To_listOfOrder.xsl
tab.
Beta Draft 21
9.5.1.8 Task 8: Deploying the Composite Application
Deploying the HierarchicalValue composite application to Oracle Application
Server consists of following steps:
■ Creating an Application Deployment Profile.
■ Deploying the Application Deployment Profile to Oracle Application Server.
For detailed information about these steps, see Section 3.4, "Deploying Applications".
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure.
In Oracle Enterprise Manager Console, you can click the HierarchicalValue to see
the project dashboard, as shown in Figure 9–19.
To view the detailed execution trail, click the instance id in the instance column. The
Flow Trace page is displayed as shown in Figure 9–20.
Beta Draft 23
24 Product Title/BookTitle as a Variable Beta Draft
10
Working with Cross References
10
The cross referencing feature of Oracle SOA Suite enables you to associate identifiers
for equivalent entities created in different applications. For example, you can use cross
references to associate a customer entity created in one application (with native id
Cust_100) with an entity for the same customer in another application (with native id
CT_001).
This chapter explains how to create, populate, and use cross references. It contains the
following topics:
■ Introduction to Cross References
■ Creating and Modifying Cross Reference Tables
■ Populating Cross Reference Tables
■ Looking Up Cross Reference Tables
■ Deleting a Cross Reference Table Value
■ Schema Definition(XSD) File for Cross References
■ Cross Reference Use Case
Beta Draft 1
Table 10–1 (Continued)Cross Reference Table Sample
SAP EBS SBL
SAP_002 EBS_1002 SBL002
The identifier mapping is also required when information about a customer is updated
in one application and the changes need to be propagated in other applications also.
You can also integrate different identifiers is 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 Common to the cross reference table shown in Table 10–1. The
updated cross reference table would appear, as shown in Table 10–2.
Figure 10–1 shows how you can use common value integration pattern to map
identifiers in different applications.
Transform
Common value
to Siebel System
Transform
SAP system
Transform Siebel
SAP value to
Siebel System System
System Common value
C value to
O
M Common value
M
O
N
V
I Transform
E Common value to
W
Oracle E-Business
Suite System value
Oracle
Cross
E-Business
Reference Transform Oracle
Suite System
Database E-Business Suite
System value to
Common value
A cross reference table consists of following two parts: metadata and the actual data.
The metadata is the .xref file created in Oracle JDeveloper, and is stored in Metadata
Services (MDS) as an xml file. The actual data is stored in the database.
You can create a cross reference table in a SOA composite application of Oracle
JDeveloper and then use it to look up for column values at run time. However, before
using a cross reference to lookup a particular value, you need to populate it at run
time. This can de done by using the cross reference XPath functions. The XPath
functions enable you to populate a cross reference, perform lookups and delete a
column value. These XPath functions can be used in the Expression builder dialog to
create an expression or in the XSLT Mapper dialog to create transformations.
The XSLT Mapper dialog is displayed when you create an XSL file to transform data
from one XML schema to another. Figure 10–3 shows how you can select the cross
reference functions in the XSLT Mapper dialog.
Beta Draft 3
Figure 10–3 XSLT Mapper Dialog with Cross Reference Functions
Beta Draft 5
Note: -Cross reference table names, cross reference column names,
and cross reference values are case-sensitive.
Parameters
■ xrefLocation: The cross reference table URI.
■ xrefReferenceColumnName: The name of the reference column.
■ xrefReferenceValue: The value corresponding to reference column name.
■ xrefColumnName: The name of the column to be populated.
■ xrefValue: The value to be populated in the column.
■ mode: The mode in which the xref:populateXRefRow function populates the
column. You can specify any of the following values: ADD, LINK, or UPDATE.
Table 10–3 describes these modes.
Beta Draft 7
Note: The mode parameter values are case-sensitive and should be
specified in the upper case only as shown in Table 10–3.
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. In the referenceColumnName field, enter the name of the cross reference
column.
Click Browse to the right of the referenceColumnName field to select a
column name from the columns defined for the cross reference you previously
selected.
c. In the referenceValue field, you can manually enter a value or press
Ctrl-Space to launch XPath Building Assistant. Press the up and down keys to
locate an object in the list and press enter to select that object.
d. In the columnName field, enter the name of cross reference column.
Click the 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. In the value field, you can manually enter a value or press Ctrl-Space to
launch XPath Building Assistant.
f. In the mode field, enter a mode in which you want to populate the cross
reference table column. For example, 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 10–7.
Beta Draft 9
Figure 10–7 Populated Edit Function – populateXRefRow Dialog
To populate a column in the cross reference table with multiple values, you can use
the xref:populateXRefRow1M function. The syntax of the
xref:populateXRefRow1M function is as follows:
xref:populateXRefRow1M(xrefLocation as string, xrefReferenceColumnName as string,
xrefReferenceValue as string, xrefColumnName as string, xrefValue as string, mode
as string) as string
Parameters
■ xrefLocation: The cross reference URI.
■ xrefReferenceColumnName: The name of the reference column.
■ xrefReferenceValue: The value corresponding to reference column name.
■ xrefColumnName: The name of the column to be populated.
■ xrefValue: The value to be populated in the column.
■ mode: The mode in which the xref:populateXRefRow function populates the
column. You can specify either of the following values: ADD or LINK. Table 10–6
describes these modes:
The design time steps for using the xref:populateXRefRow1M function are similar
to the xref:populateXRefRow function described in "Using xref:populateXRefRow
Function".
Beta Draft 11
10.4 Looking Up Cross Reference Tables
After populating the cross reference table, you can use it to lookup for a value. This
can be done by using the following XPath extension functions:
■ xref:lookupXRef Function
■ xref:lookupXRef1M Function
Parameters
■ xrefLocation: The cross reference URI.
■ xrefReferenceColumnName: The name of the reference column.
■ xrefReferenceValue: The value corresponding to reference column name.
■ xrefColumnName: The name of the column to be looked up for the value.
■ needAnException: When value is set to true, an exception is thrown if the
value is not found, else an empty value is returned.
Exception Reasons
An exception can occur because of the following reasons:
■ The cross reference table with the given name is not found.
■ The specified column names are not found.
■ The specified reference value is empty.
■ If multiple values are found.
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 shared location in MDS by using the Resource Palette.
b. In the referenceColumnName field, enter the name of the cross reference
column.
Click Browse to the right of the referenceColumnName field to select a
column name from the columns defined for the cross reference you previously
selected.
c. In the referenceValue field, you can manually enter a value or press
Ctrl-Space to launch XPath Building Assistant. Press the up and down keys to
locate an object in the list and press enter to select that object.
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. 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 else select
No.
8. Click OK.
A populated Edit Function – lookupXRef dialog is shown in Figure 10–9.
Beta Draft 13
Figure 10–9 Populated Edit Function – lookupXRef Dialog
Parameters
■ xrefLocation: The cross reference URI.
■ xrefReferenceColumnName: The name of the reference column.
■ xrefReferenceValue: The value corresponding to reference column name.
■ xrefColumnName: The name of the column to be looked up for the value.
■ needAnException: If value is set to true, an exception is thrown if the value is
not found else an empty value is returned.
Exception Reasons
An exception can occur because of the following reasons:
■ The cross reference table with the given name is not found.
■ The specified column names are not found.
■ The specified reference value is empty.
Parameters
■ xrefTableName: The cross reference table name.
■ xrefColumnName: The name of the column from which you want to delete a
value.
■ xrefValueToDelete: The value to be deleted.
Exception Reasons
An exception can occur because of the following reasons:
■ The cross reference table with the given name is not found.
■ The specified column name is not found.
■ The specified value is empty.
■ The specified value is not found in the column.
■ Multiple values are found.
Perform the following steps to delete a value from a cross reference table column:
1. In the XSLT Mapper dialog, expand the trees in the Source and Target panes.
2. Drag and drop the source element to the target element.
3. In the Component Palette, click the down arrow and then select Advanced.
4. Select XREF Functions.
5. Drag and drop markForDelete onto the line that connects the source object to the
target object.
A markForDelete icon appears on the connecting line.
6. Double-click the markForDelete icon.
Beta Draft 15
The Edit Function – markForDelete dialog is displayed, as shown in Figure 10–10.
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 flashlight 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 shared location in MDS by using the Resource Palette.
b. In the columnName field, enter the name of cross reference table column.
Click the flashlight 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, you can manually enter a value or press Ctrl-Space to
launch XPath Building Assistant. Press the up and down keys to locate an
object in the list and press enter to select that object.
A populated Edit Function – markForDelete dialog is shown in Figure 10–11.
8. Click OK.
<complexType name="columnsType">
<sequence>
<element name="column" minOccurs="1" maxOccurs="unbounded">
<complexType>
Beta Draft 17
<attribute name="name" type="string" use="required"/>
</complexType>
</element>
</sequence>
</complexType>
<complexType name="rowsType">
<sequence>
<element name="row" minOccurs="1" maxOccurs="unbounded">
<complexType>
<sequence>
<element name="cell" minOccurs="1" maxOccurs="unbounded">
<complexType>
<attribute name="colName" type="string" use="required"/>
</complexType>
</element>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</schema>
10.7.1 Introduction
This use case implements an integration scenario between instances of Oracle EBS,
SAP and Siebel. When an insert, update, delete operation is performed on the SAP_01
table, the corresponding data is inserted or updated in the EBS and SBL tables.
Figure 10–12 provides an overview of this use case.
10.7.2 Prerequisites
Following are the prerequisites for creating this use case:
■ Installed and configured Oracle SOA Suite, Oracle JDeveloper, and an Oracle
Database to use as your repository.
■ Started Oracle SOA Suite by running the version of startsoa for your operating
system from the ORACLE_HOME/bin directory.
Beta Draft 19
connector-name="Database Adapter">
<config-property name="xADataSourceName" value="jdbc/DBConnection1"/>
<config-property name="dataSourceName" value=""/>
<config-property name="platformClassName"
value="oracle.toplink.platform.database.Oracle9Platform"/>
<config-property name="usesNativeSequencing" value="true"/>
<config-property name="sequencePreallocationSize" value="50"/>
<config-property name="defaultNChar" value="false"/>
<config-property name="usesBatchWriting" value="false"/>
</connector-factory>
This sample uses eis/DB/DBConnection1 to poll SAP table for new messages
and to connect to the procedure that simulates Oracle EBS and Siebel instances.
6. Edit the data-sources.xml available in the OH/j2ee/oc4j_soa/config
folder to have the corresponding JNDI name for datasource
jdbc/DBConnection1 as specified in the Database Adapter's oc4j-ra.xml.
<managed-data-source connection-pool-name="XRefDemo-ConnectionPool"
jndi-name="jdbc/DBConnection1" name="DBConnection1"/>
<connection-pool name="XRefDemo-ConnectionPool">
<connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"
user="scott" password="tiger" url="jdbc:oracle:thin:@host:port:service"/>
</connection-pool>
11. From the File menu, click Save All and close the Cross Reference Editor.
Beta Draft 21
5. Click Next.
The Service Connection page is displayed.
6. In the Application Connection field, select DBConnection1.
7. In the JNDI Name field, enter eis/DB/DBConnection1.
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.
10. Click Import Tables.
The Import Tables dialog is displayed.
11. Select Scott from Schema.
12. In the Name Filter field, enter %SAP% and click Query.
The Available field is populated with SAP_01 table name.
13. Double-click SAP_01.
The Selected field is populated with SAP_01.
14. Click OK.
The Select Table page now contains the SAP_01 table.
15. Select SAP_01 and click Next.
The Define Primary Key page is displayed.
16. Select ID as primary key and click Next.
The Relationships page is displayed.
17. Click Next.
The Attribute Filtering page is displayed.
18. Click Next.
The After Read page is displayed.
19. Select Update a Field in the [SAP_01] Table (Logical Delete) and click Next.
The Logical Delete page is displayed.
20. In the Logical Delete field, select LOGICAL_DEL.
Beta Draft 23
10.7.3.5 Task 5: Creating EBS and SBL External References
Perform the following steps to create two external references named EBS and SBL:
1. From the Components Palette, select SOA.
2. Select Database Adapter and drag it to the External References design area.
The Adapter Configuration wizard Welcome page is displayed.
3. Click Next.
The Service Name page is displayed.
4. In the Service Name field, enter EBS.
5. Click Next.
The Service Connection page is displayed.
6. In the Application Connection field, select DBConnection1.
7. In the JNDI Name field, enter eis/DB/DBConnection1.
8. Click Next.
The Operation Type page is displayed.
9. Select Call a Stored Procedure or Function and click Next.
The Specify Stored Procedure page is displayed.
10. Select Scott from Schema.
Beta Draft 25
Figure 10–19 SBL Reference in SOA Composite Editor
Beta Draft 27
Figure 10–21 SAP Service Connected to Mediator1
Insert
Perform the following tasks to create routing rules for Insert operation:
1. Double-click Mediator1 mediator.
The Mediator Editor is displayed.
2. In Routing Rules panel, click the Create a new Routing Rule icon.
8. Click OK.
9. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
10. Select Create New Mapper File and enter SAP_TO_COMMON_INSERT.xsl.
17. Drag and drop populateXRefRow from Components Palette to the line connecting
top:id and inp1:id elements.
18. Double-click the populateXRefRow icon.
The Edit Function-populateXRefRow dialog is displayed.
19. Click Search to the right of xrefLocation field.
The SCA Resource Lookup dialog is displayed.
20. Select customer.xref and click OK.
Beta Draft 29
21. In the referenceColumnName field, enter "SAP_01" or click Search to select the
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 orcl:generate-guid().
25. In the mode field, enter "Add" or click Search to select this mode.
Figure 10–23 shows populated Edit Function – populateXRefRow dialog.
Update
Perform the following tasks to create routing rules for Update operation:
7. Click OK.
8. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
9. Select Create New Mapper File and enter SAP_TO_COMMON_UPDATE.xsl.
10. Click OK.
A SAP_TO_COMMON_UPDATE.xsl tab is displayed.
11. Drag and drop top:Sap01 source element to the inp1:Customer target element.
The Auto Map Preferences dialog is displayed.
12. Click OK.
15. Drag and drop lookupXRef from Components Palette to the line connecting
top:id and inp1:id elements.
16. Double-click the lookupXRef icon.
The Edit Function-lookupXRef dialog is displayed.
17. Click Search to the right of xrefLocation field.
The SCA Resource Lookup dialog is displayed.
18. Select customer.xref and click OK.
19. In the referenceColumnName field, enter "SAP_01" or click Search to select the
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.
Figure 10–25 shows populated Edit Function – looupXRef dialog.
Beta Draft 31
Figure 10–25 Edit Function – looupXRef Dialog: XrefCustApp Use Case
24. From the File menu, click Save All and close the SAP_TO_COMMON_
UPDATE.xsl tab.
The Routing Rules panel would appear as shown in Figure 10–26.
UpdateID
Perform the following tasks to create routing rules for UpdateID operation:
1. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2. Select Service.
The Target Services dialog is displayed.
3. Navigate to XrefCustApp, Mediators, Common, Services, Common.
4. Select updateid and click OK.
5. Click the Filter icon.
The Expression Builder dialog is displayed.
6. Enter the following expression in the Expression field:
7. Click OK.
8. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
9. Select Create New Mapper File and enter SAP_TO_COMMON_UPDATEID.xsl.
10. Click OK.
A SAP_TO_COMMON_UPDATEID.xsl tab is displayed.
11. Drag and drop top:Sap01 source element to the inp1:Customer target element.
The Auto Map Preferences dialog is displayed.
12. Click OK.
13. From the Components Palette, select Advanced.
15. Drag and drop populateXRefRow from Components Palette to the line connecting
top:id and inp1:id elements.
16. Double-click the populateXRefRow icon.
The Edit Function-populateXRefRow dialog is displayed.
17. Click Search to the right of xrefLocation field.
The SCA Resource Lookup dialog is displayed.
18. Select customer.xref and click OK.
19. In the referenceColumnName field, enter "SAP_01" or click Search to select the
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.
Figure 10–27 shows a populated Edit Function – populateXRefRow dialog.
Beta Draft 33
Figure 10–27 Edit Function – populateXRefRow Dialog: XrefCustApp Use Case
24. Drag and drop lookupXRef from Components Palette to the line connecting
top:id and inp1:id elements.
25. Double-click the lookupXRef icon.
The Edit Function-lookupXRef dialog is displayed.
26. Click Search to the right of xrefLocation field.
The SCA Resource Lookup dialog is displayed.
27. Select customer.xref and click OK.
28. In the referenceColumnName field, enter "SAP_01" or click Search to select the
column name.
29. In the referenceValue column, enter
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.
Figure 10–28 shows a populated Edit Function – lookupXRef dialog.
Delete
Perform the following tasks to create routing rules for Delete operation:
1. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2. Select Service.
The Target Services dialog is displayed.
3. Navigate to XrefCustApp, Mediators, Common, Services, Common.
4. Select delete and click OK.
Beta Draft 35
5. Click the Filter icon.
The Expression Builder dialog is displayed.
6. Enter the following expression in the Expression field:
$in.Sap01Collection/top:Sap01Collection/top:Sap01/top:operation = 'DELETE'
7. Click OK.
8. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
9. Select Create New Mapper File and enter SAP_TO_COMMON_DELETE.xsl.
10. Click OK.
A SAP_TO_COMMON_DELETE.xsl tab is displayed.
11. Right-click <sources> and select Add Parameter.
The Add Parameter dialog is displayed.
12. In the Local Name field, enter COMMONID.
17. Drag and drop top:Sap01 source element to the inp1:Customer target element.
The Auto Map Preferences dialog is displayed.
18. Click OK.
25. Drag and drop markForDelete from Components Palette to the line connecting
top:id and if node.
26. Double-click the markForDelete icon.
The Edit Function-markForDelete dialog is displayed.
27. Click Search to the right of xrefLocation field.
The SCA Resource Lookup dialog is displayed.
28. Select customer.xref and click OK.
29. In the columnName field, enter "SAP_01" or click Search to select the column
name.
Beta Draft 37
Figure 10–32 Insert, Update, UpdateID, and Delete Operations
Insert Operation
Perform the following tasks to create routing rules for Insert operation:
1. Double-click Common mediator.
The Mediator Editor is displayed.
2. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
3. Select Service.
The Target Services dialog is displayed.
4. Navigate to XrefCustApp, References, SBL.
5. Select SBL and click OK.
6. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
7. Select Create New Mapper File and enter COMMON_TO_SBL_INSERT.xsl.
8. Click OK.
A COMMON_TO_SBL_INSERT.xsl tab is displayed.
11. From the File menu, click Save All and close the COMMON_TO_SBL_INSERT.xsl
window.
12. In the Synchronous Reply panel, click Browse for target service operations.
The Target Type dialog is displayed.
13. Select Service.
The Target Services dialog is displayed.
14. Navigate to XrefCustApp, References, Logger.
16. Click the Transformation icon next to the Using Transformation field.
The Reply Transformation map dialog is displayed.
17. Select Create New Mapper File and enter SBL_TO_COMMON_INSERT.xsl.
21. Drag and drop an populateXRefRow function from Components Palette to the
connecting line.
22. Double-click the populateXRefRow icon.
The Edit Function-populateXRefRow dialog is displayed.
23. Enter the information in the following fields:
■ 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"
Beta Draft 39
24. Click OK.
The SBL_TO_COMMON_INSERT.xsl would appear as shown in Figure 10–34.
25. From the File menu, click Save All and close the SBL_TO_COMMON_INSERT.xsl
tab.
26. In the Synchronous Reply panel, click the Assign Values icon.
The Assign Values dialog is displayed.
27. Click Add.
The Assign Value dialog is displayed.
28. In the From section, select Expression.
35. Repeat the Step 2 through Step 34 to specify another target service EBS and its
routing rules.
Figure 10–36 shows the insert operation panel with SBL and EBS target service.
Delete Operation
Perform the following tasks to create the routing rules for delete operation:
1. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2. Select Service.
The Target Services dialog is displayed.
3. Navigate to XrefCustApp, References, SBL.
4. Select SBL and click OK.
5. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
6. Select Create New Mapper File and enter COMMON_TO_SBL_DELETE.xsl.
7. Click OK.
A COMMON_TO_SBL_DELETE.xsl tab is displayed.
8. Drag and drop inp1:Customers 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 10–33.
Beta Draft 41
Figure 10–37 COMMON_TO_SBL_DELETE.xsl Transformation
10. Drag and drop an lookupXRef function from Components Palette to the line
connecting inp1:id and db:XCUSTOMER_ID.
11. Double-click the lookupXRef icon.
The Edit Function: lookupXRef dialog is displayed.
12. Enter the information in the following fields:
■ xrefLocation: "customer.xref"
■ referenceColumnName: "Common"
■ referenceValue: /inp1:Customers/inp1:Customer/inp1:Id
■ columnName:"SBL_78"
■ needException:false()
13. Click OK.
14. From the File menu, click Save All and close the COMMON_TO_SBL_
DELETE.xsl window.
15. In the Synchronous Reply panel, click Browse for target service operations.
The Target Type dialog is displayed.
16. Select Service.
The Target Services dialog is displayed.
17. Navigate to XrefCustApp, References, Logger.
18. Select Write and click OK.
19. Click the Transformation icon next to the Using Transformation field.
The Reply Transformation map dialog is displayed.
20. Select Create New Mapper File and enter SBL_TO_COMMON_DELETE.xsl.
23. Drag and drop an markForDelete function from Components Palette to the
connecting line.
24. Double-click the markForDelete icon.
■ xrefLocation: "customer.xref"
■ columnName:"SBL_78"
27. From the File menu, click Save All and close the SBL_TO_COMMON_
DELETE.xsl tab.
28. In the Synchronous Reply panel, click the Assign Values icon.
The Assign Values dialog is displayed.
29. Click Add.
The Assign Value dialog is displayed.
30. In the From section, select Expression.
37. Repeat the Step 1 through Step 36 to specify another target service EBS and specify
the routing rules.
Figure 10–36 shows the delete operation panel with SBL and EBS target service.
Beta Draft 43
Figure 10–39 Delete Operation with SBL and EBS Target Service
Update Operation
Perform the following tasks to create routing rules for Update operation:
1. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2. Select Service.
The Target Services dialog is displayed.
3. Navigate to XrefCustApp, References, SBL.
4. Select SBL and click OK.
5. Click the Transformation icon next to the Using Transformation field.
The Request Transformation map dialog is displayed.
6. Select Create New Mapper File and enter COMMON_TO_SBL_UPDATE.xsl.
7. Click OK.
A COMMON_TO_SBL_UPDATE.xsl tab is displayed.
8. Drag and drop inp1:Customers 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 10–37.
10. Drag and drop an lookupXRef function from Components Palette to the line
connecting inp1:id and db:XCUSTOMER_ID.
11. Double-click the lookupXRef icon.
The Edit Function: lookupXRef dialog is displayed.
14. From the File menu, click Save All and close the COMMON_TO_SBL_
UPDATE.xsl window.
15. In the Synchronous Reply panel, click Browse for target service operations.
The Target Type dialog is displayed.
16. Select Service.
The Target Services dialog is displayed.
17. Navigate to XrefCustApp, References, Logger.
19. Click the Transformation icon next to the Using Transformation field.
The Reply Transformation map dialog is displayed.
20. Select Create New Mapper File and enter SBL_TO_COMMON_UPDATE.xsl.
23. From the File menu, click Save All and close the SBL_TO_COMMON_
UPDATE.xsl tab.
24. In the Synchronous Reply panel, click the Assign Values icon.
The Assign Values dialog is displayed.
25. Click Add.
The Assign Value dialog is displayed.
26. In the From section, select Expression.
Beta Draft 45
Figure 10–40 Update Operation with SBL Target Service
33. Repeat the Step 1 through Step 32 to specify another target service EBS and its
routing rules.
Figure 10–41 shows the update operation panel with SBL and EBS target service.
Figure 10–41 Update Operation with SBL and EBS Target Service
UpdateID Operation
Perform the following tasks to create routing rules for UpdateID operation:
1. In Routing Rules panel, click the Create a new Routing Rule icon.
The Target Type dialog is displayed.
2. Select Service.
The Target Services dialog is displayed.
3. Navigate to XrefCustApp, References, SBL.
4. Select SBL and click OK.
■ xrefLocation: "customer.xref"
■ referenceColumnName: "Common"
■ referenceValue: /inp1:Customers/inp1:Customer/inp1:Id
■ columnName:"SBL_78"
■ needException:false()
13. Click OK.
14. From the File menu, click Save All and close the COMMON_TO_SBL_
UPDATEID.xsl window.
15. In the Synchronous Reply panel, click Browse for target service operations.
The Target Type dialog is displayed.
16. Select Service.
The Target Services dialog is displayed.
17. Navigate to XrefCustApp, References, Logger.
19. Click the Transformation icon next to the Using Transformation field.
The Reply Transformation map dialog is displayed.
20. Select Include Request in the Reply Payload.
23. Drag and drop an populateXRefRow function from Component Palette to the
connecting line.
24. Double-click the populateXRefRow icon.
Beta Draft 47
The Edit Function-populateXRefRow dialog is displayed.
25. Enter the information in the following fields:
■ 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"
26. Click OK.
27. From the File menu, click Save All and close the SBL_TO_COMMON_
UPDATEID.xsl tab.
28. In the Synchronous Reply panel, click the Assign Values icon.
The Assign Values dialog is displayed.
29. Click Add.
The Assign Value dialog is displayed.
30. In the From section, select Expression.
Figure 10–43 Updateid Operation with SBL and EBS Target Service
where hostname is the host on which you installed the Oracle SOA Suite
infrastructure.
Beta Draft 49
In the SOA Console, you can click the XrefCustApp to see the project dashboard as
shown in Figure 10–44.
To view the detailed execution trail of the XrefCustApp application, click the instance
id in the instance column. The Flow Trace page is displayed as shown in Figure 10–45.
Beta Draft
Beta Draft
11
Getting Started with
11
This chapter describes how to start key Oracle BPEL Process Manager components,
including Oracle JDeveloper and Oracle BPEL Server. An introduction to the main
sections of Oracle JDeveloper that you use to design BPEL process service components
is also provided. Key BPEL design features such as activities and partner links are also
described.
This chapter contains the following topics:
■ Section 11.1, "Starting Oracle SOA Suite Components"
■ Section 11.2, "Introduction to the BPEL Designer Environment"
■ Section 11.3, "Introduction to Activities"
■ Section 11.4, "Introduction to Partner Links"
■ Section 11.5, "Partner Link Creation and the SOA Composite Editor"
■ Section 11.6, "Introduction to Oracle BPEL Server"
■ Section 11.7, "Introduction to Oracle BPEL Process Manager Technology Adapters"
Beta Draft Getting Started with Oracle BPEL Process Manager 11-1
Introduction to the BPEL Designer Environment
Table 11–1 Starting and Stopping Oracle BPEL Process Manager Components
To Access The... On Windows... On UNIX...
Oracle SOA Suite To start Oracle SOA Server: To start Oracle SOA Server:
From ORACLE_HOME\bin: From $ORACLE_HOME/bin:
startsoa.bat startsoa.sh
To stop Oracle SOA Server: To stop Oracle SOA Server:
From ORACLE_HOME\bin: From $ORACLE_HOME/bin:
shutdownsoa.bat shutdownsoa.sh
Note: Running startsoa from the operating
system command prompt causes server startup
messages, including errors and warnings, to
display on-screen instead of being written to a log
file. If you want to log these messages, redirect
them to a file using standard output. For example:
% startsoa.bat > logfile1 &
Oracle JDeveloper Click JDev_Oracle_ $ORACLE_HOME/jdev/bin/jdev
Home\JDev\bin\jdev.exe or create a
shortcut
11-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the BPEL Designer Environment
2. Provide the required details (including BPEL process name). Click Help for details
about the types of BPEL processes you can create.
Always use completely unique names when creating BPEL processes. Do not
create:
■ A process name that begins with a number
■ A process name that includes a dash (for example, Loan-Flow)
■ Two processes with the same name, but with different capitalization
3. Click OK.
4. Double-click the BPEL process.
Oracle JDeveloper displays the sections shown in Figure 11–1.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-3
Introduction to the BPEL Designer Environment
Each section of this view enables you to perform specific design and deployment
tasks. Table 11–2 identifies the sections listed in Figure 11–1 and provides references to
sections that describe their capabilities.
11-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the BPEL Designer Environment
As you design the BPEL process service component, additional files, folders, and
elements can appear in the Application Navigator.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-5
Introduction to the BPEL Designer Environment
■ Click the Design tab at the bottom of the window with the .bpel file selected
■ Double-click the BPEL process component in the SOA composite application
Figure 11–3 shows the activities automatically created with an asynchronous BPEL
process service component. You add to the BPEL process service component by
dragging and dropping activities, creating variables, creating partner links, and so on.
As you design the BPEL process service component by dragging and dropping
activities, creating partner links, and so on, the Design window changes. Figure 11–4
shows the Design window later in the design phase after adding a partner link (in this
example, named WriteDBRecord) and the additional activities (invoke, receive,
assign, transform, and others).
11-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the BPEL Designer Environment
Beta Draft Getting Started with Oracle BPEL Process Manager 11-7
Introduction to the BPEL Designer Environment
Click Source at the bottom of the window. Figure 11–6 shows part of the Source of a
.bpel file. Details about the CreditRatingService partner link you created appear in
the file.
11-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the BPEL Designer Environment
Note: If you want to learn more about the History view, place the
cursor in this section and press F1 to display online Help.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-9
Introduction to the BPEL Designer Environment
Figure 11–9 shows the BPEL Services selection of the Component Palette. This list
enables you to drag and drop adapters, partner links, or decision services into your
BPEL process service component.
Figure 11–10 shows the String Functions category of the Component Palette that
displays when you work in the transformation window of a transform activity.
11-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the BPEL Designer Environment
Note: If you want to learn more about the Component Palette, place
the cursor in this section and press F1 to display online Help.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-11
Introduction to Activities
■ Editing activities in the BPEL process flow sequence that displays in the Design
window
Figure 11–12 shows the Structure Window.
Notes:
■ If you want to learn more about the Structure Window, place the
cursor in this section and press F1 to display online Help.
■ Do not import two schema files with the same name into a BPEL
process service component. Ensure that the files have unique
names.
Note: If you want to learn more about the Log Window, place the
cursor in this section and press F1 to display online Help.
11-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Activities
Activities enable you to perform specific tasks within a BPEL process service
component. For example:
■ An assign activity enables you to manipulate data, such as copying the contents of
one variable to another.
■ An invoke activity enables you to invoke a service (identified by its partner link)
and specify an operation for this service to perform.
Figure 11–13 shows an example of a property window (for this example, an invoke
activity). In this example, you invoke a partner link named Invoke_FileWrite and
define its attributes.
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.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-13
Introduction to Partner Links
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 context of the
conversation. Figure 11–4 on page 11-7 shows an example of a partner link named
WriteDBRecord being invoked by a BPEL process service component.
Figure 11–15 shows an example of the attributes of a partner link for a service named
WriteFile.
Table 11–4 describes the fields of the Create Partner Link window.
11-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Partner Link Creation and the SOA Composite Editor
Table 11–5 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A partner link for an outbound adapter ■ A reference handle for the BPEL service component.
■ A reference representing the outbound adapter in the
composite
■ A wire connecting the BPEL service component to the
adapter reference
Figure 11–16 shows how this method of creation appears in the SOA Composite
Editor.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-15
Partner Link Creation and the SOA Composite Editor
Table 11–6 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A partner link for an inbound adapter ■ A service for the BPEL service component.
■ A service representing the inbound adapter in the
composite
■ A wire connecting the inbound adapter service to the
BPEL service component
Figure 11–17 shows how this method of creation appears in the SOA Composite
Editor.
Table 11–7 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A partner link from an abstract WSDL to call a A reference handle with an interface and callback interface
service defined for the BPEL service component
Figure 11–18 shows how this method of creation appears in the SOA Composite
Editor.
11-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Partner Link Creation and the SOA Composite Editor
Table 11–8 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A partner link is created from an abstract WSDL to A service with an interface and callback interface for the
implement a service BPEL service component is created.
Note: If an external SOAP reference with the specified
interface and callback interface already exists in the SOA
Composite Editor, you can either create a new external
SOAP reference and wire to it or wire to the existing
external SOAP reference.
Figure 11–19 shows how this method of creation appears in the SOA Composite
Editor.
Table 11–9 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A human task or decision service is created ■ A human task or decision service in the composite
■ A reference for the BPEL service component
■ A wire connecting the BPEL service component to the
new human task or decision service
Figure 11–20 shows how this method of creation appears in the SOA Composite
Editor.
Beta Draft Getting Started with Oracle BPEL Process Manager 11-17
Introduction to Oracle BPEL Server
11.5.6 Creating a Partner Link From an Existing Human Task, Decision Service, or
Mediator Routing Service
Table 11–10 describes the impact on the SOA Composite Editor.
Table 11–10 Impact of Partner Link Creation on the SOA Composite Editor
Creating the Following for a BPEL Process in
Oracle JDeveloper... Displays the Following in the SOA Composite Editor...
A partner link by dragging an existing human task, ■ A reference for the BPEL service component
decision service, or mediator routing service
■ A wire connecting the BPEL service component to the
component from the Resource Palette to the BPEL
existing human task, decision service, or mediator
process
routing service
Figure 11–21 shows how this method of creation appears in the SOA Composite
Editor.
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,
11-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Oracle BPEL Process Manager Technology Adapters
database tables, database queues, Java Message Services (JMS), MQ, and Oracle
E-Business Suite. This wizard enables you to configure the types of adapters shown in
Figure 11–23 for use with the BPEL process service component:
Beta Draft Getting Started with Oracle BPEL Process Manager 11-19
Introduction to Oracle BPEL Process Manager Technology Adapters
The Adapter Configuration wizard windows that appear after the Service Name
window 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.
11-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
12
12 Manipulating XML Data in BPEL Processes
This chapter describes how to manipulate XML data in BPEL, including the use of
XPath expressions.
This chapter includes the following sections:
■ Section 12.1, "Introduction to Manipulating XML Data in BPEL Concepts"
■ Section 12.2, "Delegating XML Data Operations to Data Provider Services"
■ Section 12.3, "Initializing a Variable with Expression Constants or Literal XML"
■ Section 12.4, "Copying Between Variables"
■ Section 12.5, "Accessing Fields Within Element-Based and Message Type-Based
Variables"
■ Section 12.6, "Assigning Numeric Values"
■ Section 12.7, "Using Mathematical Calculations with XPath Standards"
■ Section 12.8, "Assigning String Literals"
■ Section 12.9, "Concatenating Strings"
■ Section 12.10, "Assigning Boolean Values"
■ Section 12.11, "Assigning a Date or Time"
■ Section 12.12, "Manipulating Attributes"
■ Section 12.13, "Manipulating XML Data with bpelx Extensions"
■ Section 12.14, "Validating XML Data with bpelx:validate"
■ Section 12.15, "Manipulating XML Data Sequences That Resemble Arrays"
■ Section 12.16, "Converting from a String to an XML Element"
■ Section 12.17, "Understanding the Differences Between Document-Style and
RPC-Style WSDL Files"
■ Section 12.18, "Manipulating SOAP Headers in BPEL"
■ Section 12.19, "Use Cases for Manipulating XML Data in BPEL"
This syntax is described in detail in that specification. The from-spec and to-spec
typically specify a variable or variable part, as shown in Example 12–2:
When you use Oracle JDeveloper, you supply assign activity details in a Copy
Operation window that includes a From section and a To section. This reflects the
preceding BPEL source code syntax.
12-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Manipulating XML Data in BPEL Concepts
Rather than repeating all syntax details, this chapter shows and describes excerpts
taken primarily from sample projects provided in the SOA_Oracle_
Home\bpel\samples\references directory.
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: 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 12–3 provides an example:
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
(section 14.3) 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:
■ Core XPath functions: XPath supports a large number of built-in functions,
including functions for string manipulation (such as concat), numeric functions
(like sum), and others.
<from expression="concat('string one', 'string two')"/>
For a complete list of the functions built into XPath standards, see section 4 of the
XML Path Language (XPath) Specification.
■ BPEL XPath extension functions: BPEL adds several extension functions to the
core XPath core functions, enabling XPath expressions to access information from
a process. 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.
■ Oracle BPEL XPath extension functions: Oracle provides some additional XPath
functions that use the capabilities built into BPEL and XPath standards for adding
new functions.
12-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Delegating XML Data Operations to Data Provider Services
In previous releases of Oracle BPEL Process Manager, all variable data was in DOM
form. With release 11g, variable data in SDO form is also supported. DOM and SDO
variables in BPEL process service components are implicitly converted to the required
forms. For example, an Oracle BPEL process service component using DOM-based
variables can automatically convert these variables as required to SDO-based variables
in an assign activity, and vice versa. Both form types are defined in the XSD schema
file. No user intervention is required.
Entity variables also support SDO-formed data. However, unlike the DOM and SDO
variables previously described, the entity variable with SDO-based data enables you to
bind a unique key value to data (for example, a purchase order). Only the key is stored
in the dehydration store; the data requiring conversion is stored with the service of the
ADF BC application. The key points to the data stored in the service. When the data is
required, it is fetched from the data provider service and placed into memory.
BPEL
Process Service
Component
ADF BC Application SDO
Using Binding Wire
SDO-Formed Component
Data Service
You use the SOA Composite Editor and Oracle JDeveloper to perform the following
tasks:
■ 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 together.
■ Define the details of the BPEL process service component.
For more information about using the SOA Composite Editor, see Chapter 2,
"Introduction to the SOA Composite Editor".
12-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Delegating XML Data Operations to Data Provider Services
BPEL
Process Service
Component
(using entity
variable)
SDO Binding ADF BC Application
Wire Component Using
Reference SDO-Formed
Data
Pass key to
fetch data
When the ADF BC application is the external partner link in the outside world, there is
no SDO binding component reference in the SOA Composite Editor that you drag and
drop into the composite application to create outbound communication. Instead,
communication between the composite application and the ADF BC application occurs
as follows:
■ The ADF BC application is deployed and automatically registered as an SDO
service in the Service Infrastructure
■ You use Oracle JDeveloper to browse for and discover this application as an SDO
service and create a partner link connection
■ The composite.xml file is automatically updated with reference details (the
binding.java property) when the ADF BC application service is discovered.
For more information about the Service Infrastructure, see Chapter 1,
"Service-Oriented Architecture and Oracle SOA Suite".
5. Click the Entity Variable check box and select the flashlight icon to the right of
the Partner Link field.
The Partner Link Chooser window appears with a list of available services,
including the SDO service.
6. Browse for and select the service for the ADF BC application.
7. Click OK to close the Partner Link Chooser and Create Variable windows.
12-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Initializing a Variable with Expression Constants or Literal XML
3. Click the flashlight icon to the right of the Entity Variable field.
The Variable Chooser window appears.
4. Select the entity variable created in Section 12.2.1.3, "Creating an Entity Variable
and Choosing a Partner Link" on page 12-7 and click OK.
5. Click the + sign in the Unique Keys section.
The Create Key window appears.
6. Enter the following details to define the binding key:
Field Value
Key Local Part Enter the local part of the key.
Key Namespace URI Enter the namespace URI for the key.
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’)
The POID key for an entity variable typically comes from
another message. If the type of POID key is an integer and the
expression result is a string of ABC, the string-to-integer fails
and the Bind Entity activity also fails at runtime.
<quantity>0</quantity>
<approved/>
<message/>
</result>
</from>
<to variable="output" part="payload"/>
</copy>
</assign>
The WSDL file defines the person message type shown in Example 12–7:
For more information about this code example, see Section 9.3.2 of the Business Process
Execution Language for Web Services Specification.
12-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Assigning Numeric Values
12.5.1 How to Access Fields Within Element-Based and Message Type-Based Variables
In Example 12–8, the ssn field is copied from the CreditFlow process’s input
message into the ssn field of the credit rating service’s input message.
Example 12–9 shows how the BPEL file defines the variables involved in this
assignment:
The crInput variable is used as an input message to a credit rating service. Its
message type, CreditFlowRequestMessage, is defined in
CreditFlowService.wsdl as shown in Example 12–10:
12-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Assigning Boolean Values
Other string manipulation functions available in XPath are listed in section 4.2 of the
XML Path Language (XPath) Specification.
For more information, see the SOA_Oracle_
Home\bpel\samples\references\Assign sample.
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. This means 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.
For more information, see the SOA_Oracle_
Home\bpel\samples\references\Assign sample.
In Example 12–19, 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).
12-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating Attributes
The code in Example 12–21 selects the custId attribute of the customer field and
assigns it to the variable custId:
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 12–22:
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 12–24 consolidates multiple bills of material into one single bill of material by
appending multiple b:part’s for one BOM to b:parts of the consolidated BOM.
12-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data with bpelx Extensions
query="/b:bom/b:parts" />
</bpelx:append>
</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 more than one node is 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 12–26 shows the syntax before the execution of <insertBefore>. The value
of addrVar is:
After the execution of the syntax in Example 12–27 in the BPEL process service
component file:
<a:city>Redwood Shore</a:city>
<a:state>CA</a:state>
<a:zipcode>94065</a:zipcode>
</a:usAddress>
This operation is similar to the functionality described for Section 12.13.2, "How to Use
bpelx:insertBefore" on page 12-17, 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.
This operation can also be considered a macro of conditional-switch + (append
or insertBefore).
Example 12–30 shows the syntax before the execution of <insertAfter>. The value
of addrVar is:
After execution of the syntax shown in Example 12–31 in the BPEL process service
component file:
12-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data with bpelx Extensions
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.
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 12–34 shows addrVar with the value:
After executing the syntax shown in Example 12–35 in the BPEL process service
component file, the second address line of Mailstop is removed:
After executing the syntax shown in Example 12–36 in the BPEL process service
component file, both address lines are removed:
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 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 12–38:
Promotion changes are now applied to Peter Smith in the employee list in
Example 12–39:
12-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data with bpelx Extensions
</bpelx:rename>
</bpel:assign>
After executing the above casting (renaming), the data looks as shown in
Example 12–40 with xsi:type info added to Peter Smith:
The employee data of Peter Smith is now invalid, because <approvalLimit> and
<managing> are missing. Therefore, <append> is used to add that information.
Example 12–41 provides an example.
With the execution of both rename and append, the corresponding data looks as
shown in Example 12–42:
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:
■ Removes all the nodes pointed to by the to-spec query
■ If the to-spec query returns a list of element nodes and there are leftover child
nodes after removal of those nodes, the nodes returned by the from-spec query
are inserted before the next sibling of the last element specified by the to-spec
query. If there are no leftover child nodes, an append operation is performed.
■ If the to-spec query returns a list of attribute nodes, those attributes are removed
from the parent element. Then, the attributes returned by the from-spec query
are appended to the parent element.
12-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data Sequences That Resemble Arrays
For example:
<bpelx:validate variables="myMsgVariable myPOElemVar" />
If you want to verify the validity of XML data, set the validateXML property to true
in oc4j\j2ee\oc4j_
soa\applications\soa-infra\configuration\bpel-config.xml.
12.15.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 12–44, addresses[1] selects the first element of the addresses data
sequence:
Language (XPath) Specification). The query in Example 12–45 calls the position
function explicitly to select the first element of the addresses data sequence. It then
selects that address’s street element (which the activity assigns to the variable
street1).
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.
For more information, see the SOA_Oracle_
Home\bpel\samples\references\XPath sample.
12-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data Sequences That Resemble Arrays
Assume at run time that the idx integer variable holds 2 as its value. The preceding
expression within the from is equivalent to:
<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.
For example:
bpws:getVariableData('input', 'payload',
'/p:invoice/p:line-item[2]/p:line-total')
This is because the node returned by the getVariableData() function is already the
root element. Specifying the root element name again in the XPath is redundant and is
incorrect according to standard XPath semantics.
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 others words, the payload element of output variable is used as the
parent element.
For more information, see the SOA_Oracle_
Home\bpel\samples\tutorials\126.DataAggregator\AggregationTutori
al sample.
For more information, see the ArraySample.bpel sample file located at SOA_
Oracle_Home\bpel\samples\tutorials\112.Arrays.
12-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating XML Data Sequences That Resemble Arrays
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:
■ Add attribute and child elements to those empty lineItem elements.
■ Perform copy operations to replace the empty elements. For example, copy from a
Web service result to an individual entry in this equivalent array under a flowN
activity.
This is in contrast to RPC-style WSDL files, in which the message is defined with an
XML schema type, as in Example 12–53:
12-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating SOAP Headers in BPEL
<complexType name="LoanOfferType">
<sequence>
<element name="providerName" type="string"/>
<element name="selected" type="boolean"/>
<element name="approved" type="boolean"/>
<element name="APR" type="double"/>
</sequence>
</complexType>
each of the two attributes. This is enough if the particular operation involved uses only
one payload message in each direction.
However, WSDL supports more than one message in an operation. In the case of
SOAP, multiple messages can be sent along the main payload message as SOAP
headers. However, BPEL's default communication activities cannot accommodate the
additional header messages.
Oracle BPEL Process Manager solves this problem by extending the default BPEL
communication activities with the bpelx:headerVariable extension. The extension
syntax is as follows:
12-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Manipulating SOAP Headers in BPEL
</operation>
</binding>
2. Create a BPEL source file that declares the header message variables and uses
bpelx:headerVariable to receive the headers.
<sequence>
<!-- receive input from requestor -->
<receive name="receiveInput" partnerLink="client"
portType="tns:HeaderService" operation="initiate"
variable="input"
bpelx:headerVariable="customHeader messageID replyTo"
createInstance="yes"/>
12-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
13
13 Invoking a Synchronous Web Service from a
BPEL Process
This chapter describes how to invoke a synchronous web service from a BPEL process.
This chapter demonstrates how to create a partner link and invoke activity and set up
the components necessary to perform a synchronous callback. This chapter also
examines how these components are coded.
This chapter includes the following sections:
■ Section 13.1, "Introduction to Invoking a Synchronous Web Services"
■ Section 13.2, "Invoking a Synchronous Web Service"
■ Section 13.3, "Use Case for Invoking a Synchronous Web Service"
Beta Draft Invoking a Synchronous Web Service from a BPEL Process 13-1
Invoking a Synchronous Web Service
13-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking a Synchronous Web Service
Following the partner link are global variable definitions that are accessible
throughout the BPEL process service component. The types for these variables are
defined in the WSDL for the process itself. Example 13–2 provides an example.
The WSDL file defines the interface to your BPEL process service component—the
messages that it accepts and returns, operations that are supported, and other
parameters.
Beta Draft Invoking a Synchronous Web Service from a BPEL Process 13-3
Invoking a Synchronous Web Service
13.2.2.2 Partner Link Type and Port Type in the BPEL Code
The Web service’s QuoteConsumer.wsdl file contains two sections that enable the
web service to work with BPEL process service components:
■ Section 13.2.2.2.1, "partnerLinkType Section of the QuoteConsumer.wsdl File"
■ Section 13.2.2.2.2, "portType Section of the QuoteConsumer.wsdl File"
13-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking a Synchronous Web Service
Synchronous services have one port type. The port initiates the synchronous process
and calls back the client with the response. In this example, the portType
CreditRatingService receives the stock code and returns the stock quote.
Beta Draft Invoking a Synchronous Web Service from a BPEL Process 13-5
Use Case for Invoking a Synchronous Web Service
<!-- Generate content of output message based on the content of the input message.
-->
<assign>
<copy>
<from variable="response" part="result" query="/result"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
</assign>
13-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
14
14 Invoking an Asynchronous Web Service
from a BPEL Process
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-1
Introduction to Invoking an Asynchronous Web Service
BPEL Process
Input
Client WSDL <variable>
Application Client
PartnerLink
d1 <receive>
prepare
loanApp
<assign>
WSDL
Request LoanService
<variable> PartnerLink
Initiate
service
<invoke> Initiate Port
d3 Async
Loan
Callback Port Processor
Wait for d4 Service
callback
<receive>
Response
<variable>
Read
offer
<assign>
d2 <reply>
Dehydration Point
Output For scalability and reliability,
<variable> in-flight instances are pushed
to DB until callback is received
For the asynchronous Web service, which is indicated within the dotted rectangle
between the BPEL process service component’s receive and reply activities, the
following actions take place:
1. An assign activity (prepare LoanApp) prepares the loan application.
2. An invoke activity (initiate service) 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 (Wait for callback), which has been tracked by the correlation ID.
4. An assign activity (Read offer) reads the loan application offer.
The remaining sections in this chapter provide specific details about the asynchronous
functionality shown in Figure 14–1.
For more information about asynchronous services, see the following files:
■ SOA_Oracle_
Home\bpel\samples\utils\AsyncLoanService\LoanService.wsdl
14-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking an Asynchronous Web Service
■ SOA_Oracle_
Home\bpel\samples\tutorials\105.AsyncCompositeLoanBroker\bpel
\LoanBroker.bpel
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-3
Invoking an Asynchronous Web Service
5. Click OK.
A new partner link for the loan application approver Web service (United Loan)
appears in the Services area of the .bpel file’s diagram window.
For more information about partner links, see the following:
■ Section 14.2.2.1, "portType Section of the LoanService.wsdl File"
■ Section 14.2.2.2, "partnerLinkType Section of the LoanService.wsdl File"
14-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking an Asynchronous Web Service
■ 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.
Figure 14–3 shows the Create Variable dialog.
7. Click OK.
8. Double-click the invoke activity to display the Invoke window.
9. In the Invoke window, select the LoanService partner link from the Partner Link
list and initiate from the Operation list.
10. Select the input variable you created in Step 6, by clicking the second icon to the
right of the Input Variable field.
The Variable Chooser window appears, where you can select the variable.
There is no output variable specified because the output variable is returned in the
receive operation. The invoke activity is created.
For more information about the invoke activity, see Section 14.2.2.5, "Invoke and
Receive Activities."
11. Click OK.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-5
Invoking an Asynchronous Web Service
14-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking an Asynchronous Web Service
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.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-7
Invoking an Asynchronous Web Service
<partnerLink name="LoanService"
partnerLinkType="services:LoanService"
myRole="LoanServiceRequester"
partnerRole="LoanServiceProvider"/>
</partnerLinks>
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 a
myRole and partnerRole attribute in asynchronous processes.
<component name="LoanBroker">
<implementation.bpel process="LoanBroker.bpel"/>
</component>
For more information, see Section 14.2.1.1, "Step 1: Adding a Partner Link for an
Asynchronous Service" for instructions on creating a partner link.
14-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Invoking an Asynchronous Web Service
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.
Example 14–5 provides an example.
<variables>
<variable name="request"
messageType="services:LoanServiceRequestMessage"/>
<variable name="response"
messageType="services:LoanServiceResultMessage"/>
</variables>
<sequence>
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-9
Using WS-Addressing in an Asynchronous Service
14-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using WS-Addressing in an Asynchronous Service
WS-Addressing Header:
BPEL Process · callback location
HelloWorld.bpel · correlation id (relatesTo)
WSDL
LoanService [2.05] receive
loanApp PartnerLink [2.06] process
<variable> [2.22] callback
Initiate Initiate Port
service d3 d3
<invoke>
Async
loanOffer Loan
<variable> Processor
Service
Wait for Callback Port
callback d3 d4
<receive>
WS-Addressing Header:
· correlation id (relatesTo)
Note 1: the correlation id allows
the BPEL server to know which
instance of the process is
waiting for this callback
messages.
Note 2: The alternative
approach is to use
content-based correlation
using <correlationSet>
Figure 14–5 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 14.3.1.1, "Using
TCP Tunneling to See 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:
■ Endpoint location (reply-to address): The reply-to address specifies the location at
which a BPEL client is listening for a callback message.
■ 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.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-11
Using WS-Addressing in an Asynchronous Service
14.3.1.1.1 Setting up a TCP Listener for Synchronous Services Follow these steps to set up a
TCP listener for synchronous services initiated by an Oracle BPEL Process Manager
process:
1. Start your TCP listener to listen on a port such as 1234 and send on a port such as
9700 (port 9700 is used in this example and is the default after Oracle BPEL
Process Manager for Developers installation). If you installed Oracle BPEL Process
Manager as part of an Oracle Application Server SOA install type, substitute the
correct port number throughout these instructions. For example, you can use the
TCP tunnel included with Apache Axis (bundled with Oracle BPEL Process
Manager) by executing the following from the operating system command
prompt:
prompt> obsetenv
prompt> java -classpath %OB_CLASSPATH% orabpel.apache.axis.utils.tcpmon 1234
localhost 9700
Note that while the CreditRatingService is also a BPEL process service component,
the same technique can be used to see the SOAP messages passed to invoke a
BPEL process service component as a Web service from another tool kit such as
Axis or .NET.
14-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
14.3.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 such as 9710 and to send on the Oracle
BPEL Process Manager port (for example, 9700 is the default after installation of
Oracle BPEL Process Manager for Developers).
2. Turn off the optimization of local SOAP calls performed by Oracle BPEL Process
Manager to see the impact of changing the callback port:
a. Go to Oracle Enterprise Manager 10g Application Server Control Console.
b. Go to the Configuration tab for the deployed composite application.
c. Scroll down to the optSoapShortcut property.
d. Change the value from true to false.
3. Go to the SoapServerUrl property on the Configuration tab.
4. Change this property to http://localhost:9710.
5. Click the Apply button.
6. Restart Oracle BPEL Server to initialize these changes and initiate any flow that
invokes asynchronous Web services (for example the LoanFlow demonstration).
You can combine this with the synchronous TCP tunneling configuration to send
the UnitedLoan service initiation request through your first TCP tunnel.
The callbacks from the asynchronous services are shown in the TCP listener, such
as the UnitedLoan service callback.
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.
For more information, see the following documents:
■ Web Services Addressing (WS-Addressing) Specification for complete details about
WS-Addressing, which is accessible from
http://www.oracle.com/technology/bpel
■ SOA_Oracle_Home/bpel/samples/demos/LoanDemo for the LoanFlow demo
used in this section
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-13
Using Correlation Sets in an Asynchronous Service
example, when the conversation is in the form A > B > C > A instead of A > B >
A.
This section describes how to use correlation sets in an asynchronous service with
Oracle JDeveloper. Correlation sets enable you to correlate asynchronous messages
based on message body contents. You define correlation sets when interactions are not
simple invoke-receive activities. This example illustrates how to use correlation sets
for a process having three receive activities with no associated invoke activities.
For more information, see the following correlation set example at SOA_Oracle_
Home\bpel\samples\tutorials\109.CorrelationSets.
Field Value
Application Name Enter an application name (for this example,
MyCorrelationSetApp).
Application Template Select No Template [All Technologies].
4. Accept the default values for all remaining settings, and click OK.
5. Click Cancel in the Create Project window.
6. Select the Application Menu list for the application you just created.
7. Select New Project from the list that appears.
The New Gallery window appears.
8. Double-click SCA Project in the Items field.
The Create SCA Project window appears.
9. Enter the following values:
Field Value
Project Name Enter a name in the field (for this example,
MyCorrelationSetComposite).
14-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
Field Value
Upon project creation, create Click the check box and select BPEL Process from the list.
This creates an SCA project with a BPEL process.
Field Value
Name Enter MyCorrelationSet.
Namespace Accept the default value.
Template Select Asynchronous BPEL Process.
Expose as Composite Service Select the check box. After process creation, note the
SOAP adapter service that appears in the Services
swimlane. This service provides the entry point to the
composite application from the outside world.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-15
Using Correlation Sets in an Asynchronous Service
5. Select File Adapter on the Configure Service or Adapter window and click Next.
6. Click Next on the Welcome window.
7. Enter FirstReceive in the Service Name field on the Service Name window and
click Next.
8. Select Read File as the Operation Type on the Operation window and click Next.
The Operation Name field is automatically filled in with Read.
9. Select Directory Names are Specified as Physical Path.
10. Click Browse above to the Directory for Incoming Files (physical path) field.
11. Select a directory from which to read files (for this example,
C:\files\receiveprocess\FirstInputDir is selected).
12. Click Select.
14. Enter appropriate file filtering parameters in the File Filtering window.
16. Enter appropriate file polling parameters in the File Polling window.
18. Click Browse next to the Schema Location field in the Messages window to
display the Type Chooser window.
19. Select an appropriate XSD schema file. For this example, Book1_4.xsd is the
schema and LoanAppl is the schema element selected.
20. Click OK.
The Schema Location field (Book1_4.xsd for this example) and the Schema
Element field (LoanAppl for this example) are filled in.
21. Click Next.
Field Value
Name FirstReceive
WSDL File file:/C:/JDeveloper/mywork/Application_Name/SOA_Project_
Name/FirstReceive.wsdl
where C:/JDeveloper represents the Oracle JDeveloper home directory
for this example.
Partner Link Type Read_plt
Partner Role Leave unspecified.
My Role Read_role
14-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
14.4.1.2.2 Creating a Second Partner Link and File Adapter Service 1.Drag and drop a
second PartnerLink activity below the FirstReceivePL partner link activity.
2. Click the third icon at the top (the Define Adapter Service icon).
3. Click Next on the Welcome window.
4. Select File Adapter in the Adapter Type window and click Next.
5. Enter SecondFileRead in the Service Name field on the Service Name window
and click Next. This name must be unique from the one you entered in Step 7 on
page 14-16.
6. Select Read File as the Operation Type in the Operation window
7. Change the name in the Operation Name field to Read1.
8. Click Next.
9. Select Directory Names are Specified as Physical Path.
10. Click Browse above to the Directory for Incoming Files (physical path) field.
11. Select a directory from which to read files (for this example,
C:\files\receiveprocess\SecondInputDir is entered).
12. Click Select.
14. Enter appropriate file filtering parameters in the File Filtering window.
16. Enter appropriate file polling parameters in the File Polling window.
18. Click Browse next to the Schema Location field in the Messages window to
display the Type Chooser window.
19. Select an appropriate XSD schema file. For this example, Book1_5.xsd is the
schema and LoanAppResponse is the schema element selected.
20. Click OK.
The Schema Location field (Book1_5.xsd for this example) and the Schema
Element field (LoanAppResponse for this example) are filled in.
21. Click Next.
Field Value
Name SecondReceive
WSDL File file:/C:/JDeveloper/mywork/Application_Name/SOA_Project_
Name/SecondFileRead.wsdl
where C:/JDeveloper represents the Oracle JDeveloper home directory
for this example.
Partner Link Type Read1_plt
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-17
Using Correlation Sets in an Asynchronous Service
Field Value
Partner Role Leave unspecified.
My Role Read1_role
11. Select a directory from which to read files (for this example,
C:\files\receiveprocess\ThirdInputDir is entered).
12. Click Select.
14. Enter appropriate file filtering parameters in the File Filtering window.
15. Click Next.
16. Enter appropriate file polling parameters in the File Polling window.
18. Click Browse next to the Schema Location field in the Messages window to
display the Type Chooser window.
19. Select an appropriate XSD schema file. For this example, Book1_6.xsd is the
schema and CustResponse is the schema element selected.
20. Click OK.
The Schema Location field (Book1_6.xsd for this example) and the Schema
Element field (CustResponse for this example) are filled in.
21. Click Next.
14-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
Field Value
Name ThirdReceive
WSDL File file:/C:/JDeveloper/mywork/Application_Name/SOA_Project_
Name/ThirdFileRead.wsdl
where C:/JDeveloper represents the Oracle JDeveloper home directory
for this example.
Partner Link Type Read2_plt
Partner Role Leave unspecified.
My Role Read2_role
Field Value
Name receiveFirst
Partner Link FirstReceive
Create Instance Select this check box.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-19
Using Correlation Sets in an Asynchronous Service
14.4.1.3.2 Creating an Initial Receive Activity 1.Drag and drop a second Receive activity
from the Component Palette section to below the receiveFirst receive activity.
2. Double-click the receive icon to display the Receive window.
3. Enter the following details to associate the second partner link (SecondReceivePL)
with the second receive activity:
Field Value
Name receiveSecond
Partner Link SecondFileRead
Create Instance Do not select this check box.
Field Value
Name receiveThird
Partner Link ThirdFileRead
Create Instance Do not select this check box.
14-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-21
Using Correlation Sets in an Asynchronous Service
6. Click OK.
9. Click OK.
This groups the first and second receive activities into a correlated group.
14-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Correlation Sets in an Asynchronous Service
6. Click OK.
This groups the second and third receive activities into a second correlated group.
14.4.1.6.1 Creating Property Aliases for NameCorr 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 FirstReceivePL 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
SecondReceivePL partner link (defined by the SecondFileRead.wsdl file).
1. Right-click Property Aliases in the Structure section of Oracle JDeveloper.
2. Select Create Property Alias.
3. Select NameCorr in the Property list.
4. Expand and select Message Types > Web Services > FirstReceivePL >
FirstReceive.wsdl > Message Types > LoanAppl_msg > Part - LoanAppl.
5. Press Ctrl and then the space bar in the Query field 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.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-23
Using Correlation Sets in an Asynchronous Service
9. Press Ctrl and then the space bar in the Query field 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. Press Ctrl and then the space bar in the Query field to define the following XPath
expression:
/ns6:CustResponse/ns6:APR
14-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Case for Invoking a Asynchronous Web Service
<bpws:propertyAlias propertyName="ns1:NameCorr"
messageType="ns5:LoanAppResponse_msg"
part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>
<bpws:propertyAlias propertyName="ns1:IDCorr"
messageType="ns5:LoanAppResponse_msg"
part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>
<bpws:propertyAlias propertyName="ns1:IDCorr"
messageType="ns7:CustResponse_msg"
part="CustResponse" query="/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. Example 14–9 provides an
example.
Beta Draft Invoking an Asynchronous Web Service from a BPEL Process 14-25
Use Case for Invoking a Asynchronous Web Service
14-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
15
15 Parallel Flow in a BPEL Process
Parallel flows enable a BPEL process service component to perform multiple tasks at
the same time, which is especially useful when you need to perform several
time-consuming and independent tasks.
This chapter includes the following sections:
■ Section 15.1, "Introduction to Parallel Flows in BPEL Processes"
■ Section 15.2, "Creating a Parallel Flow in a BPEL Process"
■ Section 15.3, "Customizing the Number of Flow Activities with the flowN
Activity"
■ Section 15.4, "Use Case for Parallel Flows"
BPEL
Process
<flow>
WSDL WSDL
<sequence> <sequence>
Initiate Initiate
service service
<invoke> <invoke>
United Star
Loan Loan
Wait for Wait for
callback callback
<receive> <receive>
15.3 Customizing the Number of Flow Activities with the flowN Activity
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 run time 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. Then the
process 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
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.
15-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Number of Flow Activities with the flowN Activity
Figure 15–2 shows an Oracle Enterprise Manager 11g Application Server Control
Console view of a flowN activity 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 15–2 Oracle Enterprise Manager 11g Application Server Control Console View of
the Execution of a flowN activity
Figure 15–4 shows the flowN Window, which appears when you double-click the
flowN activity.
The flowN windows enables you to name the flowN activity, enter an expression for
calculating the value of N, and define the index variable.
1. From the Component Palette, drag a flowN activity into the designer.
15-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Number of Flow Activities with the flowN Activity
2. The receive activity calls the client partner link to get the information that the
flowN activity needs to define N and look up hotel information. Example 15–2
provides an example.
3. 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 15–3
provides an example.
4. Next, the copy rule shown in Example 15–4 uses the index variable to concatenate
the hotel entries into a list:
5. Using the hotel information, an invoke activity looks up detailed information for
each hotel through a Web service. Example 15–5 provides an example.
6. Finally, the BPEL process sends detailed information on each hotel to the client
partner link. Example 15–6 provides an example.
15-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Case for Parallel Flows
15-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
16
16 Conditional Branching in BPEL Processes
stored in its own global variable. To compare the two offers and make decisions based
on that comparison, the BPEL flow requires a switch activity.
Figure 16–1 provides an overview of a BPEL conditional branching process that has
been defined in a switch activity.
BPEL
Process
<switch> ?
<case <otherwise>
conditon 1>
Select Select
unitedLoan starLoan
<assign> <assign>
5. Right-click the first branch and select Edit from the menu.
16-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Adding a Switch Activity to Define Conditional Branching
7. Enter this expression on one line. To use the XPath Expression Builder, click the
XPath Expression Builder icon above the Expression field.
The two loan offers that the LoanFlow tutorial uses are stored in the global
variables loanOffer1 and loanOffer2. Each loan offer variable contains the
loan offer’s 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 loanOffer2’s payload to selectedLoanOffer’s payload.
■ If loanOffer1 does not have the lower APR than loanOffer2, then the
otherwise case assigns loanOffer1’s payload to selectedLoanOffer’s
payload.
For more information, see the SOA_Oracle_
Home\bpel\samples\references\Switch example of creating switch activities
in Oracle JDeveloper.
</otherwise>
</switch>
2. Drag the activity that you want to use to define the while condition onto the Drop
Activity Here area of the while activity.
The activity can be an existing activity or a new activity, such as an invoke activity
to launch a task.
For more information, see SOA_Oracle_
Home\bpel\samples\references\While for examples of defining a while
activity in Oracle JDeveloper.
16-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Case for Conditional Branching
16-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
17
17 Fault Handling in BPEL Processes
Fault handling allows a BPEL process service component to handle error messages or
other exceptions returned by outside Web services, and to generate error messages in
response to business or run-time faults.
This chapter contains the following topics:
■ Section 17.1, "Use Case for Fault Handling"
■ Section 17.2, "Defining a Fault Handler"
■ Section 17.3, "BPEL Standard Faults"
■ Section 17.4, "Categories of BPEL Faults"
■ Section 17.5, "Getting Fault Details with the getFaultAsString XPath Extension
Function"
■ Section 17.6, "Using the Scope Activity to Manage a Group of Activities"
■ Section 17.7, "Throwing Internal Faults"
■ Section 17.8, "Returning External Faults"
■ Section 17.9, "Using a Fault Handler within a Scope"
■ Section 17.10, "Using Compensation After Undoing a Series of Operations"
■ Section 17.11, "Using the Terminate Activity to Stop a Business Process Instance"
WSDL BPEL
Process
d1 <receive>
WSDL
<scope> Negative
Credit
prepare
crin
<assign> d3
Credit
Rating
Service
call f1
service
<invoke>
Read
crOut
<assign>
<scope>
credit to
-1000
<assign>
d2 <reply>
The following code segment defines the fault handler for this operation:
<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>
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.
17-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Categories of BPEL Faults
a logic error occurs (such as an endless loop), a SOAP fault occurs in a SOAP call, an
exception is thrown by Oracle BPEL Server, and so on.
Oracle BPEL Server includes several run-time faults. These faults are included in the
http://schemas.oracle.com/bpel/extension namespace. These faults are
associated with the messageType RuntimeFaultMessage. The following WSDL
file defines the messageType:
<?xml version="1.0" encoding="UTF-8" ?>
<definitions name="RuntimeFault"
targetNamespace="http://schemas.oracle.com/bpel/extension"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="RuntimeFaultMessage">
<part name="code" type="xsd:string" />
<part name="summary" type="xsd:string" />
<part name="detail" type="xsd:string" />
</message>
</definitions>
17.4.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. Table 17–1
describes the fault codes.
17-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Getting Fault Details with the getFaultAsString XPath Extension Function
17.4.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. A remoteFault
can be configured to be retried. Table 17–2 describes the fault codes.
17.4.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. Oracle BPEL Server then re-executes the scope from
the beginning.
</catchAll>
17-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using a Fault Handler within a Scope
See Also:
■ Chapter 16, "Conditional Branching in BPEL Processes" for more
information on setting up the conditional structure
■ Chapter 13, "Invoking a Synchronous Web Service from a BPEL
Process" for more information on synchronous interactions
See Also:
■ Chapter 14, "Invoking an Asynchronous Web Service from a BPEL
Process" for more information on asynchronous interactions
You can use specific fault names in the catch activity to respond in a specific way to an
individual fault. To catch any faults that are not already handled by name-specific
catch activities, use the catchAll activity.
17.9.1 Using the 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. The syntax to use an empty activity is as
follows:
<empty standard-attributes>
standard-elements
</empty>
If no catch or catchAll 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 17.11, "Using the Terminate Activity to Stop a Business
Process Instance" on page 17-9) had been performed.
Consider the following example:
<faulthandlers>
<catch faultName="x:foo">
<empty/>
</catch>
<catch faultVariable="bar">
<empty/>
</catch>
<catch faultName="x:foo" faultVariable="bar">
<empty/>
</catch>
<catchAll>
<empty/>
</catchAll>
</faulthandlers>
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.
17-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the Terminate Activity to Stop a Business Process Instance
flight for the right day. In this case, the BPEL flow performs compensation by going
back and unbooking the car and the hotel.
You can invoke a compensation handler by using the compensate activity, which
names the scope for which the compensation is to be performed (that is, the scope
whose compensation handler is to be invoked). A compensation handler for a scope is
available for invocation only when the scope completes normally. Invoking a
compensation handler that has not been installed is equivalent to using the empty
activity (it is a no-op). This ensures that fault handlers do not have to rely on state to
determine which nested scopes have completed successfully. The semantics of a
process in which an installed compensation handler is invoked more than once are
undefined.
If an invoke activity has a compensation handler defined inline, then the name of the
activity is the name of the scope to be used in the compensate activity. The syntax is as
follows:
<compensate scope="ncname"? standard-attributes>
standard-elements
</compensate>
The ability to explicitly invoke the compensate activity is the underpinning of the
application-controlled error-handling framework of Business Process Execution
Language for Web Services Specification. You can use this activity only in the following
parts of a business process:
■ In a fault handler of the scope that immediately encloses the scope for which
compensation is to be performed.
■ In the compensation handler of the scope that immediately encloses the scope for
which compensation is to be performed.
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.
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 a compensation for such a scope nested within the
outer scope disables the availability of default-order compensation.
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.
The syntax for the terminate activity is as follows:
<terminate standard-attributes>
standard-elements
</terminate>
17-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
18
18 Incorporating Java and J2EE Code
in BPEL Processes
You can incorporate sections of Java code and PL/SQL procedures into BPEL process
service components in SOA applications.
This chapter includes the following sections:
■ Section 18.1, "Introduction to Java and J2EE Code in BPEL Concepts"
■ Section 18.2, "Using Java Embedding in a BPEL Process"
■ Section 18.3, "Using PL/SQL Procedures with SOA Applications"
Beta Draft Incorporating Java and J2EE Code in BPEL Processes 18-1
Introduction to Java and J2EE Code in BPEL Concepts
18.1.2.1 Using the bpelx:exec Tag to Embed Java Code Snippets into a BPEL
Process
The BPEL tag bpelx:exec enables you to embed a snippet of Java code within a
BPEL process. 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 18–1 to embed the invokeSessionBean Java bean:
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);
}
18-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Java and J2EE Code in BPEL Concepts
]]>
</bpelx:exec>
To generate the facade classes, use the schemac tool, which is provided with Oracle
BPEL Process Manager. You can find the schemac tool in the following locations:
■ SOA_Oracle_Home\bpel\bin
To use schemac, run a command similar to the following to generate the facades from
WSDL or XSD files:
C:\BPEL_project_dir\> schemac *.wsdl /*.xsd
After you run schemac, it creates a src folder for a HelperService.java service
and a com folder for the generated Java classes. Oracle provides a sample in the
following directories that showcases the use of facade classes in Java bindings:
■ SOA_Oracle_
Home\bpel\samples\tutorials\702.Bindings\JavaBinding
When it generates the facade, schemac uses the following files:
■ Using build.xml, schemac generates the source of the facade classes.
■ The schemac tool creates a Java binding provider class HelperService.java,
which in the 702.Bindings example is located under
702.Bindings\JavaBinding\src\com\otn\services. It has one method,
which uses the facade classes CommentsType and CommentType:
public CommentsType addComment(CommentsType payload, CommentType comment)
■ To map the XML types to the corresponding facade classes, a Java binding service
is defined in the HelperService.wsdl file. See the format:typeMapping
section of Java binding in Example 18–3:
Beta Draft Incorporating Java and J2EE Code in BPEL Processes 18-3
Introduction to Java and J2EE Code in BPEL Concepts
<format:typeMap typeName="tns:commentsType"
formatType="com.otn.services.CommentsType" />
</format:typeMapping>
18-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using Java Embedding in a BPEL Process
Beta Draft Incorporating Java and J2EE Code in BPEL Processes 18-5
Using PL/SQL Procedures with SOA Applications
18-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using PL/SQL Procedures with SOA Applications
Beta Draft Incorporating Java and J2EE Code in BPEL Processes 18-7
Using PL/SQL Procedures with SOA Applications
18-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
19
19 Events and Timeouts in BPEL Processes
This chapter describes how to use events and timeouts. Because Web services can take
a long time to return a response, a BPEL process service component must be able to
time out and continue with the rest of the flow after a period of time.
This chapter includes the following sections:
■ Section 19.1, "Introduction to Event and Timeout Concepts"
■ Section 19.2, "Adding a Pick Activity to Select Between Continuing a Process or
Waiting"
■ Section 19.3, "Adding a Wait Activity to Set an Expiration Time"
■ Section 19.4, "Setting Timeouts for Synchronous Processes"
■ Section 19.5, "Use Case for Events and Timeouts"
■ 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 stands for seconds, M for one minute, H for hour, D for day,
and Y 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.
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 then is not executed.
BPEL
Process
Initiate
service
<invoke>
<pick> WSDL
19-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Adding a Pick Activity to Select Between Continuing a Process or Waiting
4. Double-click the OnAlarm branch of the pick activity shown and set its time limit
to 1 minute instead of 1 hour. Figure 19–3 provides an example.
5. Click OK.
6. Double-click the onMessage branch, and edit its attributes to receive the response
from the loan service. Figure 19–4 provides an example.
<assign>
<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>
19-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Setting Timeouts for Synchronous Processes
19-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
20
20 Invoking a BPEL Process Service
Component
This chapter shows how to invoke a BPEL process service component to perform
functions or use services.
This chapter contains the following topics:
■ Section 20.1, "Use Case for Invoking a BPEL Process Service Component"
■ Section 20.2, "Sending Messages to a BPEL Process Service Component"
BPEL Process
WSDL
Client
SOAP / PartnerLink
<receive>
WSDL
Java
Business
Delegate
<reply>
20.2.1 Invoking a BPEL Process Service Component with the Web Service/SOAP
Interface
After you deploy a BPEL process service component to Oracle BPEL Server, it is
automatically published as a Web service. This means that the process can be accessed
through its XML/SOAP/WSDL interface without any additional developer effort.
Supporting a standard Web services interface means that BPEL processes can be
invoked from any client technology that supports Web services. This includes
Microsoft .NET, Sun’s JAX-RPC implementation, Apache Axis, Oracle JDeveloper, and
many other Web services tool kits. In addition, it means that BPEL and Oracle BPEL
Process Manager can publish Web services. Those services, both synchronous and
asynchronous, can be invoked from applications and services implemented with
nearly any technology and language.
You access a BPEL process service component through its Web service interface in the
standard way you access any Web service: by writing a client that uses the BPEL
process service component WSDL interface definition and SOAP as a protocol.
20-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
21
21 Coordinating Master and Detail Processes
This chapter describes master and detail process coordinations. This coordination
enables you to specify the tasks performed by a master BPEL process and its related
detail BPEL processes. This is sometimes referred to as a parent and child relationship.
This chapter includes the following sections:
■ Section 21.1, "Introduction to Master and Detail Process Coordinations"
■ Section 21.2, "Defining Master and Detail Process Coordination in Oracle
JDeveloper"
For more information about master and detail coordinations, see the sample located in
the bpel\tutorials\T116_MasterDetailApp directory of the
soa-samples.zip file
■ Each detail process must signal the master process after the line item is available in
inventory.
■ 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 21–1 provides an overview of the header and line item validation coordination
points between one master process and two detail processes.
Figure 21–1 Master and Detail Coordination Overview (One BPEL Process to Two Detail Processes)
The following BPEL process activities coordinate actions between the master and
detail processes:
■ signal — notifies the other processes (master or detail) to continue processing
■ receive signal — waits until it receives the proper notification signal from the other
process (master or detail) before continuing its processing
Both activities are coordinated with label attributes defined in the BPEL process files.
Labels are declared per master process definition.
Figure 21–2 provides an overview of the BPEL process flow coordination.
21-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Master and Detail Process Coordinations
Figure 21–2 Master and Detail Syntax Overview (One BPEL Process to One Detail Process)
Signal Activity
label="startDetailProcess"
to="details"
As shown in Figure 21–2, each master and detail process includes a signal and receive
signal activity. Table 21–1 describes activity responsibilities based on the type of
process in which they are defined.
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.
myRole="MasterProcessProvider"
partnerRole="MasterProcessRequester"/>
<partnerLink name="DetailProcess"
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 four 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 four detail processes at runtime.
<bpelx:signal name="notifyDetailProcess" label="startDetailProcess" to="details"/>
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.
Within the invoke activity, the bpelx:invokeAsDetail attribute is set to true. This
attribute creates the partner process instance (DetailProcess) as a detail instance.
You must manually add this attribute and set the value to true in the master process
file for each detail process with which to interact. Example 21–2 provides an example.
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 21–3 provides an example.
21-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Master and Detail Process Coordinations
The second invoke activity invokes the DetailsProcess1 detail process and
associates it with a label of detailProcessComplete1. Example 21–5 provides an
example.
The third invoke activity invokes the DetailsProcess2 detail process again through
a different port and with a different input variable. It associates the
DetailsProcess2 detail process with a label of detailProcessComplete1-2:
The receive signal activity of the master process shown in Example 21–7 waits for a
return signal from detail process DetailProcess0.
The second receive signal activity of the master process shown in Example 21–8 also
waits for a return signal from DetailProcess1 and DetailProcess2.
Note: If there is only one receive signal activity in the BPEL process,
do not specify the bpelx:detailLabel attribute in the invoke
activity. In these situations, a default bpelx:detailLabel attribute is
assumed and does not need to be specified.
A signal activity indicates that the detail process shown in Example 21–10 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.
Note: This section only describes the tasks specific to master and
detail process coordination. It does not describe the standard activities
that you define in a BPEL process, such as creating variables, creating
assign activities, and so on.
21-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Defining Master and Detail Process Coordination in Oracle JDeveloper
Field Value
Name Enter a name (for this example, contactDetailProcess).
Label Enter a label name (for this example, beginDetailProcess). This label
must match the receive signal activity label you set in the detail
process in Step 5 on page 21-8.
To Select details as the type of process to receive this signal.
7. Click OK.
8. Drag and drop a Receive Signal activity into your BPEL process service
component.
9. Double-click the Receive Signal activity.
This activity enables the master process to wait until it receives the signal executed
by all of its detail processes.
10. Enter the following details:
Field Value
Name Enter a name (for this example, waitForDetailProcess).
Label Enter a label name (for this example, completeDetailProcess). This
label must match the signal activity label you set in the detail process
in Step 9 on page 21-9.
To Select details as the type of process from which to receive the signal.
Field Value
Name Enter a name (for this example, WaitForContactFromMasterProcess).
21-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Defining Master and Detail Process Coordination in Oracle JDeveloper
Field Value
Label Enter a label name (for this example, beginDetailProcess). This label
must match the signal activity label you set in the master process in
Step 6 on page 21-7.
To Select master as the type of process from which to receive the signal.
6. Click OK.
7. Drag and drop a Signal activity into your BPEL process service component.
8. Double-click the Signal activity.
This activity enables the detail process to signal its associated master process at
runtime that processing is complete.
9. Enter the following details:
Field Value
Name Enter a name (for this example, contactMasterProcess).
Label Enter a label name (for this example, completeDetailProcess). This
label must match the receive signal activity label you set in the master
process in Step 10 on page 21-7.
To Select master as the destination.
21-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Defining Master and Detail Process Coordination in Oracle JDeveloper
c. Repeat these steps as necessary for additional detail processes, ensuring that
you specify a different label value.
9. Select Save All from the File main menu.
Master and detail coordination design is now complete.
21-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
22
22 Interaction Patterns in BPEL Processes
This chapter identifies common interaction patterns between a BPEL process service
component and another application, and shows the best use practices for each.
This chapter includes the following sections:
■ Section 22.1, "One-Way Message"
■ Section 22.2, "Synchronous Interaction"
■ Section 22.3, "Asynchronous Interaction"
■ Section 22.4, "Asynchronous Interaction with Timeout"
■ Section 22.5, "Asynchronous Interaction with a Notification Timer"
■ Section 22.6, "One Request, Multiple Responses"
■ Section 22.7, "One Request, One of Two Possible Responses"
■ Section 22.8, "One Request, a Mandatory Response, and an Optional Response"
■ Section 22.9, "Partial Processing"
■ Section 22.10, "Multiple Application Interactions"
■ Section 22.11, "Summary"
d2
OR
f1 <reply>
22-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Asynchronous Interaction
Get
response d2 <invoke>
<receive>
WSDL
PartnerLink
Call
service d1 <receive>
<invoke>
<pick>
d2 <invoke>
Wait for Time out
callback in 1M
<onMessage> <onAlarm>
Logic Logic
Post Post
Callback Timeout
22-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
One Request, Multiple Responses
WSDL
<scope> PartnerLink
Call d1 <receive>
service
<invoke>
Wait for
Callback d2 <invoke>
<receive>
<onAlarm>
Notify
Someone
<sequence> <sequence>
<receive> d2 <invoke>
<receive> d3 <invoke>
<receive> d4 <invoke>
</sequence> </sequence>
22-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
One Request, a Mandatory Response, and an Optional Response
WSDL
PartnerLink
Call
service d1 <receive>
<invoke>
<pick> <switch>
WSDL
<scope> PartnerLink
Call d1 <receive>
service
<invoke>
<switch>
Wait for Msg A
Callback (maybe)
<receive Msg B>
Delay? <otherwise>
<onMessage A>
Notify User
of Delay <invoke>
Msg A
When
product
ships...
<invokes>
Msg B Msg B
22-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Multiple Application Interactions
and so on. This pattern can also include multiple shot callbacks, followed by
longer-term processing. Figure 22–9 provides an overview.
<receive> d2 <receive>
<invoke> d3 <invoke>
<receive> d4 <receive>
<receive>
<receive>
<receive>
<receive>
<receive>
<receive> <invoke>
C C
d3 d2
WSDL WSDL
PartnerLink PartnerLink
BPEL Process C
Shipper
<receive>
BC
<invoke>
A
22.11 Summary
BPEL process service components can serve as both clients or services, and this
chapter lists several common interaction patterns and describes best practices for
implementing these interactions.
22-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
23
23 Notifications and the Oracle User
Messaging Service
The Oracle User Messaging Service in Oracle SOA Suite enables you to send
notifications from a BPEL process using a variety of channels. These notifications are
delivered by e-mail, voice message, instant messaging (IM), or short message service
(SMS).
This chapter contains the following topics:
■ Section 23.1, "Use Cases for Notifications"
■ Section 23.2, "Introduction to Oracle User Messaging Service and Notification
Concepts"
■ Section 23.3, "Configuring the Service in Oracle JDeveloper"
■ Section 23.4, "Summary"
Beta Draft Notifications and the Oracle User Messaging Service 23-1
Introduction to Oracle User Messaging Service and Notification Concepts
■ Oracle User Messaging Service —works with the human task e-mail notification
layer to improve message reliability and handles the sending and receiving of
messages to and from devices, such as IM, SMS, or voice. The Oracle User
Messaging Service is a new feature for release 11g. Oracle BPEL Process Manager
is preconfigured to send notifications using the Oracle User Messaging Service.
Figure 23–1 shows the Oracle User Messaging Service interfaces and supported service
types.
Web Services
Interface
(WSIF binding) Oracle User
Messaging
Service
BPEL Email Server
Process
SMS Server
Java Voice Gateway
Call IM Server
Java
Interface
Human
Workflow
Task
23-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Service in Oracle JDeveloper
See Also:
■ Section 28.2, "Notifications from Human Workflow" on page 28-20
■ Section 26.6.7, "Specifying Participant Notification Preferences" on
page 26-53 for instructions on specifying e-mail notifications in
the Human Task editor
By default, the notification retries three time. If you want to add more retries (for
example, 5), add the following property in SOA_ORACLE_
HOME\j2ee\home\applications\soa-infra\configuration\workflow-con
fig.xml and restart Oracle BPEL Server:
<property name="oracle.bpel.services.notification.maxattempt" value="5" />
The notification thread that is running tries to send the notification every 15 minutes.
You can change this interval by adding the following property in
workflow-config.xml. For example, to retry every 10 minutes:
<property name="oracle.bpel.services.notification.publisher_interval" value="10"
/>
Beta Draft Notifications and the Oracle User Messaging Service 23-3
Configuring the Service in Oracle JDeveloper
Notes:
■ After configuring Oracle User Messaging Service for e-mail and
other channels in Oracle JDeveloper, set the NotificationMode
parameter to either ALL or EMAIL in the
workflow-notification-config.xml file, as described in
Section 28.2.1, "Configuring the Notification Channel" on
page 28-21.
■ There is currently no support for the IM notification channel in
Oracle JDeveloper. IM can be used for sending actionable
messages. See Section 28.2.4.2, "Sending Actionable Instant
Messages" on page 28-26 for configuration instructions.
23-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Service in Oracle JDeveloper
Beta Draft Notifications and the Oracle User Messaging Service 23-5
Configuring the Service in Oracle JDeveloper
2. Click OK.
The BPEL fragment that invokes the Oracle User Messaging Service to send the
e-mail message is created.
23-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Service in Oracle JDeveloper
<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"/>
</BodyPart>
</MultiPart>
</ContentBody>
</Content>
</from>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content"/>
</copy>
<copy>
<from expression="string('text/html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/
ns1:MimeType"/>
</copy>
<copy>
<from expression="string('NotificationAttachment1.html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/ns1:BodyPartName"/>
</copy>
<copy>
<from expression="string(‘This is a test message from John Cooper')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/
ns1:ContentBody"/>
</copy>
<copy>
<from expression="string('text/html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:MimeType"/>
</copy>
<copy>
<from expression="string('NotificationAttachment2.html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:BodyPartName"/>
</copy>
<copy>
<from expression="string('message2')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:ContentBody"/>
</copy>
</assign>
4. Search for BodyPart[2] and set the required values. The steps to send the
attachment MyImage.gif, for example, are as follows:
Beta Draft Notifications and the Oracle User Messaging Service 23-7
Configuring the Service in Oracle JDeveloper
Examples:
ora:readFile(‘MyImage.gif’) will read the file from the bpel project
directory
ora:readFile(‘file:///c:/MyImage.gif’) will read file from c:\ directory
ora:readFile(‘http://www.oracle.com/MyImage.gif’)
See: SOA_ORACLE_
HOME\bpel\samples\tutorials\130.SendEmailWithAttachments
for an example of sending attachments using e-mail
23-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Service in Oracle JDeveloper
Beta Draft Notifications and the Oracle User Messaging Service 23-9
Configuring the Service in Oracle JDeveloper
2. Click OK.
The BPEL fragment that invokes the Oracle User Messaging Service for SMS
notification is created.
23-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Service in Oracle JDeveloper
2. Click OK.
The BPEL fragment that invokes the Oracle User Messaging Service for voice
notification is created.
For example, to get the e-mail address from variable inputVariable and part
payload based on XPath /client/BPELProcessRequest/client/mail:
<%bpws:getVariableData('inputVariable','payload','/client:BPELProcessRequest/cl
ient: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 e-mail address or telephone number dynamically from the payload, use
the following XPath:
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 23–4 lists the property names
that can be used in this XPath function.
The following example gets the e-mail address of the user identified by the
variable inputVariable, part payload, and query
/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');
Beta Draft Notifications and the Oracle User Messaging Service 23-11
Configuring the Service in Oracle JDeveloper
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');
See Also: Chapter 28, "Human Task Services" for additional details
about using the Identity lookup dialog
#
EMailUnSolicited= The message you sent did not appear to be in response to a \
notification. If you are responding to a notification, please \
use the response link that was included with your notification.
23-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Summary
23.3.7 XML Validation Failure with the Oracle User Messaging Service
If you set the validateXML property to true (the default is false) in the ORACLE_
HOME/j2ee/home/applications/soa-infra/configuration/bpel-config.
xml file, each message exchanged with each of the Web services is validated against its
schema. However, Oracle User Messaging Service fails during XML validity checks at
run time. This is because the BPEL variables exchanged with the Oracle User
Messaging Service are not completely initialized in the BPEL process. Part of the
initialization happens in the service itself.
23.4 Summary
This chapter describes how you can send an e-mail, voice, IM, or SMS from Oracle
BPEL Process Manager.
Beta Draft Notifications and the Oracle User Messaging Service 23-13
Summary
23-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
24
24 Oracle BPEL Process Manager Sensors
Using sensors, you can specify BPEL activities, variables, and faults that you want to
monitor during run time. This chapter describes how to use and set up sensors for a
BPEL process. This chapter also describes how to create sensor actions in Oracle BPEL
Process Manager to publish sensor data as data objects in an Oracle BAM Server.
This chapter contains the following topics:
■ Section 24.1, "Use Cases for Sensors"
■ Section 24.2, "Introduction to Sensor Concepts"
■ Section 24.3, "Implementing Sensors and Sensor Actions in Oracle JDeveloper"
■ Section 24.4, "Sensors and Oracle Enterprise Manager 11g Application Server
Control Console"
■ Section 24.5, "Sensor Integration with Oracle Business Activity Monitoring"
■ Section 24.6, "Sensor Public Views"
■ Section 24.7, "Sensor Actions XSD File"
■ Section 24.8, "Summary"
Variable sensors are used to monitor variables (or parts of a variable) of a BPEL
process. For example, variable sensors can be used to 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.
When you model sensors in Oracle JDeveloper, two new files are created as part of the
BPEL process suitcase:
■ 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
See Section 24.3.1, "Configuring Sensors" on page 24-3 and Section 24.3.2, "Configuring
Sensor Actions" on page 24-6 for how these files are created.
After you define sensors for a BPEL process, you must configure sensor actions to
publish the data of the sensors to an endpoint. You can publish sensor data to the
BPEL reports schema, which is located in the BPEL dehydration store, to a JMS queue
or topic, or to a custom Java class.
The following information is required for a sensor action:
■ Name
■ Publish type
The publish type specifies the destination where the sensor data must be
presented. You can configure the following publish types:
– Database—used to publish the sensor data to the reports schema in the
database. The sensor data can then be queried using SQL.
– JMSQueue—used to publish the sensor data to a JMS queue
– JMSTopic—used to publish the sensor data to a JMS topic
– Custom—used to publish 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
24-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Implementing Sensors and Sensor Actions in Oracle JDeveloper
You typically add or edit sensors as part of the BPEL modeling of activities, faults, and
variables. You can add sensor actions by right-clicking the Sensor Actions folders and
selecting Create > Sensor Action. To add activity sensors, variable sensors, or fault
sensors, expand the Sensors folder, right-click the appropriate Activity, Variable, or
Fault subfolder, and click Create.
Using LoanDemoPlus as an example, the following sections describe how to
configure sensors and sensor actions.
The Evaluation Time attribute shown in Figure 24–2 controls the point at which the
sensor fires. You can select from the following:
■ All—Monitoring occurs during all of the preceding phases.
■ Activation—The sensor fires just before the activity is executed.
■ Completion—The sensor fires just after the activity is executed.
■ Fault—The sensor fires if a fault occurs during the execution of the activity. Select
this value only for sensors that monitor simple activities.
■ Compensation—The sensor fires when the associated scope activity is
compensated. Select this value only for sensors that monitor scopes.
■ Retry—The sensor fires when the associated invoke activity is retried.
A new entry is created in the bpel_process_name_sensor.xml file, as follows:
<sensor sensorName="CreditRatingSensor"
classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent"
kind="activity"
target="callbackClient">
<activityConfig evalTime="all">
<variable outputNamespace="http://www.w3.org/2001/XMLSchema"
outputDataType="int"
target="$crOutput/payload//services:rating"/>
</activityConfig>
</sensor>
If you want to record all the incoming loan requests, create a variable sensor for the
variable input, as shown in Figure 24–3.
24-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Implementing Sensors and Sensor Actions in Oracle JDeveloper
If you want to monitor faults from the identity service, create a fault sensor, as shown
in Figure 24–4.
target="is:identityServiceFault">
<faultConfig/>
</sensor>
24-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Implementing Sensors and Sensor Actions in Oracle JDeveloper
The data of one sensor can be published to multiple endpoints. In the two preceding
code samples, the data of LoanApplicationSensor is published to a JMS queue
and to the reports schema in the database.
If you want to monitor loan requests for which the loan amount is greater than
$100,000, you can create a sensor action with a filter, as shown in Figure 24–7.
Note:
■ You must specify all the namespaces that are required to configure
an action filter in the sensor action configuration file.
■ 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 24–8. The name in the Publish Target field denotes a fully qualified Java class
name that must be implemented.
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
oc4j-ra.xml file. Use the JMS connection name property in the Sensor Actions
dialog to point to the proper entry in the oc4j-ra.xml file.
See Also: Oracle Application Server Adapter for Files, FTP, Databases,
and Enterprise Messaging User’s Guide for details about the JMS adapter
24-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Implementing Sensors and Sensor Actions in Oracle JDeveloper
1. Select Project Properties > Libraries > Add Jar/Directory from the Tools main
menu.
2. Browse and select SOA_ORACLE_
HOME\lib\java\shared\oracle.soainfra.common\11.1.1\orabpel.jar.
24-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensors and Oracle Enterprise Manager 11g Application Server Control Console
location="JMSQueueFilter.wsdl" importType="wsdl"/>
<service name="client">
<interface.wsdl interface="http://xmlns.oracle.com/
JMSQueueFilter#wsdl.interface(JMSQueueFilter)"/>
<binding.ws
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 the
preceding code sample.
or select Start > All Programs > Oracle - Oracle_Home > Oracle Application
Server Control.
2. Log in with fmwadmin/password when prompted.
24-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensors and Oracle Enterprise Manager 11g Application Server Control Console
6. Select Action Definitions from the View list. A page similar to Figure 24–11
displays definitions of the sensor actions in the BPEL process.
24-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Integration with Oracle Business Activity Monitoring
Note: You can also use Oracle BPEL Process Manager 10.1.3.1 sensor
actions to publish sensor data as data objects on Oracle BAM Server
11g.
Notes:
■ Do not create a BAM Server connection through the Resource
Palette that displays when you select View > Resource Palette.
■ Only one Oracle BAM Server per BPEL project is currently
supported.
You must create a connection to Oracle BAM Server to browse the available data
objects. This connection information is automatically used during deployment.
1. Select New from the File main menu in Oracle JDeveloper.
The New Gallery dialog opens.
2. Choose Connections from the General category.
3. Select BAM Connection in the Items list, and click OK.
The BAM Connection wizard opens.
4. Ensure that Application Resources is selected.
5. Provide a name for the connection.
6. Click Next.
7. Enter the following connection information about the Oracle BAM Server host.
Field Description
BAM Web Host Enter the name of the host on which the BAM report server and
Web server are installed. In most cases, the BAM Web host and
Oracle BAM Server host are the same.
BAM Server Host Enter the name of the host on which the Oracle BAM Server is
installed.
User Name Enter the Oracle BAM Server user name (typically bamadmin).
Password Enter the password of the user name.
HTTP Port Enter the port number or accept the default value of 8888. This is
the HTTP port for the BAM Web host.
24-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Integration with Oracle Business Activity Monitoring
Field Description
RMI Port Enter the port number or accept the default value of 9085. The
RMI port is for the BAM report cache, which is part of the Oracle
BAM Server.
Use HTTPS Select this check box if you want to use secure HTTP (HTTPS) to
connect to the Oracle BAM Server during design time.
Otherwise, HTTP is used.
8. Click Next.
9. Test the connection by clicking Test Connection. If the connection was successful,
the following message appears:
Passed.
Field Description
Action Name Enter a unique and recognizable name for the sensor action.
Sensor Select a BPEL sensor to monitor. This is the sensor that you created in
Section 24.5.2, "Creating a Sensor" on page 24-17 for mapping sensor
data to a data object in Oracle BAM Server.
Field Description
Data Object Click the flashlight icon to open the BAM Data Object Chooser window
to select the data object in Oracle BAM Server in which you want to
publish the sensor data.
If you have not already created a connection to Oracle BAM Server in
order to select data objects, click the icon in the upper right corner of
the BAM Data Object Chooser window.
Operation Select to Delete, Update, Insert, or Upsert a row in the Oracle BAM
Server database. Upsert first attempts to update a row if it exists. If the
row does not exit, it is inserted.
Available If you selected the Delete, Update, or Upsert operation, you must also
Keys/Selected Keys select a column name in the Oracle BAM server database to use as a key
to determine the row with which this sensor object corresponds. A key
can be a single column or a composite key consisting of multiple
columns. Select a key and click the > button. To select all, click the >>
button.
Map File Provide a file name to create a mapping between the sensor (selected in
the Sensor list) and the Oracle BAM Server data object (selected in the
Data Object list). You can also invoke a mapper window by clicking the
Create Mapping icon (second icon) or Edit Mapping icon (third icon).
Network Protocol Select RMI, HTTP, or HTTPS as the network protocol to use. Oracle
BAM Server publishes the data objects and types information in WSDL
files. It uses the selected protocol to transport these files.
Enable Batching The data cached by default by the Oracle BAM component of the Oracle
BPEL Process Manager run time is flushed (sent) to Oracle BAM Server
periodically. The Oracle BAM component may decide to send data prior
to a batch timeout if the cache has a number of data objects between
automatically defined lower and upper limit values. Disable batching
by unselecting this check box.
An example of the Create Sensor Action window with a selected data object is
shown below.
24-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Public Views
Notes: After you click the Create Mapping or Edit Mapping, or the
OK button on the Create Sensor Action window, you must explicitly
save the BPEL file.
BPEL_PROCESS_INSTANCES
This view provides an overview of all the process instances of Oracle BPEL Process
Manager.
24-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Public Views
BPEL_ACTIVITY_SENSOR_VALUES
This view contains all the activity sensor values of the monitored BPEL processes.
BPEL_FAULT_SENSOR_VALUES
This view contains all the fault sensor values.
BPEL_VARIABLE_SENSOR_VALUES
This view contains all the variable sensor values.
24-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Actions XSD File
<xsd:simpleType name="tSensorActionPublishType">
<xsd:annotation>
<xsd:documentation>
This enumeration lists the possibe publishing types for probes.
</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"/>
24-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Actions XSD File
</xsd:complexType>
<!--
define a listing of sensor actions in a single document. It might be a good
idea to
have one sensor action list per business process.
-->
<xsd:complexType name="tSensorActionList">
<xsd:sequence>
<xsd:element name="action" type="tns:tSensorAction" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="tSensorKind">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="fault"/>
<xsd:enumeration value="variable"/>
<xsd:enumeration value="activity"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="tActivityConfig">
<xsd:annotation>
<xsd:documentation>
The configuration part of an activity sensor comprises of a mandatory
'evalTime' attribute
and an optional list of variable configurations
</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:extension base="tns:tSensorConfig">
<xsd:sequence>
<xsd:element name="variable" type="tns:tActivityVariableConfig"
maxOccurs="unbounded" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="evalTime" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tAdapterConfig">
<xsd:annotation>
<xsd:documentation>
The configuration part of a adapter activity extends the activty
configuration with additional attributes for adapters
</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:extension base="tns:tActivityConfig">
<xsd:attribute name="headerVariable" use="required" type="xsd:string"/>
<xsd:attribute name="partnerLink" use="required" type="xsd:string"/>
<xsd:attribute name="portType" use="required" type="xsd:string"/>
<xsd:attribute name="operation" use="required" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tVariableConfig">
<xsd:complexContent>
<xsd:extension base="tns:tSensorConfig">
<xsd:attribute name="outputDataType" use="required" type="xsd:string"/>
<xsd:attribute name="outputNamespace" use="required" type="xsd:string"/>
<xsd:attribute name="queryName" use="optional" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tActivityVariableConfig">
<xsd:complexContent>
<xsd:extension base="tns:tVariableConfig">
<xsd:attribute name="target" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tFaultConfig">
<xsd:complexContent>
<xsd:extension base="tns:tSensorConfig"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tNotificationSvcConfig">
<xsd:complexContent>
<xsd:extension base="tns:tActivityConfig">
<xsd:attribute name="inputVariable" use="required" type="xsd:string"/>
<xsd:attribute name="outputVariable" use="required" type="xsd:string"/>
<xsd:attribute name="operation" use="required" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tSensorConfig">
<xsd:sequence>
<xsd:element name="action" type="tns:tInlineSensorAction" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tInlineSensorAction">
<xsd:complexContent>
<xsd:restriction base="tns:tSensorAction"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tSensor">
<xsd:sequence>
<xsd:element name="activityConfig" type="tns:tActivityConfig"
minOccurs="0"/>
<xsd:element name="adapterConfig" type="tns:tAdapterConfig" minOccurs="0"/>
<xsd:element name="faultConfig" type="tns:tFaultConfig" minOccurs="0"/>
<xsd:element name="notificationConfig" type="tns:tNotificationSvcConfig"
minOccurs="0"/>
<xsd:element name="variableConfig" type="tns:tVariableConfig"
minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="sensorName" use="required" type="xsd:string"/>
<xsd:attribute name="kind" use="required" type="tns:tSensorKind"/>
<xsd:attribute name="classname" use="required" type="xsd:string"/>
<xsd:attribute name="target" use="required" type="xsd:string"/>
24-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Actions XSD File
</xsd:complexType>
<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 will be provided to sensors for variable Datas. Note the
any element represents variable data.
-->
<xsd:complexType name="tVariableData">
<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"/>
24-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Actions XSD File
<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"
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.
-->
24-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Sensor Actions XSD File
<xsd:complexType name="tProcessSensorData">
<xsd:sequence>
<xsd:element name="activityData" type="tns:tProcessActivityData"
minOccurs="0"/>
<xsd:element name="faultData" type="tns:tProcessFaultData" minOccurs="0"/>
<xsd:element name="adapterData" minOccurs="0"
type="tns:tProcessAdapterData"/>
<xsd:element name="variableData" type="tns:tProcessVariableData"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="notificationData" type="tns:tProcessNotificationData"
minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<!--
A single process sensor value comprises of the sensor value metadata
(sensor and timestamp) and the payload (the value) of the sensor
-->
<xsd:complexType name="tProcessSensorValue">
<xsd:sequence>
<xsd:element name="header" type="tns:tProcessSensorValueHeader"/>
<xsd:element name="payload" type="tns:tProcessSensorData"/>
</xsd:sequence>
</xsd:complexType>
<!--
Process instance header.
-->
<xsd:complexType name="tProcessInstanceInfo">
<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:sequence>
</xsd:complexType>
<!--
The list of sensor values comprises of a process header describing the
BPEL process with name, cube instance id etc. and a list of sensor values
comprising of sensor metadata information and sensor values.
-->
<xsd:complexType name="tProcessSensorValueList">
<xsd:sequence>
<xsd:element name="process" type="tns:tProcessInstanceInfo" minOccurs="1"
maxOccurs="1"/>
<xsd:element name="sensorValue" type="tns:tProcessSensorValue" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<!-- The sensor list is the root element of the sensor.xml document in the
bpel process suitcase and is used to define sensors. -->
<xsd:element name="sensors" type="tns:tSensorList"/>
<!-- The actions element is the root element of the sensorAction.xml document
in the bpel process suitcase and is used to define sensor actions.
Sensor actions define how to publish data captured by sensors -->
<!-- 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>
24.8 Summary
This chapter describes how to set up and use sensors to monitor BPEL activities,
variables, and faults during run time. This chapter also describes how to create sensor
actions in Oracle BPEL Process Manager to publish sensor data as data objects in an
Oracle BAM Server.
24-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
25
25 Business Rule Service Component
This chapter describes how to use a business rule service component to integrate a
SOA composite application with a business rules engine.
This chapter contains the following topics:
■ Section 25.1, "Business Rule Concepts"
■ Section 25.2, "Business Rule Architecture"
■ Section 25.3, "Use Cases for Integration of Business Processes and Business Rules"
■ Section 25.4, "Integration of BPEL Processes, Human Tasks, and Business Rules"
■ Section 25.5, "Deploying a Business Rule"
■ Section 25.6, "Running a Business Rule in a SOA Composite Application"
A business rules engine is a system that manages and executes business rules. A
business rule system typically consists of a rule repository, rule author, and rules
engine. The rule author allows business rules to be specified separately from
application code. Separating the business rules from code allows business analysts to
change business policies quickly with graphical tools. The rules engine evaluates the
business rule and returns decisions or facts that are then used in the business process.
The rules are typically stored in a rule repository in a database or file system.
25-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Business Rule Architecture
■ For a loan company to create a rule denying a loan request to customers whose
incomes fall below a specific level, the income level represents the fact used in the
rule.
Each data object instance corresponds to a single fact. Rules are expressions that can be
evaluated on this factual information.
If an object is re-asserted (whether or not it has changed), the rules engine is updated
to reflect the new state of the object. Re-asserting the object does not create a new fact.
In order to have multiple facts of a particular fact type, separate object instances must
be asserted.
Using the Oracle Business Rules Designer (Rule Designer) in Oracle JDeveloper, you
create rules that operate on facts that are part of a data model. You make business
objects and their methods known to Oracle Business Rules using fact definitions.
Oracle Business Rules consist of the following key components:
■ Rule Designer — An editor integrated with Oracle JDeveloper that enables you to
create and edit rules.
■ Oracle Business Rules Rules Engine (Rules Engine) — A Java library that applies
rules to facts and defines and processes rules. The Rules Engine defines a
declarative rule language, provides a language processing engine, and provides
debugging tools.
Oracle SOA Suite provides support for a Rules Engine file repository to store
business rules. A repository stores dictionaries. A dictionary is a set of XML files
that stores the application's rule sets and the data model. Rule sets are a group of
business rules that are typically evaluated together and generated as one unit.
Dictionaries can have different versions. Dictionaries and dictionary versions can
be created, deleted, exported, and imported into a repository.
■ Oracle Business Rules SDK (Rules SDK) — A Java library that provides business
rule management features to use for writing customized rules programs.
■ Oracle Business Rules RL Language (RL Language) —A language that defines the
syntax for Rules Engine programs. RL Language includes an intuitive Java-like
syntax for defining rules that supports Java semantics.
This integration provides the following benefits:
■ Dynamic processing (provides for intelligent routing, validation of policies within
a process, and constraint checks)
■ Integration with adhoc human tasks (provides policy-based task assignment,
various escalation policies, and load balancing of tasks)
■ Integration with business activity monitoring (sends alerts based on certain
policies and dynamic processing-based key performance indicator (KPI)
reasoning)
See Also: Oracle Fusion Middleware User's Guide for Oracle Business
Rules
25-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Business Rule Architecture
</pattern>
<pattern name="CallFunctionStateful">
<arguments>
<call>AutoLoanRules.computeLoanAdvise</call>
</arguments>
</pattern>
</decisionService>
</decisionServices>
The repository type is set to SCA-Archive for business rule service components. This
indicates that the rule dictionary is located in the service component architecture
archive. The path is relative and interpreted differently by the following:
■ Design time — The path is prefixed with Oramds:/. Metadata service (MDS) APIs
open the rule dictionary. Therefore, the full path to the dictionary is as follows:
Oramds:/AutoLoanComposite/oracle/rules/AutoLoanRules.rules
■ Runtime (business rule service engine) — The business rule service engine uses
the metadata manager to open the rule dictionary. The composite name prefix
(AutoLoancomposite) is removed from the path and the metadata manager
assumes the existence of oracle/rules/AutoLoanRules.rules relative to the
composite home directory.
Notes:
■ The concept of dictionary links is not exposed through business
rule metadata. It is assumed that all linked dictionaries exist at an
appropriate location in the SOA archive.
■ The Web Distributed Authoring and Versioning (WebDAV) rule
repository is not supported in release 11g.
25-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Business Rule Architecture
<arguments>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
<pattern name="AssertExecuteWatchStateful">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
<decisionService targetNamespace="http://xmlns.oracle.com/loanoffer/Advisor"
ruleEngineProviderReference="OracleRulesSDK" name="LoanAdvisorService">
<catalog>AutoLoanRules</catalog>
<pattern name="CallFunctionStateless">
<arguments>
<call>AutoLoanRules.computeLoanAdvise</call>
</arguments>
</pattern>
<pattern name="CallFunctionStateful">
<arguments>
<call>AutoLoanRules.computeLoanAdvise</call>
</arguments>
</pattern>
</decisionService>
</decisionServices>
Apart from the operations (patterns), the parameter types (or fact types) of operations
are specified (and validated later at runtime). Therefore, every decision service exposes
a strongly-typed contract.
There is a one-to-one relationship between decision service metadata and the WSDL
file being generated for a decision service. Operation
AssertExecuteWatchStateless provides an example:
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</complexType>
</element>
</sequence>
<attribute name="name" type="NCName" use="required"/>
</complexType>
</element>
The preceding syntax also showed the XML-schema definition for the input message
of pattern AssertExecuteWatchStateless. As an analogy, an XML-schema
element is being created for the output message:
<element name="assertExecuteWatchStatelessDecision">
<complexType>
<sequence>
<element name="resultList" minOccurs="1" maxOccurs="1">
<complexType>
<sequence>
<element ref="ns1:rating"/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
. . .
. . .
<message name="assertExecuteWatchStatelessMessage">
<part name="payload" element="tns:assertExecuteWatchStateless"/>
</message>
<message name="assertExecuteWatchStatelessDecisionMessage">
<part name="payload" element="tns:assertExecuteWatchStatelessDecision"/>
</message>
. . .
. . .
<portType name="IDecisionService">
<operation name="assert">
<input name="assertInput" message="tns:assertMessage"/>
</operation>
<operation name="assertExecute">
<input name="assertExecuteInput" message="tns:assertExecuteMessage"/>
</operation>
<operation name="watch">
<input name="watchInput" message="tns:watchMessage"/>
<output name="watchOutput" message="tns:watchDecisionMessage"/>
<fault name="operationErroredFault" message="tns:decisionServiceError"/>
</operation>
<operation name="assertExecuteWatchStateless">
<input name="assertExecuteWatchStatelessInput"
message="tns:assertExecuteWatchStatelessMessage"/>
<output name="assertExecuteWatchStatelessOutput"
message="tns:assertExecuteWatchStatelessDecisionMessage"/>
<fault name="operationErroredFault"
message="tns:decisionServiceError"/>
</operation>
<operation name="assertExecuteWatchStateful">
<input name="assertExecuteWatchStatefulInput"
message="tns:assertExecuteWatchStatefulMessage"/>
<output name="assertExecuteWatchStatefulOutput"
message="tns:assertExecuteWatchStatefulDecisionMessage"/>
<fault name="operationErroredFault"
25-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Business Rule Architecture
message="tns:decisionServiceError"/>
</operation>
</portType>
For a decision service exposing an RL function, you only need the information about
the rule dictionary and the fully-qualified function name. The function signature can
be queried from the rule dictionary. Note also that no rule set name must be specified
because functions hang off a dictionary.
Note the following details about decision services that expose an RL function:
In the preceding sample, the function consists of one parameter of XML schema
element ns1:setupParameter and a return type of rules:int.
The following messages and operations are also part of the WSDL contract:
<message name="callFunctionStatelessMessage">
<part name="payload" element="tns:callFunctionStateless"/>
</message>
<message name="callFunctionStatelessDecisionMessage">
<part name="payload" element="tns:callFunctionStatelessDecision"/>
</message>
<portType name="IDecisionService">
<operation name="callFunctionStateless">
<input name="callFunctionStatelessInput"
message="tns:callFunctionStatelessMessage"/>
<output name="callFunctionStatelessOutput"
message="tns:callFunctionStatelessDecisionMessage"/>
<fault name="operationErroredFault"
message="tns:decisionServiceError"/>
</operation>
</portType>
25-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Business Rule Architecture
A decision service is a lightweight entity. It consists only of the service description. All
other artifacts are shared within a decision component. The heart of runtime is the
decision service cache, which is organized in a tree structure. Every decision
component owns a subtree of that cache (depending on the composite distinguished
name (DN), component, and service name). In this regard, decision services of a
decision component share the following data:
■ Metadata of the decision component
– Fact type metadata
– Function metadata
– Rule Set metadata
■ Rule session pool
– One rule session pool is created per decision component
– The rule sessions in the pool are preinitialized with the data model RL and the
rule set RL already executed
– New rule sessions are created on demand
– Rule sessions can be reused for a configurable number of times
– The initial size of the rule session pool is configurable
■ Stateful rule session cache
– A special cache is maintained for stateful rule sessions (see Section 25.2.5,
"Stateful Interactions with a Decision Component" on page 25-12)
■ Deployment artifacts
– Decision component deployment can end up in class generation for JAXB fact
types. The classes can be shared across the composite.
Figure 25–1 provides an overview.
Note the following details about stateful interactions with a decision component:
■ The following operations are final. A rule session is removed from the cache after a
final operation finishes (therefore, querying for results clears the state).
– Retrieve the result
– Assert facts, execute the rule set, and retrieve the result
– Call the function (stateless)
■ The following operations are stateful operations
– Assert the facts
– Assert the facts and execute the rule set
– Call the function (stateful)
25-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Integration of BPEL Processes, Human Tasks, and Business Rules
■ Rule sessions from the cache and those from the pool are mutually exclusive
– The rule session pool is for simple, stateless interactions only
– The rule session cache keeps the state of a rule session across decision service
requests
See Also: Business rule sample files and tutorial that uses all three
service components located in the soa-samples.zip file
6. Click OK.
This creates a business rule service component.
25-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Integration of BPEL Processes, Human Tasks, and Business Rules
8. Create and edit business rules as necessary. The rules you create in this editor are
added to the business_rule_name.rules file. Business rules modeling is a
multistep process. For example, you can:
■ Specify the rules data model:
– Import XML-schema definitions for XML-fact declarations
– Create variables that are required for rule modeling
– Create helper RL functions that can be used during rule modeling
■ Create Rulesets:
– A ruleset can be considered as an execution unit
– A ruleset comprises of one or more rules
■ Create Services:
– Expose a ruleset as a service
– Expose a RL function as a service
See Also: The following documentation for details about using the
Rule Designer:
■ Oracle Fusion Middleware User's Guide for Oracle Business Rules
■ Tutorial included in the soa-samples.zip file
25-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Integration of BPEL Processes, Human Tasks, and Business Rules
invocation pattern Assert facts and execute rule set operation was
executed before in the BPEL process.
– Assert facts, execute rule set, retrieve results, and reset the session —
The same as Assert facts, execute rule set, and retrieve results, except that
the results are reset for the next time that you invoke the Web service.
Resetting the session clears the previously asserted fact values.
– Assert facts, execute rule set, and retrieve results — The same as Assert
facts and execute rule set, except that the results are retrieved from the
business Rules Engine. You map the results of rule set execution to BPEL
variables with an assign activity. The rules session remains active. This
enables you to reuse previously asserted facts.
■ If you created functions in the Rule Designer:
– Execute function — Executes a function. Functions are also defined in
dictionaries. For rule sets, you select input and output facts. For functions,
there are a fixed set of input parameters and a single return value.
– Execute function and reset the session — The same as Execute function,
except that a stateful rule session is created for this pattern. All fact values
are reset after retrieving the return value of the function.
11. Click Assign Input Facts, then click the Create icon to create mappings for the
input facts.
This enables you to create assignments that map BPEL input variables to
automatically created BPEL variables that correspond to the input fact type
specified in the Rule Designer.
12. If you selected an invocation pattern that retrieves results, click Assign Output
Facts, then click the Create icon to create mappings for the output facts.
This enables you to create assignments that map automatically created BPEL
variables that correspond to the output fact type specified in the Rule Designer.
13. Click OK when complete.
This creates:
■ A new business rule partner link for this Web service that interfaces with the
Rules Engine.
■ A business rule activity consisting of assign and invoke activities to the
business rule partner link.
■ A WSDL file based on the rule set is generated.
Business rule service component association with the BPEL process component is
now complete.
25-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying a Business Rule
2. Create and run a test instance of the SOA composite application that includes the
business rule. See Section 3.5, "Testing Applications" on page 3-8 for instructions
on creating and running a test instance.
This creates an instance of the SOA composite application.
3. Refresh the page after instance creation.
4. Click the instance ID of the SOA composite application in the Last 5 Instances
section.
The Trace section displays the flow of service components and service and
reference binding components in the SOA composite application.
5. Click a business rule service component to view the flow trace of the component
(for this example, ApprovalRequired).
25-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Running a Business Rule in a SOA Composite Application
This enables you to view flow trace and audit details for the business rule service
component.
6. Return to the page shown in Step 4 on page 25-20 and click a business rule service
component shown in the Components table (for this example, ApprovalRequired
is selected).
This page displays details about the completion success rate of business rule
service component details.
25-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Part IV Human Workflow Service Component
Beta Draft
Beta Draft
26
26 Designing Human Tasks
A company's business processes drive the integration of systems and people that
participate in it. The business process and associated systems have a life cycle and
certain behavior. The users who participate in the business process have roles and
privileges to perform tasks in the business process. Using the workflow services of
Oracle BPEL Process Manager, you can blend the integration of systems and services
with human workflow into a single end-to-end process flow, while providing visibility
and enabling exception handling and optimization at various levels.
This chapter contains the following topics:
■ Section 26.1, "Introduction to Workflow Services"
■ Section 26.2, "Use Cases for Workflow Services"
■ Section 26.3, "Workflow Services Components"
■ Section 26.4, "Participant Types in Workflow Services"
■ Section 26.5, "Introduction to the Modeling Process"
■ Section 26.6, "Creating the Human Task Definition with the Human Task Editor"
■ Section 26.7, "Associating the Human Task Service Component with a BPEL
Process"
■ Section 26.8, "End-to-End Workflow Examples"
Figure 26–1 High-Level View of Workflow Services in Oracle BPEL Process Manager
Users
See Also: Section 26.6, "Creating the Human Task Definition with
the Human Task Editor" on page 26-12
26-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to Workflow Services
See Also: Section 26.6, "Creating the Human Task Definition with
the Human Task Editor" on page 26-12
See Also: Chapter 31, "Designing Task Display Forms for Human
Tasks"
■ Worklist Application:
– An out-of-the-box fully customizable worklist
– Support for various user profiles — end user, supervisor, process owner,
group owner, and administrator
– Ability to perform authorized actions on tasks in the worklist, acquire and
check out shared tasks, define personal to-do tasks, and define subtasks
– Ability to filter tasks in a worklist view based on various criteria
– Work queues — standard work queues such as high priority tasks, tasks due
soon, and so on. Ability to define custom work queues.
– Users can define custom vacation rules and delegation rules
– Group owners can define task dispatching rules for shared tasks
– Proxy access to selected subset of a user’s worklist
– Complete workflow history and audit trail
– Digital signatures for tasks
– Internationalization support — out-of-the-box support for eight languages
■ Workflow reports:
– Out-of-the-box reports — productivity report, tasks priority report, cycle time
report, and assignee time distribution report
■ Notification services:
– Send notifications to specified users upon changes to specified tasks
– Notifications through different delivery channels (e-mail, phone, instant
message, and SMS)
– Ability to customize content of the notifications for different types of tasks
– Perform actions on tasks through e-mail
– Guaranteed delivery of messages — support for bad e-mail format detection
and blacklisted addresses (for incoming messages)
See Also:
■ Chapter 23, "Notifications and the Oracle User Messaging Service"
■ Section 28.1.6, "Notification Service" on page 28-11
■ Identity Services:
– Role-based access control — assign permissions to roles and link an
organization hierarchy to the role model for authorization
– Assign worklist privileges to users, groups, and roles
– Maintain user properties such as name, location, phone, and e-mail and
capture organizational hierarchy (reporting structure) and group information
– Integration with standard (for example, LDAP-based) directory services for
user and role provisioning
26-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Cases for Workflow Services
Business Process
<receive>
Purchase List
<invoke>
Vendor Pricing
Service
<receive>
Get Outcome via Assign to
Task Service Manager
Approved Rejected
?
<invoke>
Vendor Order
Service
<invoke>
Employee
Notification
See Also:
■ Section 26.8, "End-to-End Workflow Examples" on page 26-81
■ SOA_Oracle_Home\bpel\samples\demos
The following sections describe multiple use cases for workflow services.
OID
LDAP
Workflow Service
Get Approvals
BPEL Change Routing
Process
All Approvals
Complete
Various
Routing
Patterns
See Section 26.4, "Participant Types in Workflow Services" on page 26-10 for the
various flow types supported by workflow services. You can use these types as
building blocks to create complex workflows.
26-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Use Cases for Workflow Services
process. A high-priority task may be assigned to a certain user and if the user does not
respond in two days, then the task is routed to the manager for further action.
Workflow Services
Escalate Task
1 2 3 4 5 6
BPEL 7 8 9 10 11 12 13
21 22 23 24 25 26 27
Task Resolved
28 29 30 Calendar
Notification
Figure 26–6 Oracle BPM Worklist—Access Tasks, Forms, Attachments, and Reports
Workflow Services
List Work Items
Complete Task
Get Weekly
Productivity
Report Task Details
and History
26-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Workflow Services Components
instant message, and SMS. See Section 28.2, "Notifications from Human Workflow"
on page 28-20 for more information.
■ User Metadata Service
The user metadata service manages metadata related to workflow users, such as
user work queues, preferences, vacation, and delegation rules.
■ Runtime config service
The runtime config service provides methods for managing metadata used in the
task service run time environment. It principally supports management of task
payload flex field mappings.
■ Evidence service
The evidence service supports storage and nonrepudiation of digitally-signed
workflow tasks.
Workflow Services
Task Evidence
Metadata Store
Service Service
Portal
User Identity
BPEL Metadata Service Users
Process Workflow Service
Service Services Worklist
Component
Task Task
Service Query
Service
E-mail Client
Metadata Task Notification
MDS Assignment Service
.task Metadata Service
.bpel
.wsdl
Identity Notification
Management Channels
· OID · E-mail
· LDAP Database · Application Server Wireless
· JAZN - Voice
· other user - SMS
Figure 26–8 shows the interactions between the services and the business process.
Worklist application
BPEL Process Web application to search
Service Component for tasks, view tasks, and
act on tasks
User Directory
(one of)
Policy Store
Contains
Oracle Information
Internet JAZN LDAP,
XML Custom about
Directory application
roles and
permissions
26-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to the Modeling Process
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.
■ Management Chain—used to route tasks for approval to multiple users in a
management chain hierarchy. You specify the task participants as a management
chain list or a list of users.
■ Sequential list of approvers (extension of a sequential workflow)—used to create a
list of sequential participants for a workflow. This type is similar to the
management chain participant type, except that with that type, the users are part
of an organization hierarchy. For the sequential list of approvers participant type,
they can be any list of users or groups.
■ FYI assignee — used when a task is sent to a user, but the business process does
not wait for a user response; it just continues. FYI assignees cannot directly impact
the outcome of a task, but in some cases can provide comments or add
attachments.
■ External Routing Service —used to configure an external routing service that
dynamically determines the participants in the workflow. If this participant type is
specified, all other participant types are ignored. It is assumed that the external
routing service provides a list of participant types (single approver, list of
approvers, group vote, and so on) at run time to determine the routing of the task.
■ Rule-based assignments — in addition to the built-in patterns, you can use the
state-based routing rules to create complex, dynamic workflows
■ Mixing and matching patterns — mix and match patterns to create complex
workflows
26.5.1 Create a Human Task Definition with the Human Task Editor
The Human Task editor enables you to define the metadata for the task. This editor
enables you to specify human task settings, such as task outcome, payload structure,
task participants, assignment and routing policy, expiration and escalation policy,
notification settings, and so on. This information is saved to a metadata task
configuration file with a .task extension.
See Also: Section 26.6, "Creating the Human Task Definition with
the Human Task Editor" on page 26-12 for specific instructions
26.5.2 Optionally Associate the Human Task Definition with a BPEL Process
You can optionally associate the .task file that consists of the human task settings
with a BPEL process. Association is made with a human task activity that you drag
and drop into your BPEL process for configuring. You also define the task definition,
task initiator, task priority, and map the task parameter that carries 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.
See Also: Chapter 31, "Designing Task Display Forms for Human
Tasks"
26.6 Creating the Human Task Definition with the Human Task Editor
The Human Task editor enables you to define the metadata for the task. The editor
enables you to specify human task settings, such as task outcome, payload structure,
task participants, assignment and routing policy, expiration and escalation policy,
notification settings, and so on.
When a human task is created, the following folders and files appear:
■ The human task settings specified in the Human Task editor are saved to a
metadata task configuration file in the 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 JDeveloper
26-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
– The human task icon in the SOA Composite Editor or in your BPEL process in
Oracle JDeveloper
This reopens the .task file in the Human Task editor.
■ A Human Tasks folder containing the human task you created appears in the
Structure window of the SOA Composite Editor.
Figure 26–9 shows these folders and files.
26.6.1 Creating a Human Task Service Component and Accessing the Human Task
Editor
You create a human task service component in the SOA Composite Editor. After
creation, you design the component in the Human Task editor. The method by which
you create the human task service component determines whether the component can
5. Note the Expose as Composite Service check box. You selection of this check box
determines how the human task service component is created.
a. If you want to create a human task service component that you later associate
with a BPEL process service component, do not select the Expose as
Composite Service check box. The human task service component is created
as a component that you explicitly associate with a BPEL process service
component.
This service provides external customers with an entry point into the human
task service component of the SOA composite application.
6. Click Finish.
The Human Task icon appears in the SOA Composite Editor canvas workspace
and a Human Task folder appears in the Structure window in the lower left
section of the SOA Composite Editor.
7. Double-click the Human Task icon.
The Human Task editor appears.
8. Go to section Section 26.6.2, "Reviewing the Sections of the Human Task Editor" on
page 26-15.
26-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
Note: 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 > SOA Components > Human Task.
Instructions for using these main sections of the Human Task editor to create a
workflow task are listed in Table 26–1.
26-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
Field Description
Title Enter an optional task title. The task title displays in the Oracle BPM
Worklist. If you enter a title in the Task Title field of the General tab of
the Human Task window described in Section 26.7.2.1, "Specifying the
Task Title" on page 26-71, the title you enter here is overridden.
Priority Specify the priority of the tasks. Priority can be 1 through 5, with 1
being the highest. By default, the priority of a task is 3. The priority can
be used to sort tasks in the Oracle BPM Worklist. This priority value is
overridden by any priority value you select in the General tab of the
Add a Human Task window.
See Also: Section 26.7.2.2, "Specifying the Task Initiator and Task
Priority" on page 26-72 for instructions on specifying a priority value in
the Add a Human Task window
The seeded and custom outcomes selected here display for selection in the
Majority Voted Outcome section of the group vote participant type.
26-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
One or more users or groups can be highlighted and selected by clicking Select.
3. 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.
4. View the details of a user or group by highlighting the user or group and clicking
Detail.
2. Browse the available variable schemas and functions to create a task owner.
3. Click OK to return to the Human Task editor.
You selection displays in the Owner field.
26-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
See Also:
■ Click Help for instructions on using the Expression Builder
window and XPath Building Assistant
■ Section 28.4, "Human Task Service and Identity Service Related
XPath Extension Functions" on page 28-36 for information about
workflow service dynamic assignment functions and identity
service functions
Field Description
Parameter Type Select Type or Element and click the Browse icon to display the
Type Chooser window for selecting the task parameter.
Name Accept the default name or enter a custom name. This field only
displays if Type is the selected parameter type.
Modifiable via worklist Select this check box to enable users to edit task payload data in the
footer of the Oracle BPM Worklist. For example, the approver in the
application may need to add approver comments.
Note:You can only define payload flex field mappings in the Oracle
BPM Worklist for payload parameters that are simple XML types.
Figure 26–13 Human Task Editor — Assignment and Routing Policy Section
The configuration tasks for each participant type are described in subsequent
sections.
3. See the following section based on your selection:
26-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
For This
Subsection... See...
Add Participant
Type
Section 26.6.5.2, "Configuring the Single Approver Participant Type" on
■ Single approver page 26-24
■ Group vote Section 26.6.5.3, "Configuring the Group Vote Participant Type" on
page 26-27
■ Management
chain Section 26.6.5.4, "Configuring the Management Chain Participant Type"
on page 26-31
■ Sequential list of
approvers Section 26.6.5.5, "Configuring the Sequential List of Approvers
Participant Type" on page 26-34
■ FYI assignee
Section 26.6.5.6, "Configuring the FYI Assignee Participant Type" on
■ External routing
page 26-37
service
Section 26.6.5.7, "Configuring the External Routing Service Participant
Type" on page 26-38
4. See the following task assignment and routing policy sections shown in
Figure 26–13 after you have configured a participant type. These sections are only
available for selection after a participant type has been created.
■ A single user, group, or application role (for example, jstein), which in the case
of a single approver, is captured as follows:
<participant name="Assignee1">
<resource isGroup="false" type="STATIC">jstein</resource>
</participant>
You may have a business requirement to create a dynamic list of task approvers
specified in a payload variable. This XPath expression can resolve to zero or more
XML nodes. Each node value can be either of the following:
■ A single user, group, or application role
■ A delimited string of users, groups, or application roles. For example, the
following task shows that the payload message attribute is of type xsd:String
and its value is a comma-delimited string of approvers. This node can be used to
specify the participants.
<task>
. . .
<payload>
<approvers>jstein,wfaulk,cdickens</approvers>
</payload>
</task>
The default delimiter for the assignee delimited string is a comma (,). This delimiter
can be changed using the assigneeDelimiter XML element in the
wf-config.xml file. This delimiter applies to all workflows in the system.
Specifying participants in this manner is applicable to all participant types, although
they are interpreted differently for each type. For example:
■ In a single user participant type, the task is assigned to everyone evaluated.
■ In a sequential list of approvers participant type, the task is sequentially assigned
to users and groups evaluated in the list.
■ In a group vote participant type, a task is created for each user and group
evaluated in the list.
This interpretation of resource XPath expressions provides
orcl:create-nodeset-from-delimited-string-equivalent functionality to
enable you to specify a dynamic list of one or more task approvers (resource element
members) from the payload variable.
26-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
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.
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
Instructions for configuring the following subsections of the Add Participant Type
- Single Approver window are listed in Table 26–3:
– User Id or Group Id — Enter a user or group name or click the first icon
(Browse) to the right of the field to display a window for selecting a user
or group configured through the identity service. The identity service
enables user authorization and the lookup of user properties, roles, group
memberships, and privileges. User information is obtained from the user
directory or repository that is configured with the Identity Service. (JAZN,
LDAP, OID, or any third party user store). For group assignments, the
task must be performed by one of the members in the group. Therefore,
the user must first claim it in order to act on it.
– Application Role — Enter an application role that contains specific
permissions for acting on tasks. For example, assume you have two roles:
worker and supervisor. The worker role can only view tasks assigned to
the worker group. The supervisor role can view all tasks for their direct
reports and reassign tasks. Application roles must be mapped to
enterprise roles that are typically in the enterprise LDAP server. During
deployment time, you map application roles to enterprise roles in Oracle
Enterprise Manager Fusion Middleware Control Console. You can also use
Java Platform Security (JPS) policy store APIs to map enterprise roles to
application roles.
■ By expression
– Dynamic User XPath or Dynamic Group XPath — Dynamically assign
this task to a user (for example, jcooper) or group (for example,
administrators) by clicking the icon to the right of the field to display the
Expression Builder window. Users who are members of a group are
assigned this task. For a user to act on a task assigned to a group, they
must first claim the task in the Oracle BPM Worklist during run time.
– Dynamic Application Role XPath — Dynamically assign this task to an
application role.
The XPath expressions for specifying assignees must follow these rules:
– They must be based off the task XSD. This includes the payload as defined
in the payload section. For example,
/task:task/task:payload/order:orderAssignee is an example of an XPath
expression based of the task XSD.
– The XPath expressions cannot contain BPEL-specific XPath functions such
as bpws:getVariableData(), and so on because these XPath expressions are
not evaluated from the context of a BPEL instance.
– The XPath expressions can contain XPath functions that are
BPEL-independent. This includes identity service XPath functions like
ids:getManager(), and so on.
26-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
The expression to bypass a task participant must evaluate to a Boolean value. For
example, /task:task/task:payload/order:orderAmount < 1000 is a valid XPath
expression for skipping a participant.
Figure 26–15 Add Participant Type — Group Vote (Upper Section of Window)
Figure 26–16 Add Participant Type — Group Vote (Lower Section of Window)
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
Instructions for configuring the following subsections of the Add Participant Type
- Group Vote window are listed in Table 26–4:
26-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
26-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
If selected, the workflow waits for all responses before an outcome is initiated.
Figure 26–17 Add Participant Type — Management Chain (Upper Section of Window)
Figure 26–18 Add Participant Type — Management Chain (Lower Section of Window)
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
Instructions for configuring the following subsections of the Add Participant Type
- Management Chain window are listed in Table 26–5:
26-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
26-34 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
Instructions for configuring the following subsections of the Add Participant Type
- Sequential List of Approvers window are listed in Table 26–6.
user store). For group assignments, the task must be performed by one of the
members in the group. Therefore, the user must first claim it in order to act on
it.
■ By expression
Dynamically assign this task to a user (for example, jcooper) or group (for
example, administrators) by clicking the icon to the right of the field to
display the Expression Builder window. Users who are members of a group
are assigned this task. For a user to act on a task assigned to a group, they
must first claim the task in the Oracle BPM Worklist during run time.
26-36 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
Instructions for configuring the following subsections of the Add Participant Type
- FYI Assignee window are listed in Table 26–7:
■ By name
– User Id or Group Id — Enter a user or group name or click the first icon
(Browse) to the right of the field to display a window for selecting a user
or group configured through the identity service. The identity service
enables user authorization and the lookup of user properties, roles, group
memberships, and privileges. User information is obtained from the user
directory or repository that is configured with the Identity Service. (JAZN,
LDAP, OID, or any third party user store). For group assignments, the
task must be performed by one of the members in the group. Therefore,
the user must first claim it in order to act on it.
– Application Role — Enter an application role that contains specific
permissions for acting on tasks. For example, assume you have two roles:
worker and supervisor. The worker role can only view tasks assigned to
the worker group. The supervisor role can view all tasks for their direct
reports and reassign tasks. Application roles must be mapped to
enterprise roles that are typically in the enterprise LDAP server. During
deployment time, you map application roles to enterprise roles in Oracle
Enterprise Manager Fusion Middleware Control Console. You can also use
JPS policy store APIs to map enterprise roles to application roles.
■ By expression
– Dynamic User XPath or Dynamic Group XPath — Dynamically assign
this task to a user (for example, jcooper) or group (for example,
administrators) by clicking the icon to the right of the field to display the
Expression Builder window. Users who are members of a group are
assigned this task. For a user to act on a task assigned to a group, they
must first claim the task in the Oracle BPM Worklist during run time.
– Dynamic Application Role XPath — Dynamically assign this task to an
application role.
26-38 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Enter a recognizable label for this participant in the Label field. This label must be
unique among all the participants in the task definition (for example, Approval
Manager, Primary Reviewers, and so on).
3. Click the + sign to add additional name and pair value parameters.
Figure 26–22 Human Task Editor — Assignment and Routing Policy Section
This check box is the equivalent of the Adhoc workflow pattern of pre-10.1.3 Oracle
BPEL Process Manager releases. This applies when there is at least one participant. In
this case, each user selects users or groups as the next assignee when approving the
task.
1. If you want this task assignee to invite other participants into the workflow before
routing it to the next assignee in this workflow, select the Allow all participants to
invite other participants check box.
26-40 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Click Route task to all participants, in order specified to route tasks to all
participants in the specified order.
3. Click the icon to the right of the Routing Condition field to display the Expression
Builder window 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
below a specific amount, no approval is required by their manager.
4. Click OK to return to the Human Task editor.
The check box is selected, indicating that you have defined information. You can
click the icon to the right of the Complete task when a participant chooses
<outcome> check box to edit this information.
26.6.5.12.1 Introduction to Advanced Task Routing Using Business Rules You can define
state machine routing rules using Oracle Business Rules. This enables you to create
Oracle Business Rules that are evaluated:
■ After a routing slip task participant sets the outcome of the task
■ Before the task is assigned to the next routing slip participant
This enables you to override the standard task routing slip method described in
Section 26.6.5.10, "Routing Tasks to All Participants in the Specified Order" on
page 26-40 and build complex routing behavior into tasks.
26.6.5.12.2 Fact Types 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:
■ Asserts facts into the decision service
■ Executes the advanced routing rule set
Rules can test values in the asserted facts and specify the routing behavior by setting
values in a TaskAction fact type.
Table 26–8 describes the fact types asserted by the task service.
26-42 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
See Also: Oracle Fusion Middleware User's Guide for Oracle Business
Rules for details on facts
26.6.5.12.3 Actions In order to instruct the task service on how to route the task, rules
can specify one of a number of task actions. This is done by updating the TaskAction
fact asserted into the rule session. However, rules should not directly update the
TaskAction fact. Instead, rules should call one of the action RL functions, passing the
TaskAction fact as a parameter. These functions handle the actual updates to the fact.
For example, to specify an action of go 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 26–9:
26.6.5.12.4 Sample Rule Set This section describes how to use rules to implement
custom routing behavior with a simple example. A human workflow task is created
for managing approvals of expense requests. The outcomes for the task are APPROVE
and REJECT. The task definition includes an ExpenseRequest payload element. One of
the fields of ExpenseRequest is the total amount of the expense request. The routing
slip for the task consists of three single participants (Assignee1, Assignee2, and
Assignee3).
By default, the task gets routed to each of the assignees, with each assignee choosing to
APPROVE or REJECT the task.
Instead of this behavior, the desired routing behavior is as follows:
■ 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. Note that 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 Rule Author.
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 rule set are
triggered.
■ Early approval rule
IF
and
(for each case where) PreviousOutcome is a PreviousOutcome
PreviousOutcome.outcome == "APPROVE"
and
(for each case where) TaskAction is a TaskAction
THEN
call COMPLETE(TaskAction)
26-44 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
IF
and
(for each case where) PreviousOutcome is a PreviousOutcome
PreviousOutcome.outcome == "REJECT" and
PreviousOutcome.logicalAssignee != "Assignee1"
and
(for each case where) TaskAction is a TaskAction
THEN
call PUSHBACK(TaskAction)
and
(for each case where) PreviousOutcome is a PreviousOutcome
PreviousOutcome.outcome == "REJECT" and
PreviousOutcome.logicalAssignee == "Assignee1"
and
(for each case where) TaskAction is a TaskAction
THEN
call COMPLETE(TaskAction)
3. 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.
See Also:
■ Oracle Fusion Middleware User’s Guide for Oracle Business Rules
■ Oracle Fusion Middleware Language Reference Guide for Oracle
Business Rules
Figure 26–23 Human Task Editor — Expiration and Escalation Policy Section
26-46 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
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 of the participant’s level, 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 to interpret the participant level expiration for the participants is described
below:
■ Management Chain — Each participant in the management chain gets the same
expiration duration. 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 task expires and the escalation and renewal policy is applied.
■ Sequential list of approvers — Each assignment in the management chain gets the
same expiration duration as the one specified in the sequential list of approvers.
Note that 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 task expires and the escalation and renewal policy is applied.
■ Group vote
– In a group vote workflow, if the parallel participants are specified as a
resource, a routing slip is created for each of the resources. The expiration
duration of each created routing slip follows these rules:
Note: When the parent task expires in a parallel task, the subtasks
are withdrawn if those tasks have not expired or completed.
In the following routing slip sample, participant Loan Agent Group has an
expiration duration of 1 day and participant Loan Agent Supervisor does not
have any expiration duration on the task, even though an expiration duration is
specified at the routing slip level. In this example, the routing slip is treated just as if
there were no expiration duration specified at the routing slip level.
<routingSlip xmlns="http://xmlns.oracle.com/pcbpel/workflow/routingslip">
<expirationDuration>PT10D </expirationDuration>
<participants>
expirationDuration="PT2D">
<resource isGroup="true" type="STATIC">wfaulk</resource>
<levels type="STATIC">1</levels>
<title type="STATIC">Vice President</title>
</managementChain>
<participant name="Reviewer">
<resource isGroup="true" type="STATIC">sfitzger</resource>
</participant>
</participants>
</routingSlip>
Table 26–10 demonstrates the expiration policy. Note that the management chain in the
above example evaluates to two users — wfaulk and cdickens (manager of
wfaulk).
26-48 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Select an escalation and expiration policy. You can enter a fixed time or a dynamic
time by clicking the icon to the right of the By Expression field to display the
Expression Builder window.
■ Section 26.6.6.2, "Never Expire Policy"
■ Section 26.6.6.3, "Expire After Policy"
■ Section 26.6.6.4, "Renew After Policy"
■ Section 26.6.6.5, "Escalate After Policy"
26-50 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
26-52 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
1. Click the + sign to expand the Notification Settings section (displays as shown in
Figure 26–28).
Instructions for configuring the following subsections of the Notification Settings
section are listed in Table 26–11.
26-54 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
This message applies to all the supported notification channels: e-mail, voice,
instant message, and SMS. E-mail 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.
2. Modify the message wording as necessary.
3. Click OK to return to the Human Task editor.
Field Value
Make notifications secure 1. Select to make the notification message secure. If
(exclude details) selected, a default notification message is used. There
are no HTML worklist task details, attachments, or
actionable links in the e-mail. Only the task number is in
the message.
See Also: Section 28.2.9, "Sending Secure Notifications"
on page 28-28
Make e-mail messages 1. Select to make e-mail notifications actionable. This
actionable enables you to perform task actions through e-mail.
See Also: Section 28.2.4, "Sending Actionable Messages"
on page 28-24 for additional configuration details and
Oracle Fusion Middleware Administrator’s Guide for Oracle
SOA Suite for instructions on configuring outbound
and inbound e-mails
26-56 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
Field Value
Send task attachments with 1. Select to send task attachments with the notification
e-mail notifications message.
2. If you want to customize the notification headers, select
Custom Notification Headers.
Custom notification headers are used to specify name
and value pairs to identify key fields within the
notification. These entries can be used by users to define
delivery preferences for their notifications. For example:
You can set Name to ApprovalType and value to
Expense or maybe Name to Priority and value to High.
Users can then use specify delivery preferences in the
worklist application. These preferences can be based on
the contents of the notification.
Note that the rule-based notification service is only used
to identify the preferred notification channel to use. The
address for the preferred channel is still obtained from
the identity service.
3. Add name and pair value parameters by name or XPath
expression.
See Also: "Sending Inbound and Outbound
Attachments" on page 28-27, "Custom Notification
Headers" on page 28-29, Chapter 40, "User Messaging
Preferences", and preferences details in the Using Oracle
BPM Worklist chapter.
<function name="Department_supervisor"
classpath="oracle.bpel.services.workflow.assignment.dynamic.patterns.
DepartmentSupervisor">
</function>
</dynamicAssignmentFunctions>
26-58 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
Note: For 11g Release 1, this parameter must be configured from the
Task Service page in Oracle Enterprise Manager Grid Control Console.
Access this page by selecting Administration > Human Workflow
from the SOA Infrastructure menu, then selecting the Task Service
tab.
26-60 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
3. Click OnAssigned to display a list of additional callback values to select for this
column.
The following callbacks are available:
■ OnCompleted — This callback is invoked when the task is completed,
expired, withdrawn, or errored.
■ OnAssigned — This callback is invoked when the task is assigned to a new set
of assignees due to the following actions:
– outcome update
– skip current assignment
– override routing slip
■ OnUpdated — This callback is invoked for any other update to the task that
does not fall in the OnTaskComplete or OnTaskAssigned callback. This
26-62 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
See Also: Section 28.1.10, "Digital Signatures and the Evidence Store
Service" on page 28-16
Note: Task contents access rules and task actions access rules exist
independently of one another.
26.6.8.9.1 Introduction to Access Rules Access rules are computed based on the
following details:
■ 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 means only assignees and nobody else 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
■ Flex fields do not have individual representation in the map returned by
TaskMetadataService.getVisibilityRules().
■ All message attributes in the map returned by
TaskMetadataService.getVisibilityRules() are prefixed by
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 participant’s access rules by
calling the API on
oracle.bpel.services.workflow.metadata.ITaskMetadataService.
public Map<String, IPrivilege> getTaskVisibilityRules(IWorkflowContext context,
String taskId)
throws TaskMetadataServiceException;
26.6.8.9.2 Specifying Task Content Access Rules You can specify the access levels that
specific users (such as the approval manager) have to act on task attributes (such as a
payload).
1. Click Configure Visibility.
The Configure Task Content Access window appears.
2. Click the Create icon and select Add Content Access Rule.
26-64 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
■ ATTACHMENTS
■ HISTORY
■ ASSIGNEES (covers assignees, assignee users, and assignee groups)
■ FLEXFIELDS
■ DATES (Covers the start date, end date, assigned date, created date,
expiration date and updated date of comments, task, and so on)
■ REVIEWERS
■ Payload message attributes
4. Select the participants and their privileges (no access, read access, or write access)
for acting upon the selected task attribute. Participants that you do not select have
complete access.
■ Approval Manager
■ PUBLIC
■ APPROVERS
■ ASSIGNEES
■ CREATOR
■ OWNER
■ REVIEWERS
■ ADMIN
■ Individual participants as specified in the routing slip of the task definition
For example, if you provide the Approval Manager and CREATOR users
with write access, the APPROVERS user with read access, and the PUBLIC
and ASSIGNEES users with no access on the PAYLOAD task attribute, the
window appears as follows:
5. Click OK.
The Configure Task Content Access window displays details about your
selections.
6. Click OK.
26.6.8.9.3 Specifying Task Actions Access Rules You can specify the actions that specific
users (such as the approval manager) have to act on task attributes (such as a payload)
that you specified in the Configure Task Content Access window.
1. Click Configure Visibility.
The Configure Task Content Access window appears.
2. Click the Create icon and select Add Action Access Rule.
26-66 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Human Task Definition with the Human Task Editor
5. Click OK.
The Configure Task Content Access window appears.
26-68 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
26.6.10 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 clicking the metadata task configuration .task file in the Application
Navigator.
1. Select Save from the File main menu or click the X sign to close the .task
metadata task configuration file.
2. If you click the X sign, select Yes when prompted to save your changes.
See Also: Section 26.6, "Creating the Human Task Definition with
the Human Task Editor" on page 26-12 for instructions on creating a
human task
Note: When you first drag and drop this activity into Oracle
JDeveloper, the window is named Add a Human Task. After you finish
specifying details on this window and click OK, the name of this
window changes to simply Human Task.
The .task file of the human task service component is associated with the BPEL
process.
7. See the following sections to configure the human task activity:
■ Section 26.7.2, "Defining the Human Task Activity Title, Initiator, Priority, and
Parameter Variables"
■ Section 26.7.4, "Defining the Human Task Activity Advanced Features"
26.7.2 Defining the Human Task Activity Title, Initiator, Priority, and Parameter
Variables
Figure 26–30 shows the General tab that displays after you select the human task.
26-70 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
The General tab of the Human Task activity enables you to perform the tasks shown in
Table 26–13:
See Also: Section 26.8.3.5, "Associating the Human Task and BPEL
Process Service Components" on page 26-88 for an example of
specifying the task title name
1. Double-click the dots in the BPEL Variable column to map the task parameter to
the BPEL variable. You must map only the task parameters that carry input data.
For output data that is filled in from the worklist, you do not need to map the
corresponding variables.
The Task Parameters window appears.
2. Expand the Variables navigation tree and select the appropriate task variable.
26-72 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
3. Click OK.
The Human Task window appears as follows.
4. Click OK.
5. If you want to define advanced features for the human task activity, click the
Advanced tab and go to section Section 26.7.4, "Defining the Human Task Activity
Advanced Features" on page 26-77. Otherwise, click OK to close the Human Task
window.
Figure 26–31 shows how a workflow interaction is modeled in Oracle BPEL Process
Manager. Figure 26–31 also illustrates the interaction when no BPEL callbacks are
modeled. In this case, once a task is complete, the BPEL process is called back with the
completed task. No intermediary events are propagated to the BPEL process instance.
It is recommended that any user customizations be done in the first assign,
AssignTaskAttributes, and that AssignSystemTaskAttributes not be changed.
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 + sign next to the human task activity in Oracle JDeveloper to display its
contents, as shown in Figure 26–32.
26-74 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
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
AssignWorkflowContext
Assigns the workflow context to use for
interactions with the workflow service
26-76 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
The Advanced tab of the Human Task activity enables you to perform the tasks shown
in Table 26–14:
26-78 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Associating the Human Task Service Component with a BPEL Process
the purchase. You can link these different tasks in the BPEL process by chaining the
second task to the first task with this option.
1. Select the Include task history from check box to extend a previous workflow task
in the BPEL process. Selecting this check box 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
■ Comments added to the task in the previous workflow
■ Attachments added to the task in the previous workflow
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 needs to see the interviewers
and the comments they made about the candidate. This process can be modeled
using a group vote for the hiring. If the candidate is hired, a database adapter is
used to create the entry in the HR database. After this, a simple workflow can
include the task history from the group vote so that the hiring request, history, and
interviewer comments are carried over. This simple workflow is assigned to the
HR contact.
3. Select a payload to use:
■ Clear old payload and recreate — This option is applicable when the payload
attributes in the XML files of the human tasks involved in this extended
workflow are different. For example, the payload attribute for the human task
whose history you are including has three extra attributes than the payload of
the other human task.
■ Use existing payload — This option is applicable when the payload attributes
in the XML files of the human tasks involved in this extended workflow are
exactly the same.
3. Go to the Human Task editor for this human task (the .task file).
4. Expand the Advanced Settings section at the bottom of the editor.
5. Click Allow task and routing customization in BPEL callbacks.
This check box must be selected to use callbacks. This enables you to update the
metadata.
See Also:
■ Section 26.6.8.7, "Allowing Task and Routing Customization in
BPEL Callbacks" on page 26-62
■ Section 26.7.3.1, "BPEL Callbacks" on page 26-75
26-80 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') =
'WITHDRAWN'">
<bpelx:annotation>
<bpelx:pattern>Task is withdrawn
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') =
'EXPIRED'">
<bpelx:annotation>
<bpelx:pattern>Task is expired
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') =
'ERRORED'">
<bpelx:annotation>
<bpelx:pattern>Task is errored
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<otherwise>
<bpelx:annotation>
<bpelx:pattern>Task is EXPIRED, WITHDRAWN or ERRORED
</bpelx:pattern>
</bpelx:annotation>
...
</otherwise>
</switch>
26.8.2 Prerequisites
This example assumes you are familiar with basic BPEL constructs, including BPEL
activities and partner links, and basic XPath functions. Familiarity with the SOA
Composite Editor and Oracle JDeveloper—the environment for designing and
deploying BPEL processes—is also assumed.
26-82 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
Field Value
Application Name Enter an application name (for this example,
HelpDeskRequestApp).
Application Template Select No Template [All Technologies].
4. Accept the default values for all remaining settings, and click OK.
5. The Create Project window appears.
6. Enter a name for the project (for this example, HelpDeskRequestComposite), and
click OK.
Field Value
Project Name Enter HelpDeskRequestProcess.
Template Select Asynchronous BPEL Process.
Expose as Composite Service Select the check box. After process creation, note the
SOAP adapter service that appears in the Services swim
lane. This service provides the entry point to the SOA
composite application from the outside world.
16. Click the Browse icon to the right of the Output field.
26-84 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
Field Value
Human Task Definition Enter HelpDeskRequestHumanTask.
Name
Expose as Composite Service Do not select the check box.
Field Value
Title Enter Help desk request for .
Note: Ensure that you enter a blank space after for.
Outcomes Enter RESOLVED,UNRESOLVED
Description Leave unspecified.
Priority Accept the default value.
Category Leave unspecified.
Owner Leave unspecified.
2. Click the Add icon on the right side of the Parameters section to specify the task
payload.
The Add Task Parameter window is displayed.
3. Click Element and then the Browse icon to the right of this field.
The Type Chooser window appears.
4. Expand and select Project Schema Files > serviceRequest.xsd > Requester, and
click OK.
5. Ensure that the Modifiable via worklist check box is not selected.
6. Click OK on the Add Task Parameter window.
7. Click the Add icon again on the right side of the Parameters section.
8. Click Type and then the Browse icon to the right of this field.
9. Expand and select XML Schema Simple Types > string.
10. Click OK.
26-86 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
13. Repeat Steps 7 through 11 and create the remaining parameters with the following
values:
14. Click the Add icon on the right side of the Assignment and Routing Policy
section.
The Add Participant Type window appears.
15. Select Single Approver from the Type list.
This participant type acts alone on the task.
16. Enter Help Desk Agent in the Label field.
19. Select the Allow this participant to invite other participants check box to enable
adhoc routing.
20. Click OK.
21. Click the + sign to expand the Expiration and Escalation Policy section.
Field Value
Drop-Down List Select Escalate after.
Fixed Duration Day Select this button.
Day Select 1.
Minutes Select 10.
Field Value
Maximum Escalation Levels Enter 3.
Highest Approver Title Select CEO.
26.8.3.5 Associating the Human Task and BPEL Process Service Components
1. Double-click the BPEL process service component in the SOA Composite Editor.
The BPEL process displays in Oracle JDeveloper.
2. Select BPEL from the Component Palette.
3. Expand BPEL Activities and Components.
4. Drag and drop a Human Task below the receiveInput receive activity.
The Add a Human Task window appears.
5. If it is not currently displaying, select HelpDeskRequestHumanTask from the
Task Definition list.
The window refreshes to display additional fields.
6. Note that Help desk request for appears in the Task Title field. You entered this
name in Step 1 on page 26-86.
7. Click the XPath Expression Builder icon to the right of this field to display the
Expression Builder window.
26-88 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
8. Press Ctl and then the space bar in the Expression field and select the following
XPath expression:
bpws:getVariableData('inputVariable','payload','/ns1:HelpDeskRequest/ns1:req
uester/ns1:ID')
9. Click Insert Into Expression.
10. Click OK.
The XPath expression displays in the Task Title field.
11. Click the BPEL Variable entry for the requester parameter.
13. Expand Process > Variables > inputVariable > payload > ns1:HelpDeskRequest
> ns1:Requester.
26-90 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
13. Enter HelpDeskRequestTaskFlow in the Project Name field, and click OK.
26-92 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
10. Drag and drop additional task icons into the JSPX window and select these
options:
■ Human Task > Task Comments.
■ Human Task > Task Attachments.
■ Human Task > Task History
When complete, the bottom part of the JSPX window appears as follows:
11. Select ADF Faces from the Component Palette. If this entry does not appear in the
Component Palette, select All Pages from the list.
12. Drag and drop Panel Group Layout between the Header and Comment sections.
This displays a small blue box between the two sections.
15. Drag and drop requester in front of the small blue box that represents the Panel
Group Layout.
26-94 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
A menu appears.
16. Select the read-only drop handler for requester by selecting Forms > ADF
Read-only Form.
18. Drag and drop payload below the Panel Group Layout and select ADF Form >
Forms.
20. Drag and drop resolution below the payload and select Forms > ADF Form.
21. Click OK when prompted on the Edit Form Fields window.
The JSPX window appears as follows:
26-96 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
End-to-End Workflow Examples
23. Select and double-click Application Sources > WEB-INF > taskflow.properties.
32. Click OK to close the WAR Deployment Profile Properties window and the Project
Properties window.
33. Right-click HelpDeskRequestTaskFlowApp and select Deploy >
HelpDeskRequestTaskFlowApp > to > application_server_connection. If you do
not have a connection, select New Connection and provide responses to the
prompts in the Application Server Connection wizard.
34. The Configure Application window appears.
2. Log in as jstein/welcome1.
3. Select HelpDeskRequestSCAApp.
26-98 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
31
31 Designing Task Display Forms for Human
Tasks
As described in Chapter 26, "Designing Human Tasks," the human workflow service
creates tasks for users to interact with the business process. Each task has two
parts—the task metadata and the task form. The task form is used to display the
contents of the task to the user’s worklist.
Oracle BPM Worklist displays all worklist tasks that are assigned to a user or a group.
When a worklist user drills down into a specific task, the task display form renders the
details of that task For example, an expense approval task may show a form with line
items for various expenses, and a help desk task form may show details such as
severity, problem location, and so on.
The task display form renders custom actions and system actions. Custom actions are
created using task outcomes. The task display form is created using ADF task flows in
Oracle JDeveloper. This chapter describes how to design and customize task display
forms.
This chapter contains the following sections:
■ Section 31.1, "Introduction to the Task Display Form"
■ Section 31.2, "Associating the Task Flow with the Task Service"
■ Section 31.3, "Creating an ADF Task Flow Based on a Human Task"
■ Section 31.4, "Creating a Task Display Form"
■ Section 31.5, "Creating an E-Mail Notification"
■ Section 31.6, "Deploying a Composite Application with a Task Flow"
■ Section 31.7, "Displaying a Task Display Form in the Worklist"
■ Section 31.8, "Troubleshooting the Task Display Form"
Beta Draft Designing Task Display Forms for Human Tasks 31-1
Associating the Task Flow with the Task Service
Figure 31–1 ADF Task Flow Based on a Human Task, in Oracle JDeveloper
31.3.1 How to Create an ADF Task Flow Within the Same Application as the Human
Task
[Summary to come]
To create an ADF task flow within the same application as the human task
1. Open the BPEL process (in this example, HelpDeskRequestProcess.bpel) within
the SOA composite application.
31-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an ADF Task Flow Based on a Human Task
Figure 31–2
Beta Draft Designing Task Display Forms for Human Tasks 31-3
Creating an ADF Task Flow Based on a Human Task
31.3.2 How to Create an ADF Task Flow Within the Same Composite Application as the
Human Task
The ADF Task Flow Based on Human Task function prompts you for the .task file to
use for the ADF task flow, which you find using the file browser or the resource
catalog. You must have previously created a human task (.task file) as part of a SOA
composite before you can create a task flow. See Chapter 26, "Designing Human
Tasks," for how to create the .task file for the help desk request example used in the
following steps. When the .task file is selected, data controls are automatically
created based on the task parameters and outcomes.
You can also follow these steps to create the task flow in the same application. Instead
of steps 1 and 2, select the application that contains the human task (for this example,
HelpDeskRequestApp).
31.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:
■ Various parameters and operations to access task data and act on it
■ Drop handlers with which you can rapidly create interface regions to display
contents of the task
31-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
The human task-aware data controls appear in the Data Controls panel of the Oracle
JDeveloper Application Navigator, as shown in Figure 31–3. The data controls for the
task (represented by the task node in the figure) have custom drop handlers to render
specific regions of the task, for example, the task header, system actions, custom
actions, comments, and so on. In addition, the standard ADF drop handlers, used to
create tables, forms, and so on, are available for rendering the payload.
Beta Draft Designing Task Display Forms for Human Tasks 31-5
Creating a Task Display Form
Figure 31–4 Custom Drop Handlers for Creating the Task Display Form for a Human
Task
The custom drop handlers are designed to autogenerate the following regions of the
task details page:
■ Task header
■ Task history
■ System actions
■ Custom actions
■ Task comments
■ Task attachments
■ Complete task without payload
■ Complete task with payload
■ Task display for notification
31-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
Beta Draft Designing Task Display Forms for Human Tasks 31-7
Creating a Task Display Form
■ Request More Information—You 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.
■ Go—This button is used to update a system action that you selected from a list.
The list can contain the following simple actions:
– Escalate—An escalated task is assigned to the user’s manager. The Comments
area is available for an optional comment.
– Pushback—This action sends a task up one level in the workflow to the
previous assignee.
– Release—Releasing 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.
– Renew—Renewing 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. [Cross-reference to come. Will point to screen
and instructions in the SOA Admin Guide.]
A renewal appears in the task history. The Comments area is available for an
optional comment.
– Suspend/Resume—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. Buttons that update a task are disabled after suspension.
– Withdraw—Only the task creator can withdraw (cancel) the task. The
Comments area is available for an optional comment. The business process
determines what happens next.
■ Save—Changes to the task are saved.
While you are creating a task display form, all possible system action buttons appear,
although only those actions that are appropriate for the task state and fit the user’s
privileges will appear in the worklist. Figure 31–6 shows an example of system action
buttons on a task display form.
31-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
Beta Draft Designing Task Display Forms for Human Tasks 31-9
Creating a Task Display Form
Figure 31–10
31-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
See Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework for more information about standard ADF drop handlers.
31.4.3 How to Create a Task Display Form Using Individual Drop Handlers
The following steps describe how to create the task display form—a .jspx file—for a
help desk request business process. When you finish, the task display form will have
Beta Draft Designing Task Display Forms for Human Tasks 31-11
Creating a Task Display Form
six regions, for the custom action buttons, system action buttons, task header,
comments, attachments, and task history.
See the alternative discussed in Section 31.4.5, "How to Create a Task Display Form
Using the Complete Task with Payload Drop Handler."
Before you create this task display form, you must have created the following:
■ A new application and SOA project, and a human task service—a single approver
workflow in which the help desk request is either resolved or unresolved by a
single help desk employee. See Section 26.8.3, "Modeling the Help Desk Request,"
for more information.
■ An ADF task flow based on the human task. See Section 31.3.2, "How to Create an
ADF Task Flow Within the Same Composite Application as the Human Task," for
more information.
To create a task display form for the help desk request example:
Note: Click Save All frequently, especially after each drag and drop.
Figure 31–11
6. In the Edit Action Bindings dialog, accept the defaults and click OK.
This creates buttons for custom actions: Resolved and Unresolved, as shown in
Figure 31–12.
31-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
Figure 31–12
Figure 31–13
10. Drag and drop the task icon again, this time below the panel of buttons.
Beta Draft Designing Task Display Forms for Human Tasks 31-13
Creating a Task Display Form
Figure 31–14
12. Drag and drop additional task icons into the JSPX window, selecting these options
with each iteration:
■ Human Task, then Task Comments.
■ Human Task, then Task Attachments.
■ Human Task, then Task History
The task display form now has six regions, for custom action buttons, system
action buttons, the task header, comments, attachments, and task history.
2. Expand Layout.
3. Drag and drop Panel Group Layout between the Header and Comment sections,
as shown in Figure 31–15
Figure 31–15
31-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
Figure 31–16
6. From the context menu, select Forms, then ADF Read-only Form, as shown in
Figure 31–17.
Figure 31–17
7. In the Edit Form Fields dialog, accept the defaults and click OK.
This creates the following portion of the payload region, between the Header and
Comments, as shown in Figure 31–18.
Figure 31–18
8. Drag and drop payload below the Panel Group Layout and select Forms, then
ADF Forms.
9. In the Edit Form Fields dialog, accept the defaults and click OK.
10. Drag and drop resolution below the payload region and select Forms, then ADF
Form.
11. In the Edit Form Fields dialog, accept the defaults and click OK.
Beta Draft Designing Task Display Forms for Human Tasks 31-15
Creating a Task Display Form
Figure 31–19
The task display form, shown in Figure 31–20, is completed and ready to be deployed.
31-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Task Display Form
31.4.5 How to Create a Task Display Form Using the Complete Task with Payload Drop
Handler
The following steps describe how to use a drop handler that creates the task display
form, including the payload, without having to individually build each region.
See the alternative discussed in Section 31.4.3, "How to Create a Task Display Form
Using Individual Drop Handlers."
To create a task display form using the Complete Task with Payload drop
handler:
Note: Click Save All frequently, especially after each drag and drop.
Beta Draft Designing Task Display Forms for Human Tasks 31-17
Creating an E-Mail Notification
3. In the Application Navigator Data Controls panel, expand the human task name,
then loadData(String, String, String), and then Return.
4. Drag and drop the task icon into the taskDetails.jspx window.
5. Select Human Task, then Complete Task with Payload.
6. In the Edit Action Bindings dialog, select a data collection and the action you want
the data control to initiate and click OK.
7.
8.
You are ready to add the payload region to the task display form.
The task display form is ready to be deployed. See Section 31.6, "Deploying a
Composite Application with a Task Flow," for more information.
31-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an E-Mail Notification
■ 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.)
Beta Draft Designing Task Display Forms for Human Tasks 31-19
Creating an E-Mail Notification
Figure 31–22
4. From the Component Palette, drag and drop the Router icon into the visual
editor.
5. Click router1 below the icon and enter PageRouter.
6. Click the router - PageRouter - Property Inspector tab.
7. In the default-outcome field, enter default.
8. Add more cases.
9. In the outcome field, enter EmailPage.
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 visual editor, drag a control flow from PageRouter to taskDetails.
The control flow is automatically labeled default, as shown in Figure 31–23.
31-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating an E-Mail Notification
Figure 31–23
14. In the visual editor, drag a control flow from PageRouter to EmailPage.
15. Click the control flow to see the control-flow-case - EmailPage - Property
Inspector.
16. In the from-outcome field, enter EmailPage.
Figure 31–24 shows the completed control flow.
Beta Draft Designing Task Display Forms for Human Tasks 31-21
Creating an E-Mail Notification
Figure 31–24
2. In the Create JSF Page dialog, accept the defaults and click OK.
The EmailPage.jspx tab opens in the visual editor.
3. From the Component Palette, drag and drop Panel Group Layout into the visual
editor.
4. In the Panel Group Layout - vertical - Property Inspector tab, from the Layout
list, select vertical, as shown in Figure 31–25.
31-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying a Composite Application with a Task Flow
Figure 31–25
6. From the Component Palette, drag and drop Image into the panel group layout
area.
7. In the Insert Image dialog, search for an image, in this example, oracle.gif.
If you are asked if you want to put the image in the current document root, click
Yes.
8. Click Finish.
9. From the Data Controls panel, expand HelpDeskRequestHumanTask, then
loadData(String, String, String), and then Return.
10. Drag and drop task into the panel group layout area.
12. In the Edit Action Binding dialog, accept the defaults and click OK.
13. Drag and drop additional task icons into the JSPX window, selecting these options
with each iteration:
■ Human Task, then Task Comments.
■ Human Task, then Task Attachments.
■ Human Task, then Task History
To continue adding the task payload, see Step 1 in Section 31.4.4, "How to Add the
Payload to the Task Display Form."
Beta Draft Designing Task Display Forms for Human Tasks 31-23
Deploying a Composite Application with a Task Flow
Example 31–1 shows a sample hwtaskflow.xml file with comments on which values
can and cannot be changed.
<!-- Name of the client application used to view the tasks, defaults to
'worklist' -->
<ApplicationName>worklist</ApplicationName>
<!-- Type of ejb lookup used. If not specified, remote lookup is used. Values -
LOCAL, REMOTE, SOAP -->
<LookupType>LOCAL</LookupType>
<!-- Do not modify this element. Value must be 'false' for deployment to
complete successfully -->
<TaskFlowDeploy>false</TaskFlowDeploy>
<!-- Connection details for soa server for remote ejb lookup.
31-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying a Composite Application with a Task Flow
</hwTaskFlows>
See Section 31.6.1, "Before Deploying the Task Display Form: Port Changes,"
for more information.
b. Select soa-infra as the parent app during deployment.
Beta Draft Designing Task Display Forms for Human Tasks 31-25
Deploying a Composite Application with a Task Flow
11. Enter HelpDeskRequestTaskFlow in the Project Name field, and click OK.
12. Right-click the composite application name, select Deploy, and then application_
name > to > application_server_connection.
The Configure Application dialog appears.
If you do not have a connection, select New Connection and use the Application
Server Connection wizard.
13. In New Revision ID, enter 1.0.
See Section 31.6.1, "Before Deploying the Task Display Form: Port Changes,"
for more information.
b. Select soa-infra as the parent app during deployment.
15. Right-click HelpDeskRequestTaskFlowApp, select Deploy, and then
HelpDeskRequestTaskFlowApp module to SOAConnection.
16. Click OK.
If you are using a local EJB, then do the following:
a. Edit the LookupType value in hwtaskflow.xml as follows:
<LookupType>LOCAL</LookupType>
31-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Displaying a Task Display Form in the Worklist
See Section 31.6.1, "Before Deploying the Task Display Form: Port Changes,"
for more information.
b. Select soa-infra as the parent app during deployment.
31.6.5 What Happens When You Deploy the Task Display Form
After deployment, the task display form is available for display in the worklist. Users
log in to the worklist to act on their tasks.
See the following for more information:
■ Section 31.7.1, "How to Display the Task Display Form in the Worklist," for how to
log in
■ Chapter 33, "Using Oracle BPM Worklist," for how to act on tasks
Beta Draft Designing Task Display Forms for Human Tasks 31-27
Displaying a Task Display Form in the Worklist
See Section 33.4, "Acting on Tasks: The Task Details Page," for more information.
■ host_name is the name of the host on which Oracle BPEL Process Manager is
installed
■ The port_number used at installation (typically 8888) is noted in
SOA_Oracle_Home\install\bpelsetupinfo.text
31-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Troubleshooting the Task Display Form
ADF task flow logging: To enable ADF logging, add following fragments in OC4J_
HOME/j2ee/home/config/j2ee-logging.xml and restart the server.
Beta Draft Designing Task Display Forms for Human Tasks 31-29
Troubleshooting the Task Display Form
<handler name='console-handler'/>
</logger>
<logger name='oracle.adfinternal' level='FINE' useParentHandlers='false'>
<handler name='oc4j-handler'/>
<handler name='console-handler'/>
</logger>
<logger name='oracle.jbo' level='FINE' useParentHandlers='false'>
<handler name='oc4j-handler'/>
<handler name='console-handler'/>
</logger>
31-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
28
28 Human Task Services
Human task services and functions are responsible for a variety of tasks. This chapter
describes the human task services.
This chapter contains the following topics:
■ Section 28.1, "Human Task Services"
■ Section 28.2, "Notifications from Human Workflow"
■ Section 28.3, "Configuring the Assignment Service"
■ Section 28.4, "Human Task Service and Identity Service Related XPath Extension
Functions"
■ Section 28.5, "NLS Configuration"
■ Section 28.6, "Changes to APIs"
■ Section 28.7, "Summary"
28.1.1 EJB, SOAP, and Java Support for the Human Task Services
Table 28–1 lists the type of SOAP, EJB, and Java support provided for the task services.
Most human task services are accessible through SOAP and local and remote EJB 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 28–2 lists the location for the SOAP WSDL file for each task service.
28-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
Table 28–2 (Cont.) SOAP WSDL Location for the Task Services
Service name SOAP WSDL location
Task Metadata Service http://host:port/integration/services/TaskMetad
ataService/TaskMetadataServicePort?WSDL
User Metadata Service http://host:port/integration/services/UserMetad
ataService/UserMetadataService?WSDL
Runtime Config Service http://host:port/integration/services/RuntimeCo
nfigService/RuntimeConfigService?WSDL
Evidence Store Service http://host:port/integration/services/EvidenceS
ervice/EvidenceService?WSDL
Note: Human task service SOAP clients cannot be used when Web
service security is used.
See Also: Oracle Containers for J2EE Security Guide for configuration
instructions
28-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
28-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
28-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
Platform Security (JPS), or any custom user repository. The identity service enables
authentication and authorization of users and the lookup of user properties, roles,
group memberships, and privileges. IDM is the sole identity service provider for
Oracle Application Server 11g. IDM handles all storage and retrieval of users and roles
for various repositories, including XML, LDAP, and so on. More, specifically IDM
provides the following features:
■ All providers are consolidated under IDM. 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 IDM, through configuring Oracle
Virtual Directory (OVD) as an LDAP provider to IDM, or through both. OVD
aggregates data across various repositories.
■ Application roles are supported through the JPS policy store and groups are
supported through the IDM identity store. The JSP layer handles all
security-related functionality at the OC4J container level. The policy store of JPS
handles all policies defined at the application level. Properties related to IDM are
stored in the jps-config.xml file. The enterprise roles (groups) and application
roles of previous releases are no longer supported.
■ All privileges are validated against permissions, as compared to actions in
previous releases.
■ The following set of application roles are defined. These roles are automatically
defined in the soa-infra application of the JPS policy store.
– 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.
– BPMWorkflowAdmin — Grant this role to users who must perform any
workflow administrative action. This includes actions such as searching and
acting on any task in the system, creating and modifying user and group rules,
performing application customization, and so on. This role is granted the
BPMWorkflowCustomize role and the following permissions:
* workflow.mapping.protectedFlexField
* workflow.admin.evidenceStore
* workflow.admin
– BPMWorkflowCustomize—Grant this role to business users who must
perform flex field mapping to public flex fields. This role is also granted the
workflow.mapping.publicFlexField permission.
■ The following workflow permissions are defined:
– workflow.admin — Controls who can perform administrative actions
related to tasks, user and group rules, and customizations
– workflow.admin.evidenceStore — Controls who can view and search
evidence records related to digitally-signed tasks (tasks that require a
signature with the use of digital certificates).
– workflow.mapping.publicFlexField — Controls who can perform
mapping of task payload attributes to public flex fields.
– workflow.mapping.protectedFlexField — Controls who can perform
mapping of task payload attributes to protected flex fields.
See Also:
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA Suite
for details about configuring the identity service
■ Oracle Fusion Middleware Security Guide and Oracle Fusion
Middleware Application Security Developer’s Guide for details about
JPS
■ Oracle Identity and Access Management Application Developer's Guide
for details about IDM
■ Oracle Fusion Middleware Administrator's Guide for Oracle Virtual
Directory for details about OVD
Oracle BPEL
Process Manager
Identity Service
Provider Plug-ins
11g IDM
Oracle Custom
LDAP Internet
Directory Provider
XML Database
Database Database
Repository Repository
28.1.5.1.1 Custom User Repository Plug-ins This mode enables you to plug in a
non-LDAP-based user repository by registering a custom identity service provider.
This mode is provided only for backward compatibility. The custom identity service
plug-in must implement the BPMIdentityService interface (see the Javadoc). This
identityservice class name must be registered in
workflow-identity-config.xml.
28-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
See Also:
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA
Suite for configuration instructions
■ SOA_ORACLE_
HOME\bpel\docs\workflow\oracle\tip\pc\services\id
entity for Javadoc on the BPMIdentityService interface
See Also:
■ Section 28.2, "Notifications from Human Workflow" on page 28-20
for specific details about the notification service
■ Chapter 23, "Notifications and the Oracle User Messaging Service"
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA Suite
for instructions on configuring notification service delivery
channels
28-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
See Also:
■ Chapter 33, "Using Oracle BPM Worklist" for details about the rule
configuration and user preference pages
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA Suite
for details on how to designate a user as a group owner
■ Oracle BPEL Process Manager Workflow Services API Reference
located in the SOA_ORACLE_HOME\bpel\docs\workflow
directory
getTaskDisplayInfo can query the URIs for a particular task definition. The
method setTaskDisplayInfo can define new URIs or update existing ones. Only
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 flex field attributes.
Only a user with the workflow.mapping.publicFlexField or
workflow.mapping.protectedFlexField privilege can make updates to payload
mappings for public flex fields. Only a user with the
workflow.mapping.protectedFlexField privilege can make updates to payload
mappings for protected flex fields. Any authenticated user can use the query methods
in this service.
An administrator can create attribute labels for the various flex field attributes. These
attribute labels provide a meaningful label for the attribute (for example, a label
Location may be created for the flex field attribute TextAttribute1). A given flex
field 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 the
worklist application. 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 flex fields are as follows:
■ TextAttribute1 through TextAttribute10
■ FormAttribute1 through FormAttribute5
■ UrlAttribute1 through UrlAttribute5
■ DateAttribute1 through DateAttribute5
■ NumberAttribute1 through NumberAttribute5
Values for protected flex fields are as follows:
■ ProtectedTextAttribute1 through ProtectedTextAttribute10
■ ProtectedFormAttribute1 through ProtectedFormAttribute5
■ ProtectedUrlAttribute1 through ProtectedUrlAttribute5
■ ProtectedDateAttribute1 through ProtectedDateAttribute5
■ ProtectedNumberAttribute1 through ProtectedNumberAttribute5
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.
28-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
Note: Only payload fields that are simple XML types can be
mapped.
The runtime config service also provides methods for querying the dynamic
assignment functions supported by the server.
Table 28–7 describes the methods in the runtime config service. Package
oracle.bpel.services.workflow.runtimeconfig corresponds to the runtime
config service.
See Also:
■ Section 28.3.1, "Dynamic Assignment Functions" on page 28-30 for
additional details
■ Chapter 33, "Using Oracle BPM Worklist" for details about flex
field mapping
■ Oracle BPEL Process Manager Workflow Services API Reference
located in the SOA_ORACLE_HOME\bpel\docs\workflow
directory
Note that 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.
28-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
1
Upload Certificate: One time uploading
of each user's certificate (user action)
upload
Certificate
2
Create Evidence: Create evidence by
digitally signing a task update (user action)
Browser
Task
Certificate + Content
= Signature
3 Human
Validate: Human workflow validates the Workflow
certificate used for evidence creation with
the Certificate Revocation List (CRL)
issued by the Certifying Authorities (CAs)
CA, CRL
4
Nonrepudiation: Prove that the user
generated the signature by creating
the content from the user certificate
and signature
Stored + Stored
Certificate Signature
= Task Content
28.1.10.1 Prerequisites
Prerequisites for using digital signatures and certificates are as follows:
■ Users of the Worklist Application must have certificates
■ The administrator must specify the CAs and corresponding CRL URL whose
certificates must be trusted. Users are expected to upload only certificates issued
by these CAs. This is done by editing the following entry in the
workflow-config.xml file:
<workflowConfigurations>
. . .
. . .
<trustedCAList>
<trustedCA CAName="CN = Intg, OU =AppServ, O =Oracle, C = US"
CAURL="http://www.oracle.com/Integration%20CRL%20Data.crl">
<trustedCA CAName=”CN = Intg1, OU =AppServ, O =Oracle, C = US"
CAURL="http://www.oracleindia.in.com/Integration%20In.crl">
<trustedCA CAName=”CN = Intg2, OU =AppServ, O =Oracle, C = US"
CAURL="http://www.oracle.us.com/integration.crl”>
</trustedCAList>
</workflowConfigurations>
28-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Services
See Also:
■ Section 26.6.8.8, "Specifying a Workflow Signature Policy" on
page 26-62 for details about specifying digital signatures and
digital certificates in the Human Task editor
■ Chapter 31, "Designing Task Display Forms for Human Tasks" for
details about digitally signing a task action in the Oracle BPEL
Worklist Application
28-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Notifications from Human Workflow
See Also: The following guides for details about configuring the
Oracle Application Server Wireless Notification Service:
■ Oracle Notification Service Administrator’s Guide
■ Oracle Notification Service Developer’s Guide
Note: For 11g Release 1, this parameter must be configured from the
Mailer page in Oracle Enterprise Manager Grid Control Console.
Access this page by selecting Administration > Human Workflow
from the SOA Infrastructure menu, then selecting the Mailer tab.
By default, this value is set to NONE, meaning that no notifications are sent. The
possible values for the NotificationMode attribute are:
■ ALL – the e-mail, IM, SMS, and voice channels are configured and notification is
sent through any channel.
■ EMAIL – Only the e-mail channel is configured for sending notification messages.
■ NONE – No channel is configured for sending notification messages. This is the
default setting.
The notifications for a task can be configured during the creation of a task in the
Human Task editor. Notifications can be sent to different types of participants for
different actions.
The actions for which a task notification can be sent are as follows:
■ Assigned — when the task is assigned to users or a group. This action captures the
following task actions — adhoc route, delegate, escalate, information for a task is
submitted, push back, reassign, release, and resume.
■ Task is completed
■ Task is errored
■ Task is expired
■ Information is requested for a task
■ Task outcome is updated
■ Task is suspended
■ Task is resumed
■ Task is withdrawn
■ Task is updated
– Task payload is updated
– Task is updated
– Comments are added
– Attachments are added and updated
■ All Other Actions
– Any action not covered in any of the actions listed above. This includes
acquiring a task.
Notifications can be sent to users involved in the task in various capacities. This
includes:
■ Assignees – the users or groups to whom the task is currently assigned
■ Initiator - the user who created the task
■ Creator – the user who created the task
■ Approvers – the users who have approved the task so far
– This applies to a sequential list of approvers participant type where multiple
users have approved the task and a notification must be sent to all.
■ Owner – the owner of the task
When the task is assigned to a group, each user in the group is sent a notification if no
notification endpoint is available for the group.
See Also:
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA Suite
for details about configuring the notification channel
■ Section 26.6.7, "Specifying Participant Notification Preferences" on
page 26-53 to configure task notifications in the Human Task
editor
■ Chapter 23, "Notifications and the Oracle User Messaging Service"
28-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Notifications from Human Workflow
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 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 worklist application task details page.
The following example demonstrates the use of hwf:getNotificationProperty
and hwf:getTaskResourceBundle together:
concat('Dear ', hwf:getNotificationProperty('recipientDisplay'), ' Task ',
/task:task/task:systemAttributes/task:taskNumber, ' is assigned to you. ',
hwf:getTaskResourceBundleString(/task:task/task:systemAttributes/task:taskId,
'CONGRATULATIONS', hwf:getNotificationProperty('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 function
hwf:getNotificationProperty('locale')
– If a different resource bundle is used, then use the following XPath extension
to retrieve localized messages:
orcl:get-localized-string()
28-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Notifications from Human Workflow
2. If you want to send task attachments with the notification message, choose Select
task attachments with email notifications in the Notification Settings section of
the Human Task editor.
3. Edit the following properties to configure the e-mail driver in the SOA_ORACLE_
HOME\j2ee\oc4j_
soa\application-deployments\nsdriver-email\oc4j-connectors.xm
l file. Ensure that you specify the host names of the incoming and outgoing e-mail
servers, instead of their IP addresses.
<config-property name="ReceiveFolder" value="INBOX"/>
<config-property name="OutgoingDefaultFromAddr"
value="WORKFLOW_MAILER@oracle.com"/>
<config-property name="OutgoingPassword" value=""/>
<config-property name="OutgoingUsername" value=""/>
<config-property name="OutgoingMailServer" value="mail.oracle.com"/>
<config-property name="IncomingMailServer"
value="stmail.oracle.com"/>
<config-property name="IncomingUserIDs"
value="bpmuser3_us,bpmuser2_us"/>
<config-property name="IncomingUserPasswords"
value="Bpeluser1,Bpeluser1"/>
<config-property name="IncomingMailIDs"
value="bpmuser3_us@oracle.com,bpmuser2_us@oracle.com"/>
<config-property name="OutgoingMailServerPort" value="25"/>
<config-property name="OutgoingMailServerTLS" value="false"/>
<config-property name="IncomingMailServerPort" value="143"/>
<config-property name="IncomingMailServerSSL" value="false"/>
4. Edit the following properties to configure the human task mailer in the SOA_
ORACLE_HOME\j2ee\oc4j_
soa\applications\soa-infra\configuration\workflow-notificatio
n-config.xml file. Setting the NotificationMode property to ALL or EMAIL
enables notification.
<HWFMailerConfiguration
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"
NotificationMode="ALL">
<ASNSConfiguration>
<Name>Default</Name>
<EmailFromAddress>WORKFLOW_MAILER@oracle.com</EmailFromAddress>
<EmailReplyToAddress>bpmuser2_us@oracle.com</EmailReplyToAddress>
<EmailRespondToAddress>bpmuser3_us@oracle.com</EmailRespondToAddress>
<IMRespondToAddress>jabber|bpmuser3_
us@omdemo4.oraclemobile.com</IMRespondToAddress>
28-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Notifications from Human Workflow
See Also:
■ Chapter 23, "Notifications and the Oracle User Messaging Service"
for additional details about the reliable notification service
■ Oracle Fusion Middleware Administrator’s Guide for Oracle SOA Suite
for details about administering notification messages
28-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Notifications from Human Workflow
letters are delimiters and can be omitted when the corresponding member is not
used. Examples include PT1004199059S, PT130S, PT2M10S, P1DT2S, -P1Y, or
P1Y2M3DT5H20M30.123S.
The following examples illustrate when reminders are sent.
■ The relativeDate is ASSIGNED, the recurrence is EVERY, and the reminder
duration is PT1D. If the task is assigned at 3/24/2005 10:00 AM, then
reminders are sent at 3/25/2005 10:00 AM, 3/26/2005 10:00 AM,
3/27/2005 10:00 AM, and so on until the user acts on the task.
■ If the relativeDate is EXPIRATION, the recurrence is 2, the reminder
duration is PT1D, and the task expires at 3/26/2005 10:00 AM, then reminders
are sent at 3/24/2005 10:00 AM and 3/25/2005 10:00 AM if the task was
assigned before 3/24/2005 10:00 AM.
■ If the relativeDate is EXPIRATION, the recurrence is 2, the reminder
duration is PT1D, the task expires at 3/26/2005 10:00 AM, and the task was
assigned at 3/24/2005 3:00 PM, then only one reminder is sent at 3/25/2005
10:00 AM.
See Also:
■ Section 26.6.7.4, "Securing Notifications, Making Messages
Actionable, and Sending Attachments" on page 26-56 for
specifying custom notification headers in the Human Task editor.
■ Chapter 40, "User Messaging Preferences"
These functions all check a user’s vacation status. A user that is currently unavailable
is not automatically assigned tasks.
These dynamic assignment functions can be called using the custom XPath functions
in a BPEL process or task definition.
■ wfDynamicUserAssign
■ wfDynamicGroupAssign
These XPath functions must be called with at least two, and optionally more
parameters:
■ The name of the dynamic assignment function being called.
■ The name of the group on which to execute the function (or a list of users or
groups).
■ (Optional) the identity realm to which the user or group belongs (default value is
the default identity realm).
28-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Assignment Service
If your dynamic assignment function selects users, implement the first interface. If it
selects groups, implement the second interface. If it allows the selection of both users
and groups, implement both interfaces.
The two interfaces above both extend the interface
oracle.bpel.services.workflow.assignment.dynamic.IDynamicAssignm
entFunction.
Your Java class should also implement the methods in that interface. These interfaces
as shown in the Javadoc.
The dynamic assignment framework also provides the utility class
oracle.bpel.services.workflow.assignment.dynamic.DynamicAssignme
ntUtils.
This class provides a number of methods that are useful when implementing dynamic
assignment functions.
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 functions.
Two of the functions 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 function can maintain ROUND_ROBIN
counts. The dynamic assignment function 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 function.
■ MOST_PRODUCTIVE — The parameter DEAFULT_TIME_PERIOD specified the
length of time (in days) over which to calculate the user’s productivity. This value
can be overridden when calling the MOST_PRODUCTIVE dynamic assignment
function. Use an XPath function by specifying an alternative value as the third
parameter in the XPath function call.
Note that adding entries to these files for dynamic assignment functions is optional. If
no entry is present in the file, then the name of the function (for example, ROUND_
ROBIN’) is used instead.
28-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Assignment Service
■ 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).
Notes:
■ The assignment service class cannot be stateful because every time
human task services need to call the assignment service, it creates
a new instance.
■ The getAssigneesToRequestForInformation method can
be called multiple times because one of the criteria to show the
request-for-information action is that there are users to request
information. Therefore, this method is called every time the
human task service tries to determine the permitted actions for a
task.
You can implement your own assignment service plug-in that the human task service
invokes during human task execution.
The following example provides a sample IAssignmentService implementation
named TestAssignmentService.java.
/* $Header: TestAssignmentService.java 24-may-2006.18:26:16 rarangas Exp $ */
/* Copyright (c) 2004, 2006, Oracle. All rights reserved. */
/*
DESCRIPTION
Interface IAssignmentService defines the callbacks an assignment
service will implement. The implementation of the IAssignmentService
will be called by the workflow service
PRIVATE CLASSES
<list of private classes defined - with one-line descriptions>
NOTES
<other useful comments, qualifications, etc.>
MODIFIED (MM/DD/YY)
rarangas 01/30/06 -
*/
/**
* @version $Header: IAssignmentService.java 29-jun-2004.21:10:35 rarangas Exp
$
* @author rarangas
* @since release specific (what release of product did this appear in)
*/
package oracle.bpel.services.workflow.test.workflow;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import oracle.bpel.services.workflow.metadata.routingslip.model.*;
import oracle.bpel.services.workflow.metadata.routingslip.model.Participants;
import
oracle.bpel.services.workflow.metadata.routingslip.model.ParticipantsType.*;
import oracle.bpel.services.workflow.task.IAssignmentService;
import oracle.bpel.services.workflow.task.ITaskAssignee;
import oracle.bpel.services.workflow.task.model.Task;
public class TestAssignmentService implements
28-34 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring the Assignment Service
oracle.bpel.services.workflow.task.IAssignmentService {
static int numberOfApprovals = 0;
static String[] users = new String[]{"jstein", "wfaulk", "cdickens"};
public Participants onInitiation(Task task,
Map propertyBag) {
return createParticipant();
}
public Participants onReinitiation(Task task,
Map propertyBag) {
return null;
}
public Participants onOutcomeUpdated(Task task,
Map propertyBag,
String updatedBy,
String outcome) {
return createParticipant();
}
public Participants onAssignmentSkipped(Task task,
Map propertyBag) {
return null;
}
public List getAssigneesToRequestForInformation(Task task,
Map propertyBag) {
List rfiUsers = new ArrayList();
rfiUsers.add("jcooper");
rfiUsers.add("jstein");
rfiUsers.add("wfaulk");
rfiUsers.add("cdickens");
return rfiUsers;
}
public List getReapprovalAssignees(Task task,
Map propertyBag,
ITaskAssignee infoRequestedAssignee) {
List reapprovalUsers = new ArrayList();
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++];
participants.getParticipantOrSequentialParticipantOrAdhoc().
add(participant);
return participants;
}
Note:
■ You cannot create different versions of the assignment service for
use in different BPEL processes unless you change package names
or class names.
■ Java classes and JAR files in the suitcase are not available in the
class path and therefore cannot be used as a deployment model
for the assignment service.
■ The steps must be repeated for each node in a cluster.
28.4 Human Task Service and Identity Service Related XPath Extension
Functions
Oracle BPEL Process Manager provides XPath extension functions for use with the
human task services and IDM. XPath extension functions mimic XPath 2.0 standards.
Table 28–13 lists the supported human task service functions and Table 28–14 lists the
supported identity service functions.
28-36 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Human Task Service and Identity Service Related XPath Extension Functions
Table 28–15 Deprecated Human Task Service and Identity Service Functions
Human Task Function Identity Service Functions
ora:getNumberOfTaskApprovals() ora:getGroupProperty()
ora:getPreviousTaskApprover() ora:getManager()
ora:getTaskAttachmentByIndex() ora:getReportees()
ora:getTaskAttachmentByName() ora:getUserRoles()
ora:getTaskAttachmentContents() ora:getUsersInGroup()
ora:getTaskAttachmentCount() ora:isUserInRole()
ora:lookupGroup()
ora:lookupUser()
ora:getUserProperty()
See Also:
■ Section 26.6.8.4, "Specifying Multilingual Settings" on page 26-59
for details about resource bundles
■ Section 28.1.9.1, "Internationalization of Attribute Labels" on
page 28-15 and Section 28.3.1.3, "Configuring Display Names for
Dynamic Assignment Functions" on page 28-32 for additional
details about the resource property file
WorkflowLabels.properties.
28.7 Summary
This chapter describes how you can integrate systems and services with a human task
into a single end-to-end process flow using Oracle BPEL Process Manager. The
predefined human task participant types are described, as are the components of
human task services—the task service, task routing service, identity service, worklist
service, notification service, and others.
28-38 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
33
33 Using Oracle BPM Worklist
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 contains the following topics:
■ Section 33.1, "Introduction to Oracle BPM Worklist"
■ Section 33.2, "Logging In to Oracle BPM Worklist"
■ Section 33.3, "Customizing the Task List Page"
■ Section 33.4, "Acting on Tasks: The Task Details Page"
■ Section 33.5, "Setting Vacation and Other Rules"
■ Section 33.6, "Using the Worklist Administration Functions"
■ Section 33.7, "Creating Worklist Reports"
■ Section 33.8, "Accessing Oracle BPM Worklist in Local Languages"
■ Section 33.9, "Summary"
See Appendix A, "Building a Custom Worklist Client," for how to use the APIs
exposed by the workflow service.
See Section 28.1.5, "Identity Service," for more information about the predefined roles
that can be associated with worklist user types.
To log in:
1. Go to
http://host_name:port_number/integration/worklistapp
■ host_name is the name of the host on which Oracle BPEL Process Manager is
installed
■ The port_number used at installation (typically 8888) is noted in
SOA_Oracle_Home\install\bpelsetupinfo.text
33-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Logging In to Oracle BPM Worklist
33-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
The filter criteria for a worklist view are saved when you log out and restored when
you log in again.
2. Click Refresh.
33-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
7. Click Search.
The task list page with the tasks filtered according to your criteria appears.
33-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
2. Use the Definition tab of the Create User View dialog, shown in Figure 33–6.
■ Create View or Use Public View—Create your own view or browse for a
public view to copy.
■ Name—Specify a name for your view.
■ Task Type—Browse for a task type or leave the field blank for all types.
■ Match any of these conditions—Select All or Any.
■ Add Filter—Select an item from the list and click Add Filter. For example, if
you select startDate, and click Add Filter, then a calendar and a list including
on, equals, not equals, greater than, less than, and so on appears.
■ Share View—You can grant access to another user to either the definition of
this view, in which case the view conditions are applied to the grantee’s data,
or to the data itself, in which case the grantee can see the grantor’s 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 Proxy
Work Queues.
■ Assignees—Specify the users (grantees) who can share your view.
33-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
3. Use the Display tab of the Create User View dialog, shown in Figure 33–6, to
customize the fields that appear in the view.
3. Use the Definition and Display tabs of the Edit User View dialog to customize the
view, as shown in Figure 33–8 and Figure 33–9, and click OK.
33-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
Reviewers—What happened to the Number of tasks per fetch field? Can users set the
number of tasks that appear in the task display list? (12-11-07/db)
2. Add or remove status states for display, as shown in Figure 33–10, and click OK.
33-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Customizing the Task List Page
2. Provide details in the Create To-Do Task dialog, shown in Figure 33–13, and click
OK.
■ Task Title and Category: Enter anything that is meaningful to you.
■ Percentage Complete: This attribute indicates how much of the task is
completed. 100% sets the attribute as completed.
■ Due Date: The due date doe not trigger an expiration. You can also see
overdue tasks. The start date need not be the current date.
■ Assignee: You can assign yourself or someone else.
33-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Acting on Tasks: The Task Details Page
A user can view a task when associated with the task as one of the following: current
assignee (directly or by group membership), current assignee’s manager, creator,
owner, or a previous actor.
A user’s profile determines his group memberships and roles. The roles determine a
user’s 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.
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. Create a combined list of actions that appear on the preceding lists.
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.
33-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Acting on Tasks: The Task Details Page
■ Acquire
■ Adhoc route
■ Auto release of task
■ Delegate
■ Escalate
■ Information request on task
■ Information submit for task
■ Override routing slip
■ Update outcome and route
■ Push back
■ Reassign
■ Release
■ Renew
■ Resume
■ Skip current assignment
■ Suspend
■ Update
The full history is available from the Show History button. The full history provides a
graphical view of a task flow, as shown in Figure 33–15.
The full history also provides the details of each action on a task, as shown in
Figure 33–16.
The full history provides a snapshot of the task details, as shown in Figure 33–17.
33-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Acting on Tasks: The Task Details Page
Route 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 (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. In the
worklist, you provide the percentage of votes required for approval.
To reassign a task:
1. Click Reassign.
2. Provide an individual user or group name, as shown in Figure 33–18.
A supervisor can always reassign tasks to any of his reportees. Users with the
BPMWorkflowReassign role can assign tasks to any users in the organization.
3. Move the names to the Selected area and click OK.
To request information:
1. Click Request for Info.
2. Provide an individual user or group name, or push back the task to the previous
assignee, as shown in Figure 33–19.
To route a task:
1. Click Route.
2. Select an action and provide a routing option, as shown in Figure 33–20.
33-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Acting on Tasks: The Task Details Page
■ 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, one of the members must
claim the task and act on it.
■ Group Vote: Use this option when multiple users, working in parallel, must
take action simultaneously, 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.
■ 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. Provide user or group names. move the names to the Selected area, and click OK.
4. For a group vote, provide consensus information, as shown in Figure 33–21.
5. Click Route.
33-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Acting on Tasks: The Task Details Page
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 33–23.
See Section 28.1.10, "Digital Signatures and the Evidence Store Service," for more
information.
2. To authorize the creation of a digital signature, click Yes, as shown in Figure 33–24.
33-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Setting Vacation and Other Rules
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.
33-28 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Setting Vacation and Other Rules
■ Take no action—Use this action to prevent other more general rules from
applying. For example, if you want to reassign all your tasks to another user while
you are on vacation, with the exception of loan requests, for which you want no
action taken, then create two rules. The first rule specifies that no action is taken
for loan requests; the second rule specifies that all tasks are reassigned to another
user. The first rule will prevent reassignment for loan requests.
Creating a group rule is similar to creating a user rule, with the addition of a list of the
groups that you (as the logged-in user) manage. Examples of group rules include:
■ Assigning tasks from a particular customer to a member of the group
■ Ensuring an even distribution of task assignments to members of a group by using
round-robin assignment
■ Ensuring that high-priority tasks are routed to the least busy member of a group
Group rules do one of the following actions:
■ Assign to member via—You can specify a criterion to determine which member
of the group gets the assignment. This dynamic assignment criterion can include
round-robin assignment, assignment to the least busy group member, or
assignment to the most productive group member. You can also add your custom
functions for allocating tasks to users in a group.
■ Assign to—As with user rules, you can assign tasks to subordinates or groups you
directly manage. If you have been granted the BPMWorkflowReassign role, then
you can reassign tasks to any user or group (outside your management hierarchy).
■ Take no action—As with user rules, you can create a rule with a condition that
prevents a more generic rule from being executed.
9. Click Save.
The new vacation rule appears under the My Rules node.
33-30 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Setting Vacation and Other Rules
■ Select the actions to be taken (or none) (Reassign to, Delegate to, Set outcome
to, or Take no action), as shown in Figure 33–29.
33-32 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the Worklist Administration Functions
4. Click a user rules node, or click a group name (for a group rule).
5. Click the Add icon to create a rule.
6. Provide rule information, as shown in Figure 33–32, and click Save.
See Section 33.5.1, "How to Set Vacation and Other Rules," for details about the
fields on the Other Rules dialog.
■ 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 .jgp 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
33-34 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the Worklist Administration Functions
4. Click Save.
To create labels:
To create a flex field mapping, an administrator first defines a semantic label, which
provides a more meaningful display name for the flex field attribute. Click the Add
icon (+) to use the Create Label dialog, shown in Figure 33–34.
As the figure 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 end result is that the value of the Text attribute is
stored in the TextAttribute3 column, and labelName is the column label displayed in
the user’s 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:
■ Only simple type payload attributes can be mapped. Mapping specific simple
types within a complex type is not supported.
■ A flex field (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.
33-36 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Using the Worklist Administration Functions
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 33–36.
33-38 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Worklist Reports
To create a report:
1. Click the Reports link.
Figure 33–38 Report Display—Table Format, Bar Chart Format, and Report Inputs
33-40 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Worklist Reports
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 more
than one type 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.
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.
33-42 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Accessing Oracle BPM Worklist in Local Languages
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 states—assigned and completed—are differentiated by
color.
However, this can be changed to a custom resource bundle by setting the appropriate
application preference. See Section 33.6.2, "How to Set the Worklist Display
(Application Preferences)," for more information.
For task attribute names, flex field 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 28, "Human Task 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 28, "Human Task Services," for
information on how to specify message bundles so that custom actions and task titles
are displayed in the preferred language.
Table 33–5 Languages and Java Locales Supported by Oracle BPM Worklist
Language Java Locale
English (en)
English (United States) (en_US)
German (de)
Spanish (International) (es)
Spanish (Spain) (es_ES)
French (fr)
French (Canada) (fr_CA)
Italian (it)
Japanese (ja)
Korean (ko)
Portuguese (pt)
Portuguese (Brazil) (pt_BR)
Chinese (Simplified) (zh_CN)
Chinese (Traditional) (zh_TW)
33-44 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Summary
2. Change the string in bold to set the user's preferred time zone.
<timeZone>America/Los_Angeles</timeZone>
33.9 Summary
This chapter describes how to access tasks, view task details, and perform actions on
the tasks in the sample Oracle BPM Worklist. It also discusses how you can create and
share custom views, manage user and group rules, customize task display settings,
and perform administrative tasks such as flex field mapping and application
customization.
33-46 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
30 30
This chapter describes Approval Management Service (AMX) integration with the
human task services of Oracle SOA Suite. AMX replaces the E-Business Suite (EBS)
R12 Approvals Management Engine (AME) and the PeopleSoft 8.48 Approval
Workflow Engine (AWE) of previous releases. AMX provides a unified method for
defining and controlling approval tasks. You define the approval task in the Human
Task Editor of Oracle JDeveloper, and associate the task with a BPEL process.
This chapter contains the following topics:
■ Section 30.1, "Introduction to AMX"
■ Section 30.2, "Designing AMX Approval Tasks in Oracle JDeveloper"
Human Workflow
Service
Create / Maintain
Approval Groups
Task
AM Business Analyst Persistency
Service
View / Act on
User Task
.rules
End User File
AM Business Analyst
See Also:
■ Chapter 26, "Designing Human Tasks"
■ Chapter 28, "Human Task Services"
30-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to AMX
■ AMX setup user interface — Provides a graphical user interface for defining and
modifying approval taxonomy and rules.
■ Worklist application — Provides a Web interface that enables users to act on their
assigned tasks.
■ AMX monitor — Provides the ability to monitor current flows and view history
and audit approvals for previous transactions.
■ AMX admin — Provides the administrator with a graphical user interface to
configure the approval process and monitor and control the initiated approval
process.
■ AMX test workbench — Provides methods to run simulation tests for specific
approval flows.
■ Oracle JDeveloper and AMX setup graphical components — Provide the design
time user interfaces for creating approval processes.
30.1.2.4 Chain
A chain is a subpath of an approval list builder. This is used in a dual chain approver
list builder and an approval group list builder. In the dual chain approver list builder,
the approval goes up two separate job level hierarchies. In the approval group list
builder, if multiple groups are to be included for a stage, then each group is processed
as a separate chain. These chains are always processed in parallel.
For example, one variable dictates whether the approver list generation is static or
dynamic. If static, AMX must only evaluate the rules to determine the applicable
approval list builders for each stage and use them to build the approver list once.
The following sections describe the available configuration variables:
■ Section 30.1.2.5.1, "Administrative Configurations"
■ Section 30.1.2.5.2, "Approval Configurations"
30-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to AMX
30-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to AMX
Hierarchy Dimensions
See Also: Section 26.6, "Creating the Human Task Definition with
the Human Task Editor"
Approval list builder usage defines how an approval list builder is used for a stage
within an approval service. It defines the following:
■ Preference — Specifies the order in which to process the list builder for a stage
■ Default voting regime — Specifies the voting behavior to follow
30.1.2.10 Notification
Notification refers to the e-mail, short message service (SMS), or instant message (IM)
channel that notifies a user or role that a certain task requires their attention.
See Also:
■ Chapter 23, "Notifications and the Oracle User Messaging Service"
■ Section 26.6.7, "Specifying Participant Notification Preferences"
■ Section 28.2, "Notifications from Human Workflow"
Approver List
Header Approval
Approval Group
List Builder
Job Level
Chain 2 List Builder
Chain 1
Payment
Approver
Line Receipt
Approval Verification
30-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to AMX
30.1.2.13 Stages
A stage is a specific approval point associated with a dimension. However, a
dimension can be associated with multiple approval stages. A set of rules or approval
policies are associated with each stage. A separate list of approvers is generated for
each stage, based on the rules applicable and the approver list builders defined in the
rule.
For example, an expense report can have the following stages defined:
■ Header approval stage associated with the header dimension
■ Line approval stage associated with the lines dimension
■ Receipt verification stage associated with the header dimension
■ Payment stage associated with the header dimension
Stages can be modeled to be serial or parallel with respect to each other. This is
performed while defining the approval structure. Figure 30–4 provides an overview.
Dimensions Stage
Receipt Verification
Payment
Cost Centers
See Also:
■ Section 30.2, "Designing AMX Approval Tasks in Oracle
JDeveloper"
■ Section 26.6, "Creating the Human Task Definition with the
Human Task Editor"
This type describes the specific action being performed on the approver list. The policy
types supported are:
■ List creation
■ List modification
■ Approver substitution
30-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction to AMX
30.1.3.3 Action
Based on the approval policy type, different information must be defined for each
action. These are also known as the action configurations.
List creation policy instructs AMX to create the approver list based on the following
criteria:
■ Approver list builder to be used
■ Stopping rule
■ Response type
■ All members included in the list
■ Voting regime for the rule (only for the approval group list builder)
List modification policy instructs AMX to modify the approver list based on the
following criteria:
■ Action (for extend list or truncate list)
■ List builder to use (for extend list)
■ Stopping rule for the action (for extend list)
Approver substitution policy instructs AMX to replace one approver in the approver
list with another (if present in the list).
30.1.3.4 Conditions
Conditions in Oracle business rules are Boolean expressions that compare a term to
other terms or constant values. Conditions can also be created as standalone entities
for re-use in other rules. The operators used in conditions are defined in metadata and
can be extended by application developers.
30.1.3.5 Criteria
The criteria is the set of conditions under which a rule is applicable. If all the
conditions in a routing policy are true, then that routing policy is active for the
transaction.
30.1.3.6 Priority
Rule arbitration is carried out by means of prioritizing rules. This is performed in
Oracle business rules.
provides an execution model for rule evaluation, depending on which items from the
rule context are used to define a given rule.
30.1.3.9 Terms
Terms are semantic units of information relevant to a business user. Most terms
originate from member fields of business objects, such as the first name attribute of a
person.
The decision service does not maintain its own library of terms. Instead, the decision
service uses the existing Siebel Business Analytics (SBA) and BC4J layers. A term is a
data element from the BC4J or SBA layers that has been designated for use either in
one or more contexts, rules, conditions, or actions.
The decision service uses the Oracle Fusion Middleware BC4J as a data source. The
Oracle Fusion Middleware BC4J stack is used for accessing the intratransactional and
transient data present during the online application runtime. BC4J is also used as a
source of persistent data, initially through the BC4J APIs. Once SBA delivers sufficient
BC4J integrations, offline BC4J entity objects (EOs) are accessed through the SBA layer
instead of directly through the BC4J APIs. This allows for more efficient correlation to
other data sources.
30-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
Note: This section only describes how to create and configure the
composite approver participant type. The composite approver
participant type enables you to integrate the AMX approval task with
a human task. For instructions on creating and designing all parts of a
human task, see Section 26.6, "Creating the Human Task Definition
with the Human Task Editor."
Notes:
■ VO introspection is not supported with Applications Drop 4.
■ It is important to define as many VO attributes as possible so they
do not require extensions.
■ You must define the payload to pass to the human task. Table 30–4 describes the
required contents of the payload.
Field Description
Type Select Composite Approver. This refreshes the window to display
new fields.
View Object Definition Specify the complete path for the defined VO (for example,
oracle.tip.tools.ide.workflow.editor.purchaseOrderVO can be
specified).
Note: Be aware of the following issues for Applications Drop 4:
■ The Browse icon is disabled.
■ The VOs are not used by AMX for validation.
List Substitution Policy Note: For Applications Drop 4, The Create icon is disabled and list
substitution policies are not supported.
List substitution type policies enable you to substitute approvers on
the list with other approvers. For example, you can substitute one
supervisor in the approval hierarchy with a second supervisor if the
first approver is on vacation.
List Modification Policy Note: For Applications Drop 4, The Create icon is disabled and list
modification policies are not supported.
List modification type policies allow for the modification of the
approver list generated by the applicable policies calculated using
the list creation rules. For example, you can extend the approval
hierarchy to additional levels or truncate the approval hierarchy
after a specific approver has acted.
When complete, the General section of the Add Participant Type page appears as
follows:
30-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
Field Description
Dimension Enter a dimension name (for example, HeaderDimension can be
entered).
View Link Enter the complete path of the view link (VL) (for example,
purchaseOrderVO can be specified). This VL should be linked
to the main VO. There must be only one main VO. The other
dimensions are linked to the main object by VLs.
Note: In Applications Drop 4, the VO/VL information is not used
at runtime, so no validation is performed here.
7. Click OK.
You are returned to the Add Participant Type window. The Dimensions section
displays the following information.
30-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
2. Click the Create icon in the Stages section of the Add Participant Type window.
Field Description
Stage Enter a name (for example, HeaderStage can be entered).
Dimension Select a dimension with which to associate this stage. You created
this dimension in Section 30.2.3, "Create a Dimension."
Continuous Evaluation Note: This feature is not supported in Applications Drop 4.
This field is for specifying if the routing slip interpreter must
return to the task rule service for the next set of approvers at
every possible point.
■ True — Returns to ask for the routing slip of the next set of
approvers
■ False — Requests a full routing slip only once
5. Click OK.
6. Select the stage (for example, HeaderStage can be selected).
7. Click the Create icon in the Stages section again.
8. Select Add Parallel Stage from the dropdown list. This creates a stage in parallel
with the one created in Step 4.
Field Description
Stage Enter a name (for example, CostCenter can be entered).
Dimension Select a dimension with which to associate this stage.
Continuous Evaluation This feature is not supported for Applications Drop 4.
11. Select a stage under which to create a sequential stage. (for example, HeaderStage
can be selected).
12. Click the Create icon in the Stages section.
13. Select Add Sequential Stage from the dropdown list. This creates a new stage
immediately below the stage selected in Step 11.
The Add Sequential Stage window appears.
30-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
Note the ^ and v icons above the stages. These icons enable you to change the
order of stages. For this example, assume you select the lower stage
(ReceiptVerification) and click the ^ icon. This moves the lower stage
(ReceiptVerification) above the upper stage (HeaderStage). As another example,
assume you select the new upper stage (ReceiptVerification) and click the v icon.
This moves ReceiptVerification back below HeaderStage.
2. Change the order of the approver list builders from parallel to serial. For this
example, assume you select the Job Level and Position approval list builders and
click the v icon to move both builders below the Supervisory, Approval Group,
and Dual Chain approval list builders. This configures the list builders to be
executed in serial order, instead of parallel.
30-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
Note: Use of the Create icon of the Approval Policy field is not
supported for Applications Drop 4. In a future Applications Drop, this
link will provide access to Oracle business rules.
2. Select and delete additional approval list builders as necessary (for example, the
Approval Group and Job Level approval list builders can be selected).
3. Click OK.
The Supervisory List Builder window appears. This enables you to specify the
approval policy actions.
Field Description
Voting Regime Select a voting behavior to follow. Voting is a method of decision
making that enables a group to determine its opinion. For
example, Minimum percentage of Approvers can be selected.
This selection refreshes the window to display a second list, from
which 39 is selected.
This selection enables the task to be computed as soon as the
minimum percentage is met. For example, assume four users are
assigned to act on a task, the default outcome is APPROVE, and
the minimum percentage is set at 50. If the first two users approve
the task, the third and fourth users do not need to act on the task,
since the consensus percentage value has already been satisfied.
The Voting Regime list also offers additional selections:
■ Consensus — Select to process an approval in parallel and
require all participants to respond.
■ Serial — Select to force the approvers to act serially in the
order defined in the approver list. For example, assume users
Joe and Mike both have sequence 1. If user Joe comes first,
that user is notified prior to user Mike.
■ First Responder Wins — Select to process an approval in
parallel but only take the first response.
30-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
Field Description
Constraint Type Select a voting constraint type. The values that appear are based
upon the type of approval list builder selected.
■ At Most or At Least (displays for Supervisory, Job Level,
Dual Chain, and Position)
When climbing a hierarchy with missing levels, this selection
decides whether to stop below or above the level in the rule.
■ Absolute or Relative (displays for Job Level, Dual Chain,
and Position)
Select to use absolute or relative levels.
■ Level (displays for Supervisory, Job Level, Dual Chain, and
Position)
Enter a positive integer to indicate the number of steps.
■ Chain Number (displays for Dual Chain)
Specify the chain number.
■ Group Name (displays for Approval Group)
The approval group name.
Constraint Level Select a voting constraint level.
Response Type Select a response type.
See Also: Section 30.1.3.7, "Response Type" for descriptions of
available values
Starting Point This field is left blank for this example. This field enables you to
build an XPath expression for passing data by clicking the XPath
Expression Builder icon to the right of this field.
Top Approver This field is left blank for this example. This field specifies the top
level participant in the approval hierarchy. You do not go past the
top approver in a hierarchy.
3. Click OK.
The Supervisory List Builder window shown in Step 2 contains fields for Voting
Regime, Starting Point, Top Approver, and so on. The fields that display can
differ based on the approval list builder selected. Table 30–5 identifies and
describes the fields that appear for all five approval list builders.
30-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Designing AMX Approval Tasks in Oracle JDeveloper
AMX task approval configuration is now complete. Proceed with the remaining steps
of human task design such as defining notification methods and associating the
human task with a BPEL process by following the procedures in Section 26.6,
"Creating the Human Task Definition with the Human Task Editor."
30-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
31
31 Human Task and Microsoft Excel Integration
1.
2.
1.
31-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Part V Oracle Business Activity Monitoring
Beta Draft
Beta Draft
32
32 Creating Data Objects
This chapter contains the information needed to create and manage data objects,
including assigning permissions, managing folders, creating security filters, and
adding dimensions and hierarchies.
This chapter contains the following topics:
■ Section 32.1, "Defining Data Objects"
■ Section 32.2, "Adding Permissions on Data Objects"
■ Section 32.3, "Viewing Existing Data Objects"
■ Section 32.4, "Using Data Object Folders"
■ Section 32.5, "Adding Security Filters"
■ Section 32.6, "Adding Dimensions"
■ Section 32.7, "Renaming and Moving Data Objects"
■ Section 32.8, "Adding Indexes"
■ Section 32.9, "Clearing Data Objects"
■ Section 32.10, "Deleting Data Objects"
■ Section 32.11, "System Data Objects"
32-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Defining Data Objects
Not supported:
Table 1 > Lookup > Table 2 > Lookup > Table 3
32-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Adding Permissions on Data Objects
32-6 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Viewing Existing Data Objects
32-8 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Using Data Object Folders
View. Displays the general properties of this folder such as name, date created,
date last modified, user who last modified it. View is selected when you first click
a folder.
Create subfolder. Creates another folder within the selected folder.
Delete. Removes the selected folder and all the data objects it contains.
Rename. Changes the folder name.
Move. Moves this folder to a new location, for example, as a subfolder under
another folder.
Permissions. Sets permissions on this folder.
Create Data Object. Creates a data object in this folder.
32-10 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Adding Security Filters
Login Region ID
DomainName\jsmith 1
DomainName\jsmith 2
DomainName\bwright 1
DomainName\breid 2
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
view data for the same region. On the other hand, the jsmith account is set up to view
data in both region 1 and 2.
Dimension Hierarchy
Sales Category
Brand
Description
32-12 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Adding Dimensions
3. Select Dimensions.
4. Click Add a new dimension.
5. Enter a dimension name.
6. Enter a description for the dimension.
7. Select the field names that you want to include in the dimension. An example is
Sales, Category, Brand, and Description.
The field names are moved from the Data Objects Fields list to the Dimension
Fields list to show that they are selected.
8. Click Save.
9. Click Continue.
The new dimension is listed. You must still define a hierarchy for the fields.
10. Click Add new hierarchy.
13. Select the field names that you want to define as attributes for the dimension. An
example is 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 fields is the order that they are listed in the Hierarchy Field
list. Arrange the more general grouping field at the top of the Hierarchy Fields list
and the most granular field at the bottom of the Hierarchy Fields list.
14. Click Save.
32-14 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
System Data Objects
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.
32-16 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
33
33 Using External Data Sources
This chapter contain the information needed to create and manage External Data
Sources.
This chapter contains the following topics:
■ Section 33.1, "Introducing External Data Sources"
■ Section 33.2, "Listing External Data Sources"
■ Section 33.3, "Defining External Data Sources"
■ Section 33.4, "Editing External Data Sources"
■ Section 33.5, "Deleting External Data Sources"
■ Section 33.6, "External Data Source Example"
2. Click Create.
3. Enter myDataSource in the External Data Source Name field.
4. Enter My Example External Data Source in the Description field.
5. Enter Microsoft ODBC for Oracle in the Driver field.
33-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
External Data Source Example
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. Enter server=net_service_name in the Connection string/URL.
This entry needs to be a Net Service Name defined in your tnsnames.ora file.
8. Click Save.
9. Click Continue.
The External Data Source information is displayed on the screen.
Keep default settings for field attributes not specified in the table.
11. Click Create Data Object.
33-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
34
34 Creating Alerts
To create a rule:
1. Select Alerts in the Architect function list.
In Active Studio, select the Alerts tab.
2. Click Create A New Alert.
The Rule Creation and Edit dialog displays.
34.3.1 Events
Events launch the rule and trigger the action. Each rule contains only one event.
34-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Using Alert Rule Options
34.3.2 Conditions
Conditions are optional settings for constraining the period of time in which the alert
is fired. You can select any number of conditions.
34.3.3 Actions
Actions are the results of a launched alert. You can select any number of actions.
Send a report via email and escalate to another user after a specific amount of
time
Create a message and send to a recipient. Select a secondary recipient to receive the
message if the first recipient does not respond within the specified time period.
Launch a rule
Select a dependent rule that includes the when this rule is launched event. For an
example of constructing a dependent rule see Section 34.6, "Creating Complex Alerts."
34-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Creating Alert Rules With Messages
satisfied many times within five seconds, users would not want alerting more than
once in five seconds.
Special fields are listed in the box in the lower left corner of the Alert Message
dialog. The special fields listed change when reports are selected on the right side
of the dialog.
To insert a special field into the message:
a. Select a special field from the list.
b. Click Insert into subject or Insert into text.
You can insert multiple values of the same type, for example, multiple links to
different reports.
■ Send Report Name inserts name of selected report.
■ Send Report Owner inserts owner name of selected report.
■ Send Report Link inserts link to selected report.
■ Changed Report Name inserts name of the changed report.
■ Changed Report Owner inserts Owner Name Of Changed Report.
■ Target User inserts user name of message recipient.
■ Date/Time Sent inserts date and time of message sent.
7. Click OK.
34-6 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Activating Alerts
Note: Active Studio URLs used in alerts and report links contain a
virtual directory using the product build number for caching and
performance purposes. This directory must be included in links, and it
is not recommended to edit these links. Links created with a previous
version of Oracle BAM will not work after a product upgrade. The
alert will require editing or the report shortcut will need to be copied
again.
34-8 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Parameterized Alerts
http://SERVER1/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.
34-10 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
35
35 Using the Oracle BAM Data Control
The Oracle BAM data control is a binding component in the Oracle ADF Model. This
chapter provides information about creating and using the Oracle BAM data control.
For more comprehensive information about using Oracle ADF Model data binding,
refer to Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
This chapter contains the following topics:
■ Section 35.1, "Introduction to the Oracle BAM Data Control"
■ Section 35.2, "Creating Oracle BAM Server Connections"
■ Section 35.3, "Creating Projects That Can Use Oracle BAM Data Controls"
■ Section 35.4, "Exposing Oracle BAM with Oracle ADF Data Controls"
■ Section 35.5, "Creating Oracle BAM Data Control Queries"
■ Section 35.6, "Using Oracle BAM Data Controls in ADF Pages"
Field Description
BAM Web Host Enter the name of the host on which the BAM report server and
Web server are installed. In most cases, the BAM Web host and
Oracle BAM Server host are the same.
BAM Server Host Enter the name of the host on which the Oracle BAM Server is
installed.
User Name Enter the Oracle BAM Server user name (typically bamadmin).
Password Enter the password of the user name.
HTTP Port Enter the port number or accept the default value of 8888. This is
the HTTP port for the BAM Web host.
RMI Port Enter the port number or accept the default value of 9085. The
RMI port is for the BAM report cache, which is part of the Oracle
BAM Server.
Use HTTPS Select this check box if you want to use secure HTTP (HTTPS) to
connect to the Oracle BAM Server during design time.
Otherwise, HTTP is used.
7. Click Next.
8. Test the connection by clicking Test Connection. If the connection was successful,
the following message appears:
Passed.
9. Click Finish.
35.2.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 will 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:
35-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Creating Oracle BAM Server Connections
■ Create a new Oracle BAM connection with the same name as the connection that is
referred to by the data control. See Section 35.2, "Creating Oracle BAM Server
Connections" for more information.
■ Update the current project’s DataControls.dcx file with the name of a new or
existing Oracle BAM connection. See Section 35.2.1, "How to Modify Oracle BAM
Data Control Connections to Oracle BAM Servers" for more information.
35.2.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.
Each project in a JBuilder 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 wish 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. Save and close the DataControls.dcx file.
35.3 Creating Projects That Can Use Oracle BAM Data Controls
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. These technologies must be part of the project; either they are added when the
application is created on an ADF-ready template, or the appropriate tag libraries can
be added to the project later.
Note that an Oracle BAM data control can still be used by view components that do
not support active data.
The Oracle BAM data control requires that the project contain the ADF Faces and ADF
Pages Flow technologies. The Fusion Web Application (ADF) template in JDeveloper
contains these technologies.
However, if you are planning to add an Oracle BAM data control to a project and
application that was not created using an ADF template, you can add the ADF Data
Visualization and ADF Faces Components tag libraries to the project.
To add ADF Data Visualization and ADF Faces Components tag libraries to a
project:
1. In the Application Navigator, right-click the project node and select Project
Properties.
2. In the Project Properties dialog, select JSP Tag Libraries, and click Add.
3. Select both ADF Data Visualization and ADF Faces Components tag libraries,
and click OK.
4. Click OK to close the Project Properties dialog.
35-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Exposing Oracle BAM with Oracle ADF Data Controls
data objects. Data controls consist of a number of XML metadata files that define the
capabilities of the service that the bindings can work with at runtime.
See Chapter 32, "Creating Data Objects" for information about creating Oracle BAM
data objects. For information about creating a connection to your Oracle BAM
instance, see Section 35.2, "Creating Oracle BAM Server Connections."
3. Complete the BAM Data Control wizard to create the data control query.
See Section 35.5, "Creating Oracle BAM Data Control Queries" for more
information.
35.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:
■ Data control definition file (DataControls.dcx)
■ Structure definition files for every structured object that this service exposes
■ Design time XML files
JDeveloper also adds the icons to the Data Controls panel that you can use to create
data bound UI components.
35.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
application’s business services and exposes all the queries that are available for
binding to UI components. The panel is a direct representation of the metadata XML
files created when creating a data control. By editing the data control, you can change
the elements displayed in the panel.
35-6 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Creating Oracle BAM Data Control Queries
To create parameters:
1. Click Add to add a parameter.
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
enter a value in the field.
■ ALL
Returns rows containing all values.
■ NULL
Returns rows containing null values
■ BLANK
Returns rows containing blank string values.
35-8 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Creating Oracle BAM Data Control Queries
■ 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 35.5.5.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 35.5.5.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 35.5.5.4,
"Using Active Now" for more information.
5. Click OK to add the entry to the filter expression.
35.5.5.3.1 Comparison With a Value If you select Value, do one of the following:
■ 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.
35.5.5.3.2 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.
35-10 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Creating Oracle BAM Data Control Queries
To specify a group:
1. In the Groups page of the Create BAM Data Control wizard, select one or more
fields in the Group Fields list.
To group by numeric fields, first select Show Numeric Fields at the bottom of the
list.
2. To change the display order in which the groups will be 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 35.5.6.1, "How to Configure Time Groups and Time Series" for more
information.
35-12 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Using Oracle BAM Data Controls in ADF Pages
5. Enter a quantity of the time unit to group by. For example, entering a 2 next to the
Month time unit will display the groups in two month increments (January and
February will be grouped as one data point on the chart).
6. Click Next or Finish.
35-14 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
36
36 Creating Enterprise Message Sources
This chapter contain the information needed to create and manage oracle BAM
enterprise message sources.
This chapter contains the following topics:
■ Section 36.1, "Introducing Enterprise Message Sources"
■ Section 36.2, "Listing Enterprise Message Sources"
■ Section 36.3, "Defining Enterprise Message Sources"
■ Section 36.4, "Editing Enterprise Message Sources"
■ Section 36.5, "Copying Enterprise Message Sources"
■ Section 36.6, "Deleting Enterprise Message Sources"
■ Pre-processing
■ Message specification
■ Column value (Column values can be provided either as elements or attributes in
the XML payload.)
36-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Defining Enterprise Message Sources
36-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Defining Enterprise Message Sources
■ Handling of XML that, while not expressing hierarchical data, does contain
needed data at more than one level 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.
■ Handling changes to message formats without affecting Plans. If a complex
message-processing Plan exists and the format of the messages, or the data in
them, is changed slightly, the XSL transformation could compensate for this
change so that changes to the Plan are not required.
To specify an XSL transformation:
1. In an enterprise message source that you are defining or editing, select one of the
XML formatting options in the Formatting column.
2. Click Advanced formatting options.
The Advanced Formatting dialog displays.
3. Type or paste the XSL code for the transformation for the XML in this field. You
might want to write the XSL in another editing tool and then copy and paste the
code into this dialog.
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 will not be
displayed if you close and open this dialog.
5. Click Verify transformation syntax to check the XSL syntax.
6. Click Test transformation on sample XML to test your transformation.
The results are displayed in the field underneath the links. If any errors are found
in the XSL syntax, the sample XML syntax, or during the transformation, the error
text is shown in this field.
<item>
<description>Fuel pump</description>
<price>128.95</price>
<quantity>1</quantity>
</item>
<item>
<description>Fuel filter</description>
<price>12.95</price>
<quantity>1</quantity>
</item>
</order>
The generated records for the preceding message might look like the following:
36-6 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Defining Enterprise Message Sources
The following text shows the transformed XML produced for the previous example:
<PhoenixDebtOrder>
<Flat ord_id="1847494630" rgn_id="0"
last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0"
iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0"
identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827"
canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558620"
ioi_prd_id="1847494611" ioi_size="4770000000" ioi_px="14.123512"/>
<Flat ord_id="1847494630" rgn_id="0"
last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0"
iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0"
identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827"
canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558621"
ioi_prd_id="1847494611" ioi_size="5540000000" ioi_px="15.252500"/>
<Flat ord_id="1847494630" rgn_id="0"
last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0"
iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0"
identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827"
canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558619"
ioi_prd_id="1847494611" ioi_size="3330000000" ioi_px="12.500000"/>
<Flat ord_id="1847494630" rgn_id="0"
last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0"
iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0"
identity_nm="" prd_id="1847494612" price_basis="spread" ioi_ccy_id="1847483827"
canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558620"
ioi_prd_id="1847494612" ioi_size="5880000000" ioi_px="14.124512"/>
<Flat ord_id="1847494630" rgn_id="0"
last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0"
iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0"
identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827"
canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558621"
ioi_prd_id="1847494612" ioi_size="4430000000" ioi_px="12.252500"/>
</PhoenixDebtOrder>
36-8 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Defining Enterprise Message Sources
<xsl:template match="PhoenixDebtOrder">
<xsl:choose>
<xsl:when test="PhoenixDebtOrderProduct">
<xsl:apply-templates select="PhoenixDebtOrderProduct"/>
</xsl:when>
<xsl:otherwise>
<!-- There are no products -->
<!-- Generate a tag with only the attributes from the root
PhoenixDebtOrder tag -->
<Flat>
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="PhoenixDebtOrderProduct">
<xsl:choose>
<xsl:when test="PhoenixDebtOrderIOI">
<xsl:apply-templates select="PhoenixDebtOrderIOI"/>
</xsl:when>
<xsl:otherwise>
<!-- This product has no IOIs -->
<!-- Generate a tag with only the attributes from the root
PhoenixDebtOrder tag and the parent PhoenixDebtOrderProductTag -->
<Flat>
<xsl:for-each select="../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
<!-- Add a linebreak to the output XML, just for appearance -->
<xsl:text disable-output-escaping="yes"> </xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="PhoenixDebtOrderIOI">
<Flat>
<!-- Root PhoenixDebtOrder attributes -->
<xsl:for-each select="../../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<!-- PhoenixDebtOrderProduct attributes -->
<xsl:for-each select="../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<!-- PhoenixDebtOrderIOI attributes -->
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
<!-- Add a linebreak to the output XML, just for appearance -->
<xsl:text disable-output-escaping="yes"> </xsl:text>
</xsl:template>
</xsl:stylesheet>
36-10 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
37
37 Using ICommand
This chapter provides usage and reference material for the ICommand command-line
utility and web service. It contains the following topics:
■ Section 37.1, "Introducing ICommand"
■ Section 37.2, "Executing ICommand"
■ Section 37.3, "General Command and Option Syntax"
■ Section 37.4, "Object Name Syntax"
■ Section 37.5, "Command-line-only Parameters"
■ Section 37.7, "Summary of Individual Commands"
■ Section 37.8, "Detailed Command Descriptions"
■ Section 37.9, "Format of Command File"
■ Section 37.10, "Format of Log File"
■ Section 37.11, "Sample Export File"
■ Section 37.12, "Regular Expressions"
■ Section 37.13, "Using ICommand Web Service"
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 must contain
spaces or other special characters, it may be enclosed in double quotes. For example
icommand -cmd export -name "/Samples/Call center" -type dataobject -file
C:\Callcenter.xml
It is required to use quotes around report names and file names that contain spaces
and other special characters.
For some parameters, the value may be omitted.
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.
General rules
When specified on a command line, if the name contains spaces or characters that have
special meaning to DOS or Unix, the name must be quoted according to the rules for
command lines.
When specified in an XML command file, if the name contains characters that have
special meaning within XML, the standard XML escaping must be used.
Data Objects
If the Data Object is not at the root, the full path name must be given, as in the
following example:
/My Folder/My Subfolder/My Data Object
If the Data Object is at the root, the leading slash (/) is optional. The following two
examples are equivalent:
/My Data Object
My Data Object
37-2 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Command-line-only Parameters
Reports
The full path name must be specified as in the following examples.
For shared reports:
"/public/Report/Subfolder1/My Report"
For private reports the /private:user_name/ prefix may be omitted if the user
running ICommand is the user that owns the report.
The path information without the public or private prefix is saved in the export
file.
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.
Optional parameter that specifies the name of the file that contains commands to
be processed. Since 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
Optional parameter that specifies the domain name to use to login to the Active
Data Cache (the name of the machine on which the Active Data Cache server is
running).
If this parameter is omitted, main is used, which means the server information
will be obtained from the ADCServerName key in the ICommand.exe.config file.
If the reserved value ADCInProcServer is used, then ICommand will directly
access the Active Data Cache database (which must be local on the same machine
on which ICommand is running) rather than contacting the Active Data Cache
server. This option should be used only when the Active Data Cache server is not
running; otherwise corruption of the database could occur. The information about
the location and structure of the Active Data Cache database is obtained from
various keys in the ICommand.exe.config file.
■ Logfile
-logfile filename
Optional parameter that specifies the name of the file to which results and errors
are logged. If the file does not exist, it will be created. If the file does exist, any
contents will be overwritten. Since 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 will be output to the console.
■ Logmode
-logmode mode
■ Password
-password password
37-4 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Summary of Individual Commands
The Oracle BAM version installed on the remote machine should be same as the
Oracle BAM server version (that is, both servers should be from the same label).
37.8.1 Export
Exports information about one or more objects in the Active Data Cache to an XML
file. See Section 37.11, "Sample Export File" for an example of an exported Data Object.
37-6 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Detailed Command Descriptions
37-8 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Detailed Command Descriptions
Note that the type parameter was not included in this example. By default
dataobject is assigned to type if it is not specified.
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.
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
Note that in the name parameter the name of the Data Object is specified rather than
the name of the security filter.
37.8.2 Import
Imports the information from an XML file to an object in the Active Data Cache. The
object may be created, replaced, or updated.
If the object does not exist, it will be created if possible. For Data Objects, the input file
must contain layout information in order to create the Data Object, and if the file
contains no content information, then an empty Data Object will be created.
37-10 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Detailed Command Descriptions
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.
37-12 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Detailed Command Descriptions
37.8.3 Delete
Deletes an item from the Active Data Cache.
37.8.4 Rename
Renames an item in the Active Data Cache.
37-14 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Format of Command File
37.8.5 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 Folders, all contents of the Folder are deleted.
■ For Distribution Lists, all members (users) are removed from the distribution list.
Within the root tag is a tag for every command to be executed. The tag name is the
command name, and the parameters for the command are attributes.
Sample command file:
<?xml version="1.0" encoding="utf-8"?>
<OracleBAMCommands ContinueOnError="1">
<Export name="Samples/Media Sales" file="MediaSales.xml" contents="0" />
<Rename name="Samples/Call Center" newname="Call Centre" />
<Delete type="EMS" name="WebLog" />
<Delete type="EMS" name="WebLog2" />
</OracleBAMCommands>
37-16 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Format of Log File
Sample Output:
<ICommandLog Login="MSOLNIT-PC\ASPNET">
<Results Command="Delete" ID="1">Role "Report Creator" deleted.</Results>
<Error Command="Delete" ID="2">
<![CDATA[Error while processing command "Delete".
[ErrorSource="ICommandEngine", ErrorID="ICommandEngine.Error"] There is no User
named "joeschmoe". [ErrorSource="ICommandEngine",
ErrorID="ICommandEngine.UserExist"]]]>
</Error>
</ICommandLog>
In Example 37–21, continueonerror only applies to the command that deletes user
joeschmoe. If this command fails, then ICommand will output the error and continue.
But if any other command fails, ICommand will immediately stop.
37-18 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Regular Expressions
37-20 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Using ICommand Web Service
37.13.1 Differences between the ICommand Web Service and the ICommand
Command-Line Utility
The ICommand web service includes most of the same features as the command-line
utility. For example, you can use it to:
■ Delete a data object
■ Import rows into a data object
■ 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 will receive back
the export content inline.
Commands other than import and export generally work the same as with the
command-line utility.
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 37.9, "Format of Command File." The return value is a string containing the
results of executing each command, in the log syntax described in Section 37.10,
"Format of Log File."
37-22 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Using ICommand Web Service
<Row ID="1">
<Column ID="_Region" Value="Western Region" />
<Column ID="_State" Value="Arizona" />
<Column ID="_Category" Value="Film" />
<Column ID="_Brand" Value="Kodak" />
<Column ID="_Description" Value="35mm 200" />
<Column ID="_Sales" Value="2000" />
</Row>
<Row ID="2">
<Column ID="_Region" Value="Western Region" />
<Column ID="_State" Value="Arizona" />
<Column ID="_Category" Value="Film" />
<Column ID="_Brand" Value="Kodak" />
<Column ID="_Description" Value="35mm 400" />
<Column ID="_Sales" Value="2100" />
</Row>
</Contents>
</DataObject>
</OracleBAMExport>
<Results Command="Export">Exporting Data Object "/Samples/Film
Sales"...</Results>
<Results Command="Export">Data Object "/Samples/Film Sales"
exported successfully (29 rows).</Results>
<Results Command="Export">1 items exported successfully.</Results>
</ICommandLog>
37-24 Oracle Business Activity Monitoring Architect User's Guide Beta Draft
Part VI Oracle User Messaging Service
This part describes how to use the Oracle User Messaging Service.
This part contains the following chapters:
■ Chapter 38, "Configuring User Messaging Service,"
■ Chapter 39, "Parlay X Web Services Multimedia Messaging API"
■ Chapter 40, "User Messaging Preferences"
■ Chapter 41, "Send Message to User Specified Channel Sample Application"
■ Chapter 42, "Oracle User Messaging Service Expense Report Use Case"
Beta Draft
Beta Draft
38
Configuring User Messaging Service
This chapter describes how to configure Oracle User Messaging Service (UMS) to
support SMS, Voice, and IM channels. This chapter includes the following sections:
■ Section 38.1, "Overview of Oracle User Messaging Service Configuration"
■ Section 38.2, "Configuring User Messaging Service Drivers"
■ Section 38.3, "Deploying Drivers"
■ Section 38.4, "Configuring Messaging Preferences"
To enable the workflow participants to receive and forward notifications, use Oracle
11g Enterprise Manager to set the Oracle User Messaging Service environment by
configuring the appropriate driver instances that reside on the same application server
on which you deploy the workflow application (Figure 38–2). Oracle User Messaging
Service ships with drivers that support messaging through the E-Mail, IM, SMS and
voice channels. For more information, see Section 38.2, "Configuring User Messaging
Service Drivers".
For the workflow participants to actually receive the notifications, they must register
the devices that they use to access messages through User Messaging Preferences
(Figure 38–3). For more information, see Section 38.4, "Configuring Messaging
Preferences".
Note: Oracle User Messaging Service ships with only the E-Mail
driver deployed. For information on deploying the other drivers, see
Section 38.3, "Deploying Drivers".
To configure a driver:
1. Log into the Enterprise Manager Fusion Middleware Control console as an
administrator.
2. Expand the Fusion Middleware folder and then the SOA folder (Figure 38–4).
5. Select the Local tab to access the driver deployed to the SOA instance. The ALL tab
lists drivers that are deployed to all of the instances.
6. Select a driver (such as the E-Mail driver, illustrated in Figure 38–5) and then click
the adjacent Edit icon (illustrated in Example 38–6 as a pencil) in the Configure
Driver column.
7. If needed, expand the Driver-Specific Configuration section and configure the driver
parameters. For more information, see Section 38.2.1, "Configuring Driver
Properties".
Note: The SMPP Driver driver implements Version 3.4 of the SMPP
protocol and only supports connections to an SMS-C that supports
this version.
In addition to the common properties described in Table 38–1, the SMPP driver
includes the following properties that are associated with configuring access to the
remote gateway and protocol- and channel-specific behavior (described in Table 38–3).
recipients are addressed by a user name and a host name (for example:
username@hostname). In the XMPP network, users are identified by an XMPP (Jabber)
ID, which consists of a user name and the host name of the particular XMPP server to
which the user connects. An end user of XMPP connects to an XMPP server using an
XMPP client to send instant messages to other XMPP users. XMPP has an extensible
and modular architecture. It integrates with proprietary IM networks such as Yahoo!,
MSN, AOL and ICQ using transport gateways that can connect to these networks.
XMPP, however, is not the only protocol network available for instant messaging.
The XMPP Driver provides end users with unidirectional and bidirectional access from
Oracle Application Server for real-time instant messaging (IM) through XMPP. This
driver enables end users to receive alert notifications or chat through their IM client of
choice.
In addition to the properties described in Table 38–1, the XMPP driver also includes
the following properties that relate to configuring access to the remote gateway and
protocol- or channel-specific behavior (described in Table 38–5).
SMTP or IMAP mail server. Table 38–7 lists the parameters specific to the Proxy Driver
as well as those described in Section 38.2.1 as they relate to the Proxy Driver.
To access the deployment wizard, first select the Farm menu’s J2EE Application
Deployment option and then select Deploy (Figure 38–8).
The Deploy option invokes the deployment wizard, which guides you through the
deployment process through the following pages:
■ The Select Archive page (Figure 38–9) is the first page of the wizard. To complete
this page, point OC4J to location of the driver’s EAR (Enterprise Archive) file,
which is typically located at ORACLE_HOME/archives/applications. This page
also enables you to select the option to create or apply a deployment plan, a
client-side aggregation of all of the configuration data needed to deploy an archive
into OC4J. If you use an existing deployment plan, you enter its location. If you
opt for new deployment plan, select the Automatically Create a New
Deployment Plan option.
■ Clicking Next invokes the Select Target page (Figure 38–10). This page enables
you to select the driver’s parent application.
■ The Deployment Settings page ([[graphic to be added]]) provides a tasks that enable
you to edit the deployment plan.
Complete deployment tasks as needed and then click Deploy. The confirmation
page appears ([[graphic to be added]]).
The driver appears as an active application in the Associated Drivers pare
(Figure 38–5).
Define the channels for the device by first selecting the transport type from the
Add Channels list and then by entering the appropriate number or address.
4. Click Add (Figure 38–14).
5. Click OK to complete the device. The device appears on the Devices page,
represented as subfolder, the contents of which are the device’s channels. The
Devices page enables you to edit or delete the device as well as set a device channel
as the default destination for receiving notifications. Clicking Cancel discards the
device.
■ Customer Name
■ Customer Type
■ Status
■ Amount
■ Due Date
■ Process Type
■ Expense Type
■ Total Cost
■ Processing Time
■ Order Type
■ Service Request Type
■ Group Name
■ Source
■ Classification
■ Duration
■ User
■ Role
5. Combine the selected condition type with one of the following comparison
operators:
■ Is Equal To
■ Is Not Equal To
■ Contains
■ Does Not Contain
If you select the Date attribute, select one of the following comparison operators and
then select the appropriate dates from the calendar application.
■ Is Equal
■ Is Not Equal
■ Is Greater Than
■ Is Greater Than or Equal
■ Is Less Than
■ Is Less Than or Equal
■ Between
■ Is Weekday
■ Is Weekend
6. Add appropriate values describing the attributes or operators.
7. Click Add (Figure 38–14) to add the attribute and the comparison operators to the
table.
8. Repeat these steps to add more filter conditions. To delete a filter condition, click
Delete (Figure 38–15).
9. Select one of the following delivery rules:
■ Broadcast to All Channels -- Select this option to send messages to every
listed channel.
■ Send to One of the Selected Channels (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.
■ Do Not Send Any Message -- Select this option to block the receipt of any
messages that meet the filter conditions to all of the listed channels.
10. To set the delivery channels, select a channel from the Add Notification Channel list
and then click Add (Figure 38–14). To delete a channel, click Delete (Figure 38–15).
11. 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
One of the Selected Channels (Failover in the Order).
12. Click OK to complete the filter. Clicking Cancel discards the filter.
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. It contains the following sections:
■ Section 39.1, "Overview of Parlay X Messaging Operations"
■ Section 39.2, "Send Message Interface"
■ Section 39.3, "Receive Message Interface"
■ Section 39.4, "Oracle Extension to Parlay X Messaging"
■ Section 39.5, "Parlay X Messaging Client API and Client Proxy Packages"
Note: Oracle User Messaging Service also ships with a Java API
implementation of the Parlay X API.
39-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Receive Message Interface
39-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Receive Message Interface
39-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Parlay X Messaging Client API and Client Proxy Packages
■ ReceiveMessageClient
■ ReceiveMessageManagerClient
Each client class allows a client application to invoke the operations in the
corresponding interface. These classes also provide generic methods to set standard
Web Service parameters such as the remote gateway URL (using the setEndpoint()
method), and the remote security credentials (using the setUsername() and
setPassword() methods). The security credentials will be 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 neccessary configuration items (endpoint, username, password), then invoke
one of the business methods (e.g. SendMessageClient.sendMessage(), etc). For
examples of how to use this API, see the Messaging samples, and specifically
sdpmessagingsample-parlayx-src.zip.
39-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
40
User Messaging Preferences
This chapter describes the User Messaging Preferences that are packaged with Oracle
User Messaging Service. It describes how the user configures User Messaging
Preferences and how filters work. This chapter contains the following sections:
■ Section 40.1, "Introduction"
■ Section 40.2, "Configuring Filters and Conditions"
■ Section 40.3, "Configuring Device Destination Addresses"
40.1 Introduction
User Messaging Preferences allows a user who has access to multiple devices or
channels (delivery types) to deliver notifications to a preferred device using filters.
These filters are also known as notification delivery preferences. An Oracle database, a
Toplink-compliant database, or a file-based database stores device addresses, rule sets,
and user devices.
40.1.1 Terminology
User Messaging Preferences defines the following terminology:
■ Device: a physical device, such as a phone, or PDA.
■ Device address: one of the addresses that a device can communicate with.
■ Filters: a set of notification delivery preferences.
■ System term: a pre-defined business term that cannot be extended by the
administrator.
■ Business term: a rule term defined and managed by the system administrator
through Enterprise Manager. Business terms can be added, defined, or deleted.
■ Rule term: a system term or a business term.
■ 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.
■ Channel: the transport type, for example, e-mail, voice, or SMS.
■ 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 Device.
Rule (2): if (application = eBay) AND (source = 1234) AND (amount >= 200) then do
not notify [Alex]
A runtime service, the Oracle Rules Engine, evaluates the filters to process the
notification delivery of user requests.
Note: The String data type does not support regular expressions.
40-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Introduction
System Terms
Table 40–2 lists system terms, which are pre-defined business terms. Administrators
cannot extend the system terms.
Tip: User Messaging Preferences does not provide a filter action that
instructs "do not send to a specified device." A best practice is to
specify only positive actions, and not negative actions in rules.
40-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring Device Destination Addresses
■ All filter sessions are stateless. User Messaging Preferences has no knowledge of
previous facts or activation results.
– There is no decision-branching between two rules.
– There can be no aggregation rules such as number of notifications sent to a
device address in a time period.
– There can be no cross-user (group) rules.
For a given rule, the relationship between all comparisons can be either "match all
conditions" or "match any condition". This precludes the specification of a mixture of
ANDs and ORs.
40-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
41
Send Message to User Specified Channel
Sample Application
This chapter describes how to build and run the Send Message to User Specified
Channel sample application provided with Oracle User Messaging Service. This
chapter contains the following sections:
■ Section 41.1, "Overview"
■ Section 41.2, "Installing and Configuring SOA and User Messaging Service"
■ Section 41.3, "Building the Sample"
■ Section 41.4, "Creating a Deployment Profile"
■ Section 41.5, "Creating a New Application Server Connection"
■ Section 41.6, "Deploying the Application"
■ Section 41.7, "Configuring Drivers"
■ Section 41.8, "Configuring User Messaging Preferences"
■ Section 41.9, "Testing the Sample"
41.1 Overview
The “Send Message to User Specified Channel” sample demonstrates a BPEL process
that allows a message to be sent to a user through a messaging channel specified in
User Messaging Preferences. After you have configured a device and messaging
channel addresses for each supported channel and the default device, Oracle User
Messaging Service routes the message to the user based on the preferred channel
setting that you configured.
Beta Draft Send Message to User Specified Channel Sample Application 41-1
Installing and Configuring SOA and User Messaging Service
41-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
4. Enter the name for the project and click OK (Figure 41–3).
5. Select SendMessageProj, right click and select New, SOA Tier, Service
Components, and SOA Composite (Figure 41–4).
Beta Draft Send Message to User Specified Channel Sample Application 41-3
Building the Sample
6. Select the Composite With BPEL composite template. Click OK. (Figure 41–5).
7. In the Create BPEL Process window, enter the BPEL process name as
“SendMessage.” Click OK.
41-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
You have now created an empty and default BPEL application (Figure 41–7).
In the Oracle JDeveloper main window you can view the following components of
the sample 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.
Note: You will later create the messaging service resource that is
used to send the message when you create the User Notification BPEL
process (steps 13-19).
Beta Draft Send Message to User Specified Channel Sample Application 41-5
Building the Sample
8. Expand the xsd folder in the Application Navigator and open SendMessages.xsd by
double-clicking it .
9. Click on the Source tab (Figure 41–8).
41-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
10. 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 41–9), 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"/>
Beta Draft Send Message to User Specified Channel Sample Application 41-7
Building the Sample
41-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
13. Drag and drop User Notification from BPEL Activities and Components located in
the Component Palette between the receiveInput and callbackClient activities
(Figure 41–11).
Beta Draft Send Message to User Specified Channel Sample Application 41-9
Building the Sample
Figure 41–11 Drag and Drop the User Notification Activity from the Component Palette
14. Click the XPath Expression Builder icon to the right of the "To:" input box.
41-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
16. Click the XPath Expression Builder icon to the right of the "subject:" input box.
Beta Draft Send Message to User Specified Channel Sample Application 41-11
Building the Sample
18. Click the XPath Expression Builder icon to the right of the "body:" input box.
41-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Building the Sample
■ Click OK.
■ Click OK to apply the changes (Figure 41–16).
Beta Draft Send Message to User Specified Channel Sample Application 41-13
Building the Sample
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 41–17). The SOA Composite is
complete.
41-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a Deployment Profile
3. Select OAR File (Oracle Application archive) as the Archive Type (Figure 41–19).
Beta Draft Send Message to User Specified Channel Sample Application 41-15
Creating a New Application Server Connection
6. Click OK twice.
The deployment profile is complete.
41-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating a New Application Server Connection
Beta Draft Send Message to User Specified Channel Sample Application 41-17
Deploying the Application
41-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying the Application
Beta Draft Send Message to User Specified Channel Sample Application 41-19
Deploying the Application
9. Click OK.
10. Select the deployment target ending with "oc4j_soa" (Figure 41–27) and click OK.
11. Verify that the message "Deployment Finished" appears in the deployment log
(Figure 41–28).
41-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Configuring Drivers
Beta Draft Send Message to User Specified Channel Sample Application 41-21
Configuring User Messaging Preferences
■ IMServerHost -- The host name of the Jabber server. For multiple servers, use a
comma-separated list (for example, enter my1.host.com, my2.host.com). If only
one host name is specified, it will be used for all accounts.
■ IMServerPort -- The corresponding comma-separated list of Jabber server ports
(for example, enter 5222, 5222)
■ IMServerUsername -- A list of Jabber user names for login. These user accounts
will be automatically created, if necessary, on the corresponding Jabber servers. If
you have multiple servers listed in the IMServerHost and IMServer Port
properties, then there must be an equal number of user names (one user name per
server). If you have only one server listed in these properties, then all of the user
names listed in this property will use that server. For example, enter oracleagent1,
oracleagent2. You can also enter a complete Jabber ID if its domain name is
different from the Jabber server host name (for example, enter
oracleagent1@host.com).
■ IMServerPassword -- A comma-separated list of passwords for each user name
listed for the IMServerUsername property.
For more information on configuring driver parameters and setting up the
environment, refer to "Configuring Notifications" in the Oracle Fusion Middleware
Administrator’s Guide for Oracle SOA Suite.
41-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Testing the Sample
Beta Draft Send Message to User Specified Channel Sample Application 41-23
Testing the Sample
3. In the Client Endpoint window provide the input values for invoking
SendMessageApp.
Enter the following values:
■ to: fmwadmin (the user)
■ subject: notification test (the subject)
■ body: the message content
4. Click Invoke.
41-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
42
Oracle User Messaging Service Expense
Report Use Case
This document describes how to build an expense report use case through the
following sections:
■ Section 42.1, "Overview of the Expense Report Use Case"
■ Section 42.2, "Deploying the Pre-Built Sample Applications"
■ Section 42.3, "Running the Sample Application"
■ Section 42.4, "Building the Expense Report Applications"
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-1
Overview of the Expense Report Use Case
ExpenseReportComposite, which defines a mediator that consumes the events from the
ADF BC component and transforms them into BPEL input payload that invokes the
human workflow, defined in ExpenseAppHumanTaskFlow.
42.1.1 Prerequisites
The expense report scenario requires the following:
■ An IMAP4 or POP3 e-mail server.
■ E-mail accounts provisioned to the e-mail server for users jstein, cdickens, and
wfaulkner.
■ The E-Mail Driver configured to point to the e-mail server. See Section 42.1.1.2.
■ Database tables that define the business components. See Section 42.1.1.3.
Note: The SCA and task flow application must be deployed to the
same OC4J container. For more information, see Section 42.2,
"Deploying the Pre-Built Sample Applications"
Report’s business events. Example 42–2 defines ExpenseEvent as the event that
the mediator component of the ExpenseReportComposite application subscribes to
and publishes to the ExpenseAppHumanTaskFlow application.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-3
Overview of the Expense Report Use Case
</xs:complexContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="StringValuePair">
<xs:complexContent>
<xs:extension base="ValuePair">
<xs:sequence>
<xs:element name="newValue" minOccurs="0">
<xs:complexType>
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="value" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name="oldValue" minOccurs="0">
<xs:complexType>
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="value" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="DecimalValuePair">
<xs:complexContent>
<xs:extension base="ValuePair">
<xs:sequence>
<xs:element name="newValue" minOccurs="0">
<xs:complexType>
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="value" type="xs:decimal"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name="oldValue" minOccurs="0">
<xs:complexType>
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="value" type="xs:decimal"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:schema>
42.1.1.2 Configuring the User Messaging Service E-Mail Driver to Send and
Receive Messages
To enable users to receive and forward expense report notifications, use Oracle
Enterprise Manager Fusion Middleware Control to configure the parameters of the
User Messaging Service E-Mail driver to point to the appropriate e-mail server.
To configure the E-Mail Driver:
1. Log into the Enterprise Manager Fusion Middleware Control console as an
administrator (that is, use fmwadmin as the user name and welcome1 as the
password).
2. Navigate to the User Messaging Service Home page.
3. If needed, expand the Associated Drivers section (Figure 42–2).
4. Select the E-Mail driver and then click the adjacent Edit icon (illustrated in
Figure 42–3 as a pencil) in the Configure Driver column.
The configuration page for the E-Mail driver displays (Figure 42–4).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-5
Overview of the Expense Report Use Case
5. If needed, expand the Driver-Specific Configuration section and configure the E-Mail
driver parameters listed in Table 42–1 to point the driver to the proper e-mail
server.
42.1.1.3 Creating the Database Tables that Define the Business Components
Both ExpenseReportADFCApp and ExpenseAppHumanTaskFlow require a connection to
the application database that stores the expense_report and expense_items
tables (Example 42–1). The connection to these tables enables ExpenseReportADFBCApp
to provide the current and past expense report data to Oracle Expense Reports
(Figure 42–1). ExpenseAppHumanTaskFlow also consumes the data from these tables to
populate the payload information displayed in the view object.
Before you create the database tables, you must first create a database connection,
which is a two-step process:
1. Creating a new user (Section 42.1.1.3.1).
Connect to the database as SYSDBA and then create the "expense" user and
password used to connect with the database containing the expense_report
and expense_items schema.
2. Editing the existing database connection (Section 42.1.1.3.2).
Substitute the user name and password values in the existing SQL connection for
those of the new user. You may also need to change the host and port values used
for the existing SQL connection.
Note: To complete the Expense Report use case, you must edit the
connections that ship with both ExpenseAppHumanTaskFlow and
ExpenseReportADFBCApp.
After you create new user and password and edit the existing SQL connection, you
create the Expense Report schema. For more information, see "Creating the Database
Schema".
3. Click the Add icon (represented as a green plus sign in Figure 42–6). The Create
Database Connection dialog appears.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-7
Overview of the Expense Report Use Case
6. Click OK.
7. Create a user by entering a script similar to Example 42–4 in the Enter SQL
Statement pane (Figure 42–7). Example 42–4 sets expense as both the user name and
password to the database.
8. Click Execute Script (Figure 42–8). Data returned by the script displays in the
Script Output pane (illustrated in Figure 42–7).
Note: You must replace the default user names and passwords for
the SQL connections that ship with the ExpenseReportADFBCApp
application and the task flow application, ExpenseAppHumanTaskFlow
with those set for the “expense” user. You can edit the connections
through the Edit Database Connection dialog (accessed by right-clicking
the SQL Connections node of Application Resources, such the one
illustrated in Figure 42–9 and then by selecting Properties from the
context menu).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-9
Deploying the Pre-Built Sample Applications
2. Click Execute Script (Figure 42–8). Data returned by the script displays in the
Script Output pane.
Note: A dialog box may appear to warn you that the data from the
project will be migrated to the latest Oracle JDeveloper version and
that you will not be able to open the application or its project using an
older release. Click Yes.
2. Create a new connection by first clicking File and then selecting Connections
(located in the General section).
3. Select Application Server Connection from the Items pane and then click OK. The
Welcome page of the Application Server Connection Wizard displays.
4. Complete the wizard as follows:
a. Click Next. The Type page appears.
b. Enter 11g in the Connection Name field.
c. Select Oracle Application Server 11g as the Connection Type. Click Next. The
Authentication page appears.
d. Enter the user name and password (fmwadmin and welcome1, respectively).
e. Click Next. The Connection page appears.
f. Enter the server name and port.
g. Click Next. The Test page appears. Click Test Connection. If you defined the
connection properly, Success! appears.
5. In the Application Navigator, right-click ExpenseReportCompositeApp.
6. In the context menu that displays, select Deploy > ExpenseReportSCApp > to
and then select the Oracle Application Server 11g connection.
Note: Verify that the Build Successful message displays in the log.
7. Accept the default value of 1.0 as the New Version ID in the Revision ID dialog and
click OK.
8. In the Deployment Plan page select MDS Configuration.
9. Click Choose Repository in the Metadata Repository section.
10. In the Choose Repository window, click Select (next to the repository starting with
"ORACLE" with Type "DB." For example, "ORACLE_orcl_STADQ11_1012_MDS".
11. In the Shared MDS Connections pane, select Edit.
12. In the Partition drop down menu, select the partition with the suffix .soa-infra only.
14. Select the deployment target ending with "oc4j_soa" and then click OK.
15. Verify that the Deployment Finished message displays in the deployment log.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-11
Running the Sample Application
Note: Use either Internet Explorer 7.0 or the latest version of Mozilla
Firefox (such as 5.0), to run this application.
11. In a browser, open the Oracle BPM Worklist by entering following URL:
http://hostname:port/integration/worklistapp
15. Open the expense report approval e-mail sent to wfaulk (user name).
18. Check the status of the of the task in the Worklist application.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-13
Building the Expense Report Applications
4. In the Location page, enter ExpenseReportModel in the Project Name field. If needed,
enter an alternate location for the application in the Directory field. Otherwise,
accept the default location
(C:\JDeveloper\mywork\ExpenseReportADFBCApp\ExpenseReportModel).
5. Click Next. The Paths page appears with values populated to the Default Package,
Java Source Path and Output Directory fields.
6. If needed, change the information populated to the Paths page. Otherwise, click
Next. The Summary page appears.
7. Click Finish to complete the wizard. ExpenseReportModel displays in the
Application Navigator. Simultaneously, the Initialize Business Components Project
dialog appears.
42.4.1.1.2 Creating the Business Components In the Create Business Components from Tables
wizard:
1. Complete the Entity Objects page as follows:
a. Enter Expense% in the Name Filter field.
b. Click Query. EXPENSE_ITEMS and EXPENSE _REPORT appear in the
Available pane.
c. Click Add All to move these items to the Selected pane.
d. Click Next. The Updatable View Objects page appears (Step 2).
e. Click Add All to move EXPENSE_ITEMS and EXPENSE _REPORT to the
Selected pane.
f. Click Next to proceed from the Updatable View Objects page to the Read-Only
View Objects page (Step 3). EXPENSE_ITEMS and EXPENSE_REPORT appear
in the Available pane.
2. Click Add All to move EXPENSE_ITEMS and EXPENSE _REPORT to the Selected
pane.
3. Click Next. The Application Module page appears.
4. Accept the populated values in the Application Module page and click Next until
you reach the Summary page.
5. Click Finish to complete the wizard. The business components display in the
Application Navigator (Figure 42–12). With the business components created, you
now create the published events.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-15
Building the Expense Report Applications
2. Select the Business Events page (Figure 42–14) and then click the Add icon. The Edit
Business Event definition dialog appears (Figure 42–15).
4. Accept the default Value Sent property, Always, and then Click OK. ExpenseEvent
displays in the Event Definitions section of the Business Events page.
g. Click OK. The Business Events page reappears with the event publication data
populated to the Event Publication section (Figure 42–17).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-17
Building the Expense Report Applications
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-19
Building the Expense Report Applications
5. Select Business Components Service Interface from the Archive Type list.
6. Enter ExpenseReportModel in the Name field.
7. Click OK. The ExpenseReportModel deployment profile displays in the Deployment
Profiles pane of the Project Properties dialog (Figure 42–22).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-21
Building the Expense Report Applications
8. Name the view object expenseReport. This is the default view object.
9. Drag and drop two more View objects from the ADF Task Flow component palette
into the task-flow-definition.xml file and name them as follows:
■ createExpense
■ addExpenseItem
10. Create the flow between these views as follows:
a. Drag a Control Flow Case component from the Components Palette and then
drop it into expenseReport. Connect expenseReport to createExpense.
b. Label the Control Flow Case component as next.
c. Drag and drop a Control Flow Case from expenseReport to addExpenseItem.
d. Label the ControlFlowCase component as next.
e. Drag and drop a Control Flow Case component from addExpenseItem to
ExpenseReport.
f. Label the ControlFlowCase component as next. Figure 42–24 illustrates the view
items strung together in a task flow.
Figure 42–24 Creating the Task Flow Using the ADF Task Flow Component Palette
11. Create a .jspx page for the expenseReport view object by double-clicking the
expenseReport view object. The Create JSP dialog appears.
12. Click OK to create expenseReport.jspx.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-23
Building the Expense Report Applications
15. Select Action Outcome and then select next from the list.
17. Rename the button object by first placing the cursor on it and then by entering
Expense Report.
18. Click Enter.
19. Create a .jspx page for the createExpenseView object by double-clicking the
createExpenseView component. The Create JSP dialog appears.
20. Click OK to create createExpense.jsp.
21. If needed, expand Data Controls (Figure 42–26) and then drag and drop the
expenseReportView1 data control into createExpense.jsp.
22. From the context menu that appears, select Forms and then the ADF Creation
Form drop handler (Figure 42–27). The Edit Form Fields dialog appears
(Figure 42–27).
23. Select Include Submit and then click OK. The bindings display in createExpense.jsp
(Figure 42–28).
24. Double-click the Submit button. The Bind Action Property dialog appears
(Figure 42–25).
25. Select Action Outcome and then select next from the list.
32. Drag and drop the Commit operation into addExpenseItem.jspx next to the
navigation components (First, Previous, Next, and Last, illustrated in Figure 42–30).
33. From the context menu that appears, select ADF Button (illustrated in
Figure 42–30). The Commit button appears (Figure 42–31).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-25
Building the Expense Report Applications
4. Click OK. The Create OC4J Deployment Descriptor Wizard appears and opens to the
Select Descriptors page.
5. Complete the wizard as follows:
a. In the Select Descriptors page, select orion-application.xml and then click Next.
The Select Version page appears.
b. Select (or accept) 10.0 and then click Finish to create orion-application.xml.
6. Right-click ExpenseReportModel and then select Project Properties from the context
menu.
7. Select Compiler. Accept the default values in the Compiler pane and then click OK.
8. Click File and then New. The New Gallery appears.
9. Expand the General node (if needed) and select Deployment Profiles.
10. Select WAR file from the Items pane.
11. Click OK. The Create Deployment File – WAR File dialog appears.
12. Enter ExpenseReportDeploymentProfile in the Deployment File Name field.
15. In the Application Navigator, right-click the ExpenseReportModel project and then
select Deploy from the context menu.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-27
Building the Expense Report Applications
f. Click OK. The Event Chooser reappears (Figure 42–34) with the location of
ExpenseReport.edl in the Definition field, ExpenseEvent in the Event field, and the
schema definition of ExpenseEvent in the Type field.
Tip: If the Copy File dialog appears, click Yes to create a local copy of
ExpenseReport.edl.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-29
Building the Expense Report Applications
6. Repeat these steps for both the Input and Output elements. Click OK when
complete (Figure 42–39).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-31
Building the Expense Report Applications
Figure 42–40 The ExpenseReport BPEL Process in the SOA Composite Editor
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-33
Building the Expense Report Applications
6. Click OK. The Routing Rules panel of the mediator component editor is populated
with the ExpenseReport data, with xsl/ExpenseEvent_To_ExpenseInfo.xsl displaying in
the Using Transformation field (Figure 42–44).
4. Create links between the matching elements by dragging and dropping each of the
source elements to the corresponding target elements. Create the following links
described in Table 42–2.
5. Click Save.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-35
Building the Expense Report Applications
5. To specify the task owner dynamically (as opposed a static or dedicated user from
a directory configured for Oracle BPEL Process Manager), select XPATH from the
list next to the User field and then click the adjacent note pad icon to access the
Expression Builder dialog (Figure 42–50).
a. Expand task:task in the Schema pane.
b. Select task:creator.
c. Click Insert Into Expression and then click OK.
/task:task/task:creator appears in the User field of the Human Task
Editor.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-37
Building the Expense Report Applications
c. In the Dynamic User XPATH field, click the note pad icon to access the
Expression Builder dialog.
d. Build the following expression:
ids:getManager("/task:task/task:creator")
a. Maximum Number of Chain Levels Up: Select By Number and then enter 2.
b. Highest Title of Approver: Select By Title and then select Director.
11. Click OK to exit the Add Participant Type dialog.
12. Enable participants to approve or reject the expense report through e-mail as
follows:
a. Click the Add icon in the Notification Settings section.
b. Select Make email messages actionable.
13. Create a new task as follows:
a. Open the BPEL flow, ExpenseReport.bpel, either by clicking the
ExpenseReport.bpel tab or by selecting it from the Resources file in the
Application Navigator.
b. Drag a Human Task from the BPEL component palette and insert it below the
ReceiveInput component (Figure 42–52).
The Add a Human Task dialog appears. ExpenseReportTask displays in the Task
Definition list and Creator and ExpenseID display in the Task Parameters column
(Figure 42–53).
c. To insert a dynamic task title, click the note pad icon next to the Task Title field.
The Expression Builder dialog appears.
d. In the BPEL Variables pane, navigate to the payload of the inputVariable
and then select ns1:creator.
e. Click Insert Into Expression and then click OK.
f. Repeat these steps to select ns1:creator as the value for the Initiator field.
g. To define the Creator and ExpenseID task parameters, click the adjacent search
icon (Figure 42–54).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-39
Building the Expense Report Applications
h. In the Task Parameters dialog that appears, expand the Variables navigation tree
and select the appropriate task variables. For Creator, select ns1:creator.
For ExpenseID, select ns1:ID.
i. Click OK.
14. Once you complete the Add a Human Task dialog (Figure 42–55), click OK.
1. Click File and then click New. The New Gallery appears.
2. From the Categories pane, expand General and then select Applications.
3. In the Items pane, select Application and then click OK. The Create Application
Dialog appears.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-41
Building the Expense Report Applications
11. Click OK. The Create ADF Task Flow dialog appears.
12. Click OK. The task flow design page entitled ExpenseReportTask_TaskFlow.xml
appears with a default Task View object called taskDetails (Figure 42–58).
13. Rename the taskDetails object Header (accomplished by clicking the object’s
caption).
42.4.3.1.1 Populating the Header Task Flow Object To populate the Header object:
1. Double-click the Header Task View object. The Create JSF Page dialog appears.
2. Click OK. Header.jspx appears.
3. In the Applications Navigator’s Data Controls pane, expand ExpenseReportTask to
expose the task node.
4. Drag and drop the task node into Header.jspx. In the context menu that appears,
select Human Task. The Task Handler context menu, which includes the Custom
Actions drop handler appears (Figure 42–61).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-43
Building the Expense Report Applications
11. From the context menu (Figure 42–61), select Human Task and then the Task
Header drop handler. The Header panel appears (Figure 42–64).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-45
Building the Expense Report Applications
9. Click OK. The Create Business Components from Tables wizard appears and opens to
the Entity Objects page (Step 1).
42.4.3.1.3 Creating the Business Components In the Create Business Components from Tables
wizard:
1. In the Entity Objects page, enter Expense% in the Name Filter field.
2. Click Query. The EXPENSE_ITEMS and EXPENSE _REPORT tables appear in the
Available pane.
3. Click Next to proceed to the Read-Only View Objects page. Complete the Entity
Objects page as follows:
a. Enter Expense% in the Name Filter field.
b. Click Query. The EXPENSE_ITEMS and EXPENSE _REPORT tables appear in
the Available pane.
c. Click Add All to move these tables to the Selected pane.
4. Click Finish to complete the wizard. The business components created from the
database tables display in the Application Navigator.
5. In the Application Navigator, open ExpenseReportView.xml (located in
expenseapphumantaskflow). ExpenseReportView.xml opens, defaulting to the General
page.
6. Select Query. The Query page opens (Figure 42–65).
7. Click Edit (the pencil icon, illustrated in Figure 42–3). The Edit Query dialog
appears.
8. Append the following WHERE clause in the Where field (illustrated in Figure 42–66):
Expense.ID=:IDValue
9. Click OK.
10. Click Bind Variables in the navigation tree. The Bind Variables page appears.
12. Enter IDValue in the Name field and then click OK.
13. In Header.jspx (illustrated in Figure 42–64), invoke the context menu and then select
Go the Page Definition. HeaderPageDef.xml, which contains the page
configuration appears (Figure 42–68).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-47
Building the Expense Report Applications
14. Click Add in the Bindings panel. The Insert Item dialog appears.
16. Select AttributeValues as the item and then click OK. The Create Attribute Binding
dialog appears.
17. Add a new data source for this binding by clicking Add. The Add Data Source
dialog appears.
18. Expand ExpenseReportTask and then traverse to payload (ExpenseReportTask >
loadData (string, string, string) > Return > task > payload). payloadIterator displays in
the Iterator Name field.
Figure 42–69 Selecting the Data Source for the Attribute Binding
19. Click OK. The Create Attribute Binding dialog reappears, with the payload data
source displaying in the Data Source field (Figure 42–70).
20. Select ExpenseID from the Attribute list and then click OK.
21. Click Add in the Bindings panel. The Insert Item dialog appears.
22. Select General Bindings as the category type.
23. Select action as the item and then click OK. The Create Attribute Binding dialog
appears.
24. If needed, expand AddModuleDataControl and then select ExpenseReportView.
25. Click New to create a new iterator binding for ExpenseReportView. The Iterator ID
dialog appears.
26. Click OK.
28. In the Parameters section, click the Value field that corresponds to IDValue to
invoke the list function (Figure 42–71).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-49
Building the Expense Report Applications
30. Create the following expression by first expanding ADF Bindings in the Variables
pane and then traversing to inputValue (ADF Bindings > bindings > ExpenseId >
inputValue).
${bindings.ExpenseId.inputValue}
31. Click Insert Into Expression.
32. Click OK. The expression appears as the value for the IDValue parameter
(Figure 42–72).
33. Click Add in the Execute panel of HeaderPageDef.xml (Figure 42–68). The Insert
Item dialog appears.
34. Select invokeAction as the category type and then click OK. The Insert
InvokeAction dialog appears and defaults to the Common Properties page
(Figure 42–73).
37. Select always from the Refresh list and then click Finish (Figure 42–74).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-51
Building the Expense Report Applications
38. From the data controls panel, drag and drop the ExpenseReportView node into
Header.jspx.
39. From the context menu, first select Forms and then click ADF Read-only Form.
The Edit Form Fields dialog displays.
42.4.3.1.4 Creating the Footer Task Flow Object To create the Footer Task Flow object:
1. Drag and drop the ExpenseReportView node into Header.jspx.
2. From the context menu, first select Tables and then ADF Read-only Table.The Edit
Table Columns dialog appears.
3. Click OK.
4. Create the footer for the page. Drag and drop a view object from the component
panel into In ExpenseReportTask_Taskflow.xml (Figure 42–58).
5. Rename the view object Footer (Figure 42–76).
Figure 42–77 Connecting the Header and Footer Objects with Task Flows
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-53
Building the Expense Report Applications
e. Click the commandButton component and then rename it back (Figure 42–80).
14. In the Application Navigator, expand Application Sources and then open
taskflow.properties.
15. Add the following parameter:
human.task.lookup.type=LOCAL
4. Double-click EmailPage view object to create EmailPage.jspx. The Create JSF JSP
dialog appears.
5. Click OK.
6. Drag a Panel Group Layout component from the Component Palette and drop it
into EmailPage.jspx.
7. Using the Property Inspector for the Panel Group Layout object, change the layout
of the Panel Group Layout object by selecting vertical from the Layout list
(Figure 42–82).
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-55
Building the Expense Report Applications
8. Insert an image into Email.jspx before the Panel Group Layout object as follows:
a. Right-click the Panel Group Layout object and then select Insert Before Panel
Group Layout-vertical.
b. From the context menu, select ADF Faces. The Insert ADF Faces Item dialog
appears.
c. Select Image and then click OK. The Insert Image dialog appears and defaults
to the Common Properties page.
d. Using the Search icon (Figure 42–54), locate the image and then click Finish.
9. Populate the Panel Group Layout object by dragging ExpenseReportView1 (located
beneath AppModuleDataControl in the Application Navigator’s Data Controls) into
Email.jspx.
10. Select Forms and then ADF Read only Form from the context menu
(Figure 42–75).
11. Select the Panel Form Layout. The Panel Group Layout is populated.
12. In Panel Group Layout -vertical- Property Inspector (Figure 42–84), select Style and
then define the inline style as follows:
"margin: 2px; border: 1 px solid black; padding: 3px; overflow: auto; width: 95%;"
Note: Separate each style with semi-colons. Separate each key value
with quotation marks.
13. Drag a Router object from the Components Palette into ExpenseReportTask_
TaskFlow.xml.
14. Using the Property Inspector for the router object, rename the router object by
entering EmailRouter in the id* field.
18. In the Property Inspector for the Call Flow Case component
(control-flow-case-Header-Property Inspector), select default from the from outcome
list. The from-outcome and to-activity-id values are default and Header, respectively.
19. Drag a Control Flow Case component from the Components Palette and then
connect it to the EmailRouter component.
Beta Draft Oracle User Messaging Service Expense Report Use Case 42-57
Building the Expense Report Applications
20. Rename this component EmailPage and then connect this Control Flow Case
component using the Property Inspector as by entering EmailPage as both the
from-outcome and to-activity-id values.
24. Select Expression Builder from the list accessed from the expression field. The
Expression Builder appears.
25. Build the following expression and then click OK.
#{pageFlowScope.bpmClientType=="notificationClient"}
42.4.3.1.7 Deploying the TaskFlow Application See Section 42.2.2, "Deploying the ADF BC
Application (ExpenseReportADFBCApp)".
This part describes how to create, deploy, and run test cases that automate the testing
of SOA composite applications.
This part contains the following chapter:
■ Chapter 43, "Testing SOA Composite Applications"
Beta Draft
Beta Draft
43
43 Testing SOA Composite Applications
This chapter describes how to create, deploy, and run test cases that automate the
testing of SOA composite applications. Test cases enable you to simulate the
interaction between a SOA composite application and its Web service partners prior to
deployment in a production environment. This helps to ensure that a process interacts
with Web service partners as expected by the time it is ready for deployment to a
production environment.
This chapter contains the following topics:
■ Section 43.1, "Overview of the Composite Test Framework"
■ Section 43.2, "Components of a Test Suite"
■ Section 43.3, "Creating Test Suites and Test Cases in Oracle JDeveloper"
■ Section 43.4, "Creating the Contents of Test Cases"
■ Section 43.5, "Deploying a Test Suite"
■ Section 43.6, "Running a Test Suite and Viewing Report Results"
See Also: Section 43.3, "Creating Test Suites and Test Cases in Oracle
JDeveloper" on page 43-6
See Also:
■ Section 43.3, "Creating Test Suites and Test Cases in Oracle
JDeveloper" on page 43-6
■ Section 43.4, "Creating the Contents of Test Cases" on page 43-8
See Also:
■ Section 43.2.2, "Emulations" on page 43-4
■ Section 43.4, "Creating the Contents of Test Cases" on page 43-8
43-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Components of a Test Suite
■ XML Assert — Compare the element values of an entire XML document to the
expected element values. For example, compare the exact contents of an entire
loan request XML document to another document.
See Also:
■ Section 43.2.3, "Assertions" on page 43-5
See Also: Section 43.6, "Running a Test Suite and Viewing Report
Results" on page 43-22
<loanAmount>20000</loanAmount>
<carModel>Camry</carModel>
<carYear>2007</carYear>
<creditRating>800</creditRating>
</loanApplication>
</content>
</part>
</message>
</initiate>
</compositeTest>
43.2.2 Emulations
You create emulations to simulate the message data that your SOA composite
application receives from Web service partners.
The following test code instructs Oracle SOA Suite to initiate the loan request with an
error and receive a fault message in return from a Web service partner:
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SCA Test Modeler version 1.0 at [7/3/07 3:29 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">
<fault faultName="ser:NegativeCredit" xmlns:ser="http://services.otn.com">
<message>
<part partName="payload">
<filePath>creditRatingFault.xml</filePath>
</part>
</message>
</fault>
</emulate>
</wireActions>
</compositeTest>
See Also:
■ Section 43.4, "Creating the Contents of Test Cases" on page 43-8
43-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Components of a Test Suite
43.2.3 Assertions
You create assertions to validate a variable or an entire XML document at a point
during SOA composite application execution. The following example instructs Oracle
SOA Suite to ensure that the content of the customername variable matches the
content specified.
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SCA Test Modeler version 1.0 at [6/13/07 10:51 AM]. -->
<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@oracle.com</email>
<customerName>Joe Smith</customerName>
<loanAmount>20000</loanAmount>
<carModel>Camry</carModel>
<carYear>2007</carYear>
<creditRating>800</creditRating>
</loanApplication>
</content>
</part>
</message>
</initiate>
<wireActions wireSource="client" operation="initiate">
<assert comparisonMethod="string">
<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>
See Also:
■ Section 43.4, "Creating the Contents of Test Cases" on page 43-8
See Also:
■ Section 43.4, "Creating the Contents of Test Cases" on page 43-8 for
instructions on loading message files into test mode
b. Right-click Test Suites in the Structure window and select Create Test Suite.
43-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating Test Suites and Test Cases in Oracle JDeveloper
The following subdirectories for adding test files are created beneath logicTest:
includes, messages, componenttests, and tests.
8. If you want to exit test mode and return to design mode in the SOA Composite
Editor, click the x icon next to TestDelivery.xml above the designer.
Notes:
■ The componenttests folder for the BPEL process service
component is not supported for beta 3. Only testing at the SOA
composite application level is supported for beta 3.
■ Do not edit the FileList.xml files that display under 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.
43-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
Field Value
Service Displays the name of the binding component service (client).
Operation Displays the operation type of the binding component service
(initiate).
Part Select the type of inbound message to send (for example, payload).
Value Create a simulated message to send from a client:
■ Enter Manually Click to manually enter message data in the Enter Value field. A
Generate Sample button enables you to automatically generate a
sample file for testing. Click Save As to save the sample file.
■ Load From File Click the Browse icon to load message data from a file. The file is
added to the messages folder in the Application Navigator.
4. Click OK.
43-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
This displays the Wire Actions window, from which you can design emulations
and assertions for the selected part of the SOA composite application. By default,
Do Not Emulate is selected. This is because no tests have been created.
Field Value
Output Message Displays the output message of the selected service component.
Part Select the message part containing the output (for example, payload).
Value Create a simulated output message to return from a Web service partner:
■ Enter Manually Click to manually enter message data in the Enter Value field. A
Generate Sample button enables you to automatically generate a
sample file for testing. Click Save As to save the sample file.
■ Load From File 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 message to be
delivered from the Web service partner.
43-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
6. Click OK.
Notes:
■ The Use Base Wire Actions button on the Wire Actions window is
disabled for beta 3.
■ The Create Component Test window that displays when you
double-click a BPEL process service component in test mode (for
example, LoanBroker or CreditRatingService shown in the
examples in this chapter) is not supported for beta 3.
Field Value
Callback Operation Select the callback operation (for example, onResult).
Callback Message Displays the callback message name of the asynchronous process.
Part Select the message part containing the callback (for example, payload).
Value Create a simulated callback message to return from an asynchronous
Web service partner:
■ Enter Manually Click to manually enter message data in the Enter Value field. A
Generate Sample button enables you to automatically generate a
sample file for testing. Click Save As to save the sample file.
■ Load From File 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 callback message to
be delivered from the Web service partner.
An example of a simulated callback message from a Web service partner that you
enter manually or load from a file is as follows:
<?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>
43-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
<selected>false</selected>
<approved>true</approved>
<APR>1.9</APR>
</loanOffer>
4. Click OK.
Field Value
Fault Select the fault type to return from a partner (for example,
NegativeCredit).
Fault Message Displays the message name.
Part Select the message part containing the fault (for example, payload).
Value Create a simulated fault message to return from a Web service partner:
■ Enter Manually Click to manually enter message data in the Enter Value field. A
Generate Sample button enables you to automatically generate a
sample file for testing. Click Save As to save the sample file.
■ Load From File 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.
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 43.2.2, "Emulations" on
page 43-4.
Note also that the operation for the SOA composite application (for this example,
process) displays in the Operations column on the left.
4. Click OK.
43-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
Type Description
Assert Input Select to create an assertion in the inbound direction.
Assert Output Select to create an assertion in the outbound direction.
Assert Fault Select to assert a fault into the application flow.
5. See the following section based on the type of assertion you want to perform.
Field Value
Fault Select the type of fault to assert (for example, NegativeCredit). This
field only displays if you select Assert Fault in Step 4 on page 43-17.
Assert Target Displays the variable assert target you selected in Step 2.
Compare By Select the type of comparison:
■ string — Compares string values
■ number — Compares numerical values
■ pattern-match — Compares a regular expression pattern (for
example, [0-9]*).
Assert Value Enter the value you are expecting. This value is compared to the value
for the assert target.
Description Enter an optional description.
43-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Creating the Contents of Test Cases
4. Click OK.
The Wire Actions window displays your selection.
5. Click OK.
The Create Assert window refreshes based on your selection of an entire XML
document.
3. Enter the following details in the remaining fields:
Field Value
Fault Select the type of fault to assert (for example, NegativeCredit). This
field only displays if you select Assert Fault in Step 4 on page 43-17.
Assert Target Displays the XML document assert target you selected in Step 2.
Compare By Specify the strictness of the comparison.
■ xml-identical — Used when the comparison must be exact (for
example, element ordering).
■ xml-similar — Used when the comparison must be similar in
content, but do not need to exactly match
Part Select the message part containing the XML document (for example,
payload).
Value Create an XML document whose content is compared to the assert
target content:
■ Enter Manually Click to manually enter message data in the Enter Value field. A
Generate Sample button enables you to automatically generate a
sample file for testing. Click Save As to save the sample file.
■ Load From File Click the Browse icon to load message data from a file. The file is added
to the messages folder in the Application Navigator.
Description Enter an optional description.
43-20 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Deploying a Test Suite
4. Click OK.
The Wire Actions window displays your selection.
5. Click OK.
43-22 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Running a Test Suite and Viewing Report Results
Field Description
TestRun Name Enter a name for the test instance. When testing is
complete, report details are captured under this name.
Timeout Enter a value in seconds in which to complete this test. If
the test does not complete within this time limit, then
testing is terminated.
Number of Concurrent Test Enter the number of test instances to create.
Instances
The Test Runs tab displays details about the test instance.
7. Click a specific test in the TestRun Name column.
8. Scroll down the page and review the results under the Results tab.
11. Click the percentage value under Coverage for a BPEL process service component.
Activities that were executed are framed in green and activities that were not
executed are framed in pink.
12. Scroll down and note the pink sections that were not executed.
43-24 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Running a Test Suite and Viewing Report Results
43-26 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Part VIII Appendices
Beta Draft
Beta Draft
A
A Building a Custom Worklist Client
Starting with the sample Worklist Application, 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.
This chapter contains the following topics:
■ Section A.1, "Introduction to Building Clients for Workflow Services"
■ Section A.2, "Packages and Classes for Building Clients"
■ Section A.3, "Workflow Service Clients"
■ Section A.4, "Classpaths for Clients Using SOAP"
■ Section A.5, "Classpaths for Clients Using Remote EJBs"
■ Section A.6, "Classpaths for Clients Using Local EJBs"
■ Section A.7, "EJB References in Web Applications"
■ Section A.8, "Initiating a Task"
■ Section A.9, "Writing a Worklist Application Using the HelpDeskUI Sample"
Example A–1 Building a Client for Workflow Services—Setting the Outcome to Approved
try
{
//Create JAVA WorflowServiceClient
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.JAVA_CLIENT);
//Get the task query service
ITaskQueryService querySvc = wfSvcClient.getTaskQueryService();
//Login as jstein
IWorkflowContext ctx = querySvc.authenticate("jstein",
"welcome1",
null, //Use default realm
null);//Not logging in on behalf of another user
//Set up list of columns to query
List queryColumns = new ArrayList();
queryColumns.add("TASKID");
queryColumns.add("TASKNUMBER");
queryColumns.add("TITLE");
queryColumns.add("OUTCOME");
}
catch (Exception e)
{
//Handle any exceptions raised here...
System.out.println("Caught workflow exception: "+e.getMessage());
}
A-2 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Workflow Service Clients
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.MODE,
IWorkflowServiceClientConstants.MODE_DYNAMIC);
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_PROVIDER_URL,
"ormi://localhost/soa-infra");
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS,
"welcome1");
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL,
"oc4jadmin");
IWorkflowServiceClient client =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.REMOTE_CLIENT,
properties, null);
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.MODE,
IWorkflowServiceClientConstants.MODE_DYNAMIC);
A-4 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Workflow Service Clients
properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.SOAP_END_POINT_ROOT,
"http://localhost:8888");
IWorkflowServiceClient client =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.SOAP_CLIENT,
properties, null);
IWorkflowServiceClient client =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.REMOTE_CLIENT,
properties, logger);
Through the factory, it is possible to get the client libraries for all the workflow
services. Table A–1 shows the clients available for each of the services.
The client classes use the configuration file wf_client_config.xml for the service
end points. In the client classpath, this file is in the classpath directly, meaning the
containing directory is in the classpath. The wf_client_config.xml file contains:
■ A section for EJB configuration
<ejb>
<serverURL>ormi://localhost/hw_services</serverURL> <!-- for stand alone -->
<!--serverURL>opmn:ormi://localhost:home/hw_services</serverURL--> <!-- for
opmn managed instance -->
<user>oc4jadmin</user>
<password>welcome1</password>
<initialContextFactory>oracle.j2ee.rmi.RMIInitialContextFactory</initialContextFac
tory>
</ejb>
See the chapter "Web Service Client APIs and JARs" in the section "Simplifying the
Classpath with wsclient_extended.jar" in Oracle Application Server Web Services
Developer's Guide 10g Release 3 (10.1.3), at
http://www.oracle.com/technology/documentation
A-6 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
EJB References in Web Applications
Note: Only child applications can use local EJBs. This restricts
standalone Java clients to using either remote EJBs or SOAP clients.
See Chapter 28, "Human Task Services," for more information on TaskQueryService,
TaskReportService, UserMetadataService, and RuntimeConfigService.
A-8 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Initiating a Task
The payload XML element contains all the other XML elements in it. Each XML
element defines a message attribute.
Example A–7 shows how to set a task payload.
task.setPayloadAsElement(payloadElem);
// set title
task.setTitle("Vacation request for jcooper");
// set creator
task.setCreator("jcooper");
// set taskDefinitionId
task.setTaskDefinitionId("/VacationRequestApp/VacationRequest!1.0*2007-04-26-10-49-50/
VacationRequest"); (Your task definition ID will be different.)
payloadElem.appendChild(vacationRequestElem);
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;
A-10 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Writing a Worklist Application Using the HelpDeskUI Sample
<html>
<head>
<title>Help desk request login page</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<%
String redirectPrefix = "/HelpDeskUI/";
// Ask the browser not to cache the page
response.setHeader("Pragma", "no-cache");
response.setHeader("Cache-Control", "no-cache");
{
authFailed = false;
}
if (!authFailed)
{
//Get page parameters:
String userId="";
if(request.getParameter("userId") != null)
{
userId = request.getParameter("userId");
}
String pwd="";
if(request.getParameter("pwd") != null)
{
pwd = request.getParameter("pwd");
}
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.JAVA_CLIENT);
IWorkflowContext wfCtx =
wfSvcClient.getTaskQueryService().authenticate(userId, pwd,
oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(), null);
httpSession.setAttribute("workflowContext", wfCtx);
response.sendRedirect(redirectPrefix + "statusPage.jsp");
}
catch (Exception e)
{
String worklistServiceError = e.getMessage();
response.sendRedirect(redirectPrefix + "login.jsp?authFailed=true");
out.println("error is " + worklistServiceError);
}
}
} else
{
out.println("Authentication failed");
}
}
}
%>
A-12 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Writing a Worklist Application Using the HelpDeskUI Sample
</td>
<td>
<input type="password" name="pwd"/>
</td>
</tr>
<tr>
<td>
<input type="submit" value="Submit"/>
</td>
</tr>
</table>
</form>
</div>
</div>
</center>
</body>
</html>
oracle.bpel.services.workflow.verification.IWorkflowContext,
oracle.tip.pc.services.common.ServiceFactory,
oracle.bpel.services.workflow.client.IWorkflowServiceClient,
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory,
oracle.bpel.services.workflow.query.ITaskQueryService,
oracle.bpel.services.workflow.task.model.Task,
oracle.bpel.services.workflow.task.model.IdentityType,
oracle.tip.pc.services.identity.BPMUser,
java.util.List,
java.util.Calendar,
java.text.SimpleDateFormat,
java.util.ArrayList"%>
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>RequestPage</title>
<style TYPE="text/css">
Body, Form, Table, Textarea, Select, Input, Option
{
font-family : tahoma, verdana, arial, helvetica, sans-serif;
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) {
A-14 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Writing a Worklist Application Using the HelpDeskUI Sample
}
}
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.JAVA_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();
String state = task.getSystemAttributes().getState();
String outcome = task.getSystemAttributes().getOutcome();
if(outcome == null) outcome = "";
String titleLink = "http://" + request.getServerName() +
":" + request.getServerPort() +
"/integration/worklistapp/TaskDetails?taskId=" +
task.getSystemAttributes().getTaskId();
%>
<tr class="userInfo">
<td><%=taskNumber%></td>
<td><a href="<%=titleLink%>" target="_blank"><%=title%></a></td>
<td><%=priority%></td>
<td><%=dflong.format(createdDate.getTime())%></td>
<td><%=assignee%></td>
<td><%=dflong.format(updateDate.getTime())%></td>
<td><%=updatedBy%></td>
<td><%=state%></td>
<td><%=outcome%></td>
<tr>
<%
}
%>
</table>
</div>
<%!
private BPMAuthorizationService getAuthorizationService(String identityContext)
{
BPMAuthorizationService authorizationService =
ServiceFactory.getAuthorizationServiceInstance();
if (identityContext != null)
authorizationService = ServiceFactory.getAuthorizationServiceInstance(identityContext);
return authorizationService;
}
private String getAssigneeString(Task task) throws Exception
{
List assignees = task.getSystemAttributes().getAssigneeUsers();
StringBuffer buffer = null;
for(int i = 0 ; i < assignees.size() ; i++)
A-16 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Writing a Worklist Application Using the HelpDeskUI Sample
{
IdentityType type = (IdentityType)assignees.get(i);
String name = type.getId();
if(buffer == null)
{
buffer = new StringBuffer();
}
else
{
buffer.append(",");
}
buffer.append(name).append("(U)");
}
assignees = task.getSystemAttributes().getAssigneeGroups();
for(int i = 0 ; i < assignees.size() ; i++)
{
IdentityType type = (IdentityType)assignees.get(i);
String name = type.getId();
if(buffer == null)
{
buffer = new StringBuffer();
}
else
{
buffer.append(",");
}
buffer.append(name).append("(G)");
}
if(buffer == null)
{
return "";
}
else
{
return buffer.toString();
}
}
%>
</body>
</html>
A-18 Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite Beta Draft
Index
A operation
definition, 25-17
actionable notification
assert facts, execute rule set, retrieve results, and reset
definition, 23-1
the session operation
actional e-mails, 26-56, 28-24
definition, 25-17
activities
assertion tests
definition, 11-12
overview, 43-2
overview, 11-12
assertions
activity sensors
creating value asserts, 43-17
definition, 24-1
creating XML asserts, 43-19
Adapter Configuration wizard
in BPEL test suites, 43-5
starting, 11-18
assign activity
adapters
adding to an asynchronous service, 14-13
configuring, 11-18
copying data, 12-10
definition, 11-18
description, 12-2
in Oracle JDeveloper, 11-18
for data manipulation, 12-2
service names, 11-19
formatting the e-mail message body as
adding a cross reference table column, 10-6
HTML, 23-9
adding columns to domain value maps, 9-9
in asynchronous services, 14-13
adding rows to domain value maps, 9-9
assignment service
ADF bindings
configuration, 28-30
files for, 35-5
deploying a custom assignment service, 28-36
ADF Model layer, introduced, 35-1
dynamic assignment functions, 28-30, 28-31,
ADF task flow for human tasks, 27-2
28-32
advanced formatting, message sources, 36-4
dynamically assigning task participants, 28-32
aggregate functions in calculations, 32-4
example of implementation, 28-34
alerts
implementing, 28-33
history, 34-7
overview, 28-33
ant
asynchronous callbacks, 14-3
using the developer prompt, 11-2
asynchronous interaction with a notification timer
Application Navigator
BPEL process as the client, 22-5
contents of, 11-5
BPEL process as the service, 22-5
definition, 11-5
definition, 22-4
location of in Oracle JDeveloper, 11-4
asynchronous interaction with timeout
arrays
BPEL process as the client, 22-4
determining the size of, 12-22
BPEL process as the service, 22-4
in transformations, 4-23
definition, 22-4
manipulating, 12-20
asynchronous interactions
maxOccurs attribute, 12-20
BPEL process as the client, 22-3
SOAP-encoded arrays not supported, 12-25
BPEL process as the service, 22-3
statically indexing into, 12-21
definition, 22-3
assert facts and execute rule set operation
returning faults, 17-7
definition, 25-16
asynchronous processes
assert facts only operation
dehydration store, 14-10
definition, 25-16
using dehydration, 14-10
assert facts, execute rule set, and retrieve results
asynchronous services
Beta Draft -1
assign activities, 14-13 cases, 43-6
calling, 14-4, 14-10 process code coverage overview, 43-3
correlating messages, 14-6 running test suites from Oracle BPEL
correlation IDs, 14-6 Control, 43-22
correlation sets, 14-14 simple value assert, 43-2
invoke activities, 14-5, 14-11 test case overview, 43-2
managing multiple instances, 14-6 test suite assertions, 43-5
parallel flows, 15-1 test suite components, 43-3
partner links, 14-4, 14-10 test suite emulations, 43-4
partnerLinkTypes, 14-3 test suites overview, 43-2
receive activities, 14-5, 14-13 test suites process initiation, 43-3
reply activities, 14-10 viewing test results, 43-22
use case, 14-1 XML assert, 43-3
WS-Addressing, 14-6 BPEL XPath functions
attachments examples, 12-3
sending with the notification wizard, 23-6 BPEL_ACTIVITY_SENSOR_VALUES
task attachments with e-mail notifications, 26-57, sensor public view, 24-21
28-27 BPEL_FAULT_SENSOR_VALUES
using style sheets, 26-59 sensor public view, 24-21
using WordML style sheets, 26-59 BPEL_PROCESS_INSTANCES
attribute labels sensor public view, 24-20
internationalization, 28-15 BPEL_VARIABLE_SENSOR_VALUES
attributes sensor public view, 24-22
manipulating, 12-14 bpelx exec extension
auto mapping for embedding Java code in a BPEL process, 18-2
in transformations, 4-25 bpelx:append extension
with confirmation in transformations, 4-27 description, 12-15
bpelx:copyList extension
description, 12-19
B
bpelx:exec extension
batching built-in methods, 18-4
message batching limitations with Oracle Business bpelx:headerVariable extension
Activity Monitoring, 24-19 description, 12-27
bindingFault bpelx:insertAfter extension
definition, 17-4 description, 12-16
Boolean values bpelx:insertBefore extension
assigning, 12-13 description, 12-15
BPEL design environment bpelx:remove extension
overview, 11-2 description, 12-17
BPEL files bpelx:rename extension
definition, 11-5 description, 12-18
partner links definition, 13-2 bpelx:validate extension
BPEL processes description, 12-20
common interaction patterns, 22-1 building expression with domain value map
invoking with a Web Service/SOAP functions, 9-14
interface, 20-2 business faults
sending messages from a Java/JSP definition, 17-3
application, 20-1 business rules
BPEL projects definition, 25-1
naming conventions, 11-3 deployment and run time, 25-19
BPEL test integrating with BPEL processes through the
assertions overview, 43-2 decision service wizard, 25-14
creating test suites, 43-6 use case for data validation and constraint
creating value asserts, 43-17 checks, 25-13
creating XML asserts, 43-19 use case for dynamic processing, 25-13
definition, 43-1 use case for externalizing decision points in the
deploying test suites, 43-21 process, 25-13
emulating inbound messages, 43-9 use case for human workflow, 25-13
emulations overview, 43-2 use cases, 25-13
naming limitations on test suites and test with Oracle BPEL Process Manager, 25-2
-2 Beta Draft
business rules dictionary contents, data object, 32-7
definition, 25-3 copying security filters, 32-12
core XPath functions
examples, 12-3
C
correlation ID
calculated fields, 32-4 WS-Addressing, 14-6
calculations correlation sets
aggregate functions, 32-4 associating with receive activities, 14-22
datetime functions, 32-4 creating, 14-21
expressions, 32-4 creating property aliases, 14-23
string functions, 32-4 definition, 14-7, 14-9
callback, 6-19 tutorials, 14-14
callback classes WSDL file content, 14-25
specifying on task status, 26-61 correlations, 14-6
callbacks countNodes function, 12-22
task routing and customization in BPEL create domain value maps, 9-4
callbacks, 26-62, 26-79 create instance
viewing, 26-75 definition, 14-5
catch branch in receive activities, 14-5
fault handling, 17-7 createInstance attribute, 14-6
channels creating cross reference tables, 10-4
e-mail, 23-5 creating folders for data objects, 32-8
SMS, 23-9 creating mediator component
voice mail, 23-10 mediator files, 5-3
class names cross reference table look up, 10-13
specifying in the external routing service xref
participant type, 26-39 lookupXRef function, 10-13
classpaths lookupXRef1M function, 10-16
for clients using local EJBs, A-7 cross reference tables, 10-1
for clients using remote EJBs, A-7 adding a column, 10-6
for clients using SOAP, A-6 creating, 10-4
clearing data objects, 32-15 deleting a column, 10-7
code coverage tests deleting values, 10-17
overview, 43-3 looking up, 10-13
compensate activity modifying, 10-4
definition, 17-8 populating columns, 10-7
fault handling, 17-8 xref
complex type lookupXRef function, 10-13
variables, 12-10 lookupXRef1M function, 10-16
Component Palette markForDelete function, 10-17
definition, 11-9 populateXRefRow function, 10-7
location of in Oracle JDeveloper, 11-4 populateXRefRow1M function, 10-12
transformation functions, 11-9 cross references
components creating, 10-4
of Oracle SOA Suite, 1-3 introduction, 10-1
composite modifying, 10-4
overview, 2-4 overview, 10-1
concat function schema definition file, 10-20
description, 12-12 custom
conditional branching logic sensor publish type, 24-2
definition, 16-1 custom escalation function
use case, 16-1 using, 28-36
use of XPath expressions, 16-1 custom plug-ins
using switch activities, 16-2 use with identity service, 28-10
using while activities, 16-4
conditional processing
with xsl choose, 4-22
D
with xsl if, 4-21 data controls
constant values creating, 35-4
in transformations, 4-14 displayed on the Data Controls panel, 35-5
Beta Draft -3
Data Controls panel execute function operation definition, 25-17
icons defined, 35-5 retrieve results operation definition, 25-17
using to create a user interface, 35-6 decision service
data manipulation architecture, 25-3
accessing fields with complex type configuration file contents, 25-4
variables, 12-10 definition, 25-2
assigning Boolean values, 12-13 deployment and run time, 25-19
assigning date or time, 12-13 decision service wizard
assigning literal strings, 12-12 for integrating business rules with BPEL
assigning numeric values, 12-11 processes, 25-14
concatenating strings, 12-12 defining a fault handler, 17-5
converting from a string to a structured XML dehydration
object type, 12-25 definition, 14-10
copying data between variables, 12-10 dehydration store, 14-10
determining array sizes, 12-22 deleting a cross reference table column, 10-7
dynamically indexing into a data sequence, 12-22 Deleting a Mediator, 5-22
generating array-equivalent functionality with the deleting a routing service, 5-22
genEmptyElem function, 12-24 deleting cross reference table value, 10-17
initializing variables, 12-9 xref
manipulating arrays, 12-20 markForDelete function, 10-17
manipulating attributes, 12-14 deleting data objects, 32-15
mathematical calculations with XPath deleting folders, 32-10
functions, 12-11 demos
statically indexing into a data sequence, 12-21 binding faults, 17-5
with assign activities, 12-2, 12-10 run-time faults, 17-5
with XQuery and XSLT, 12-4 sensor actions, 24-3
data mapper sensors, 24-3
using, 6-32 deployment
data object contents, 32-7 from Oracle JDeveloper, 3-2
data object permissions, 32-4 developer prompt
data objects, 32-1 required when deploying services through ant or
organizing, 32-8 obant, 11-2
data objects, adding dimensions, 32-12 Diagram window, 11-5
data objects, clearing, 32-15 definition, 11-5
data objects, creating folders, 32-8 location of in Oracle JDeveloper, 11-4
data objects, defining, 32-1 dictionaries
data objects, deleting, 32-15 in transformations, 4-29
data objects, general information, 32-6 digital signatures, 28-16
data objects, moving, 32-14 dimensions, adding to data objects, 32-12
data objects, renaming, 32-14 dimensions, time, 32-13
data objects, security filters, 32-10 domain value maps
data sequences add columns, 9-9
dynamically indexing into, 12-22 add rows, 9-9
database creation, 9-4
sensor publish type, 24-2 dvm
date time stamp field, 32-4 lookupValue function, 9-9
dates lookupValue1M function, 9-10
assigning, 12-13 editing, 9-8
datetime functions in calculations, 32-4 features, 9-1
decide activity introduction, 9-1
assert facts and execute rule set operation one-to-many mapping, 9-3
definition, 25-16 overview, 9-1
assert facts only operation definition, 25-16 qualifier order, 9-2
assert facts, execute rule set, and retrieve results qualifiers, 9-2
operation definition, 25-17 reordering the columns, 9-9
assert facts, execute rule set, retrieve results, and using, 9-9
reset the session operation definition, 25-17 using in a transformation, 9-11
definition, 25-16 using lookupValue functions, 9-14
execute function and reset the session operation domain value maps features, 9-1
definition, 25-17 one-to-many mapping, 9-3
-4 Beta Draft
qualifier order, 9-2 escalating
qualifiers, 9-2 tasks, 26-46
domain value maps functions escalation policy
dvm escalate after, 26-51
lookupValue, 9-9 overview, 26-47
lookupValue1M, 9-10 specifying, 26-58
domain value maps qualifiers, 9-2 evaluation time
domain.xml file definition, 24-4
increasing the syncMaxWaitTime property, 19-4 evidence store, 28-16
location, 19-4 evidence store service, 28-2, A-5
drop handlers, custom for task display form, 27-5 example code, 36-5
drop handlers, standard ADF, 27-10 exceptions, 17-3
dvm execute function and reset the session operation
lookupValue function, 9-9 definition, 25-17
lookupValue1M function, 9-10 execute function operation
dynamic assignment definition, 25-17
of task participants, 26-26, 26-29, 26-33, 26-36, expiration policy
26-38 expire after, 26-49
dynamic assignment functions never expire, 26-49
configuring, 28-31 overview, 26-47
configuring display names, 28-32 renew after, 26-50
definition, 28-30 export file sample, ICommand, 37-18
implementing, 28-31 expression builder dialog
using domain value map functions, 9-14
expression constants
E
variable initialization, 12-9
edit domain value maps, 9-8 expressions in calculations, 32-4
add columns, 9-9 external routing service
add rows, 9-9 configuring, 26-38
reordering the columns, 9-9 definition, 26-11, 26-38
EJB specifying the class name, 26-39
security in EJB Web services, 28-3 workflow participant type, 26-11, 26-38
support in workflow services, 28-1
elements
ignoring in XSLT documents, 4-32
F
e-mail facades
dynamically setting addresses, 23-11 See XML facades
making e-mails actional, 26-56, 28-24 fault bindings, 7-4
notifications support, 23-2, 23-5 fault handling, 6-19, 17-5
e-mail attachments binding faults demo, 17-5
notifications support, 23-6 defining, 17-1, 17-5
e-mail messages importing RuntimeFault.wsdl, 17-5
HTML content for message body, 23-9 modifying the WSDL files, 17-5
empty activity returning external faults, 17-7
definition, 17-8 throwing internal faults, 17-6
fault handling, 17-8 use case, 17-1
emulation tests using catch branches, 17-7
overview, 43-2 using compensate activities, 17-8
emulations using empty activities, 17-8
emulating inbound messages, 43-9 using scope activities, 17-6, 17-7
in BPEL test suites, 43-4 using terminate activities, 17-9
ending using the getFaultAsString function, 17-5
tasks, 26-46 using throw activities, 17-6
enterprise message sources, 36-1 fault policies, 7-1
enterprise message sources, copying, 36-10 actions, 7-4
enterprise message sources, defining, 33-2, 36-2 component level, 7-4
enterprise message sources, deleting, 33-2, 36-10 composite level, 7-4
enterprise message sources, editing, 33-2, 36-10 conditions, 7-2
entity variable fault sensors
using, 12-4 definition, 24-2
Beta Draft -5
fault-bindings.xml, 7-9 G
fault-policies.xml, 7-5
faults genEmptyElem function
categories of faults in BPEL, 17-3 description, 12-24
Qname fault name, 17-3 getCurrentDate function
returning external faults, 17-7 description, 12-13
standard faults, 17-3 getCurrentDateTime function
throwing internal faults, 17-6 description, 12-13
fields, calculated, 32-4 getCurrentTime function
fields, lookup, 32-3 description, 12-13
fields, timestamp, 32-4 getFaultAsString function
filters, copying, 32-12 description, 17-5
filters, security, 32-10 getUserProperty function
fire and forget example, 23-11
one-way message, 22-1 getVariableData function
flat query, 35-6 description, 12-12
flowN activity example, 23-11
definition, 15-2 using in mathematical calculations, 12-11
folder permissions, 32-9 global task variable name
folders, deleting, 32-10 specifying in human task activities, 26-78
folders, renaming, 32-10 group query, 35-6
functions group vote
chaining in transformations, 4-16 configuring, 26-27
concat, 12-12 consensus percentage, 26-30
countNodes, 12-22 default outcome, 26-30
custom, 12-4 definition, 26-11, 26-27
deprecated workflow service and identity service immediately triggering a voted outcome when a
functions, 28-37 minimum percentage is met, 26-30
descriptions, 4-15 specifying group voting details, 26-30
dynamically setting e-mail addresses and waiting until all votes are in before triggering an
telephone numbers, 23-11 outcome, 26-30
editing in transformations, 4-16 workflow participant type, 26-11, 26-27
editing XPath expressions in
transformations, 4-19 H
examples, 12-3
headers
functions prefixed with xp20 or orcl, 4-15
SOAP headers, 12-27
genEmptyElem, 12-24
heap size
getCurrentDate, 12-13
increasing, 4-39
getCurrentDateTime, 12-13
human task activity
getCurrentTime, 12-13
associating with a BPEL process, 26-69
getFaultAsString, 17-5
identification key, 26-78
getUserProperty, 23-11
including the task history of other tasks, 26-78
getVariableData, 23-11
scope name and global task variable name, 26-78
in transformations, 4-15
specifying a task initiator and task priority, 26-72
location of function descriptions, 12-4
specifying a task title, 26-71
mimic XPath 2.0 standards, 28-36
specifying task parameters, 26-72
parseEscapedXML, 12-25
task owner, 26-78
position, 12-21
viewing BPEL callbacks, 26-75
prefixed with xp20 or orcl, 4-15
human task definition
processXSLT, 23-9
associating with a BPEL process, 26-12
readFile, 23-8
Human Task editor
selecting an data sequence element, 12-21
abruptly completing a condition, 26-41
workflow related, 28-36
actional e-mails, 26-56, 28-24
FYI assignee
allowing all participants to invite other
configuring, 26-37
participants, 26-40
definition, 26-11, 26-37
assigning task participants by name or
workflow participant type, 26-11, 26-37
expression, 26-25, 26-29, 26-32, 26-35, 26-37
bypassing task participants, 26-26, 26-30, 26-33,
26-36
definition, 26-2
-6 Beta Draft
dynamically assigning task participants by specifying in human task activities, 26-78
expression, 26-26, 26-29, 26-33, 26-36, 26-38 identity service
editing notification messages, 26-55 definition, 26-8, 28-8
escalate after policy, 26-51 deprecated functions, 28-37
escalating, renewing, or ending a task, 26-46 determining a user’s local language and time
escalation and expiration policy overview, 26-47 zone, 29-45
escalation rules, 26-58 EJB, SOAP, and Java support, 28-2, A-5
expire after policy, 26-49 providers, 28-10
external routing service task participant, 26-38 support for in workflows, 28-8
FYI assignee task participant, 26-37 supported task operations, 28-8
group vote task participant, 26-27 use with custom plug-ins, 28-10
group voting details, 26-30 use with JAZN, 28-8, 28-10
inviting additional task participants, 26-27, 26-34, use with LDAP, 28-8, 28-10
26-36 WSDL file location, 28-2
management chain task participant, 26-31 XPath extension functions, 28-36
multilingual settings, 26-59, 28-23 import
never expire policy, 26-49 source and target schemas into a
notification preferences, 26-53 transformation, 4-3
notifying recipients of changes to task two schema files of the same name into the same
status, 26-54 project is not supported, 11-12
number of task approvers, 26-33 indexes, in data objects, 32-14
overriding default exception management, 26-60 indexing methods
renew after policy, 26-50 using XPath, 12-22
securing notifications, 26-56, 28-28 instances
sequential list of approvers task starting new, 14-6
participant, 26-34 interaction patterns
setting up reminders, 26-55 asynchronous interaction with notification
sharing attachments and comments with task timer, 22-4
participants, 26-30, 26-38 asynchronous interaction with timeout, 22-4
single approver task participant, 26-24 asynchronous interactions, 22-3
specifying callback classes, 26-61 common patterns between a BPEL process and
specifying class names, 26-39 another application, 22-1
style sheets in attachments, 26-59 multiple interactions, 22-9
task attachments with e-mail notifications, 26-57, one request, a mandatory response, and an
28-27 optional response, 22-7
task outcome, 26-17 one request, multiple responses, 22-5
task owner specification through the user one request, one of two possible responses, 22-6
directory, 26-18 one-way message, 22-1
task owner specification through XPath partial processing, 22-8
expressions, 26-20 synchronous interactions, 22-2
task participants, 26-22 invocation patterns
task payload data structure, 26-21 assert facts and execute rule set operation
task routing and customization in BPEL definition, 25-16
callbacks, 26-62, 26-79 assert facts only operation definition, 25-16
task title and priority, 26-16 assert facts, execute rule set, and retrieve results
time limits for acting on tasks, 26-27, 26-31, 26-34, operation definition, 25-17
26-36 assert facts, execute rule set, retrieve results, and
WordML style sheets in attachments, 26-59 reset the session operation definition, 25-17
execute function and reset the session operation
definition, 25-17
I
execute function operation definition, 25-17
ICommand retrieve results operation definition, 25-17
regular expressions, 37-19 invoke activity, 14-5
sample export file, 37-18 adding to an asynchronous service, 14-11
ICommand utility, 37-1 definition, 13-2
ICommand, detailed command descriptions, 37-6 in asynchronous services, 14-5, 14-11
ICommand, general command and option in synchronous services, 13-2, 13-4
syntax, 37-2
ICommand, summary of commands, 37-5
identification key
Beta Draft -7
J lookupValue1M function, 9-10
Java
support in workflow services, 28-1 M
Java applications management chain
wrapped as SOAP services, 18-1 configuring, 26-31
Java embedding definition, 26-11, 26-31
bpelx:exec extension, 18-4 highest title of approver, 26-34
embedding code in a BPEL process, 18-2 maximum number of chain levels up, 26-33
example, 18-5 workflow participant type, 26-11, 26-31
in a BPEL process, 18-1 map parameters
using bpelx exec, 18-2 creating in transformations, 4-29
Javadocs map variables
location of, 28-11 creating in transformations, 4-29
Java/JSP applications master and detail process coordinations, 21-1
calling a BPEL process, 20-1 maxOccurs attribute, 12-20, 12-22
JAZN setting for transformations, 4-39
storing a user’s local language and time mediator component
zone, 29-45 mediator files, 5-3
use with identity service, 28-8, 28-10 Mediator Creation
JMS adapter Specifying Operation or Event Subscription
sensor publish type, 24-2 Properties, 5-19
JMS Queue Mediator Designer Environment
sensor publish type, 24-2 Application Navigator, 5-2
JMS Topic History Window, 5-4
sensor publish type, 24-2 Log Window, 5-4
JUnit Mediator Editor, 5-3
BPEL test results, 43-22 Property Inspector, 5-4
Source View, 5-4
L Structure Window, 5-4
Mediator Editor, 5-3
languages
Mediator Files
changing, 29-46
.componentType, 5-3
preferences, 29-45
Composite.xml, 5-3
setting in JAZN, 29-45
.mplan, 5-3
setting in LDAP, 29-45
.wsdl, 5-3
layouts, data object, 32-7
message source advanced formatting, 36-4
LDAP
message source example code, 36-5
storing a user’s local language and time
message sources, 36-1
zone, 29-45
minOccurs attribute
used with identity service, 28-8, 28-10
setting for transformations, 4-40
literal strings
modes
assigning, 12-12
xref
literal XML
populateXRefRow function, 10-7
variable initialization, 12-9
populateXRefRow1M function, 10-12
localization, worklist, 29-45
Modifying a Mediator, 5-20
log files
Modifying Event Subscriptions, 5-21
viewing, 3-11
Modifying Operations, 5-20
Log window
modifying cross reference tables
definition, 11-12
adding a column, 10-6
location of in Oracle JDeveloper, 11-4
deleting a column, 10-7
logging
Modifying Mediator Event Subscriptions, 5-21
BPEL process properties, 3-14
Modifying Mediator Operations, 5-20
looking up cross reference tables, 10-13
multilingual settings
xref
specifying in tasks, 26-59, 28-23
lookupXRef function, 10-13
myRole attribute
lookupXRef1M function, 10-16
definition, 14-5
lookup fields, 32-3
lookupValue functions
dvm
lookupValue function, 9-9
-8 Beta Draft
N Oracle BAM
See Oracle Business Activity Monitoring
named templates
Oracle BAM Server
creating, 4-17
creating a BPEL sensor, 24-17
in functions, 4-17
creating a BPEL sensor action, 24-17
naming conventions
creating a connection to, 24-16
for BPEL projects, 11-3
Oracle BPEL Server
NLS
overview, 11-18
configuration overview, 28-38
Oracle BPEL Worklist Application
notification messages
responding to tasks from, 26-1
editing, 26-55
Oracle Business Activity Monitoring
notification services
creating a BPEL sensor action for Oracle BAM
actionable e-mails, 28-24
Server, 24-17
configuring the notification channel, 28-21
creating a BPEL sensor for Oracle BAM
definition, 26-8, 28-11
Server, 24-17
limitations on setting validateXML to true, 23-13
creating a connection to Oracle BAM
multilingual settings, 28-23
Server, 24-16
notification contents, 28-22
definition
reliability support, 28-27
integration with Oracle BPEL Process Manager
sending inbound and outbound
sensors, 24-15
attachments, 28-27
message batching limitations, 24-19
sending inbound comments, 28-27
overview, 24-15
sending reminders, 28-28
Oracle Business Rules RL Language
sending secure notifications, 28-28
definition, 25-3
specifying participant notification
Oracle Business Rules Rule Author
preferences, 26-53
definition, 25-3
WSDL file location, 28-2
Oracle Business Rules Rules Engine
notifications
definition, 25-3
configuring in Oracle JDeveloper, 23-3
Oracle Business Rules SDK
definition, 23-1, 26-2
definition, 25-3
dynamically setting e-mail addresses and
Oracle Enterprise Service Bus
telephone numbers, 23-11
overview, 1-4
e-mail attachment support, 23-6
Oracle Internet Directory
e-mail support, 23-2, 23-5
storing a user’s local language and time
formatting the e-mail message body as
zone, 29-45
HTML, 23-9
Oracle JDeveloper, 11-5, 11-7
number of retries, 23-3
adapters, 11-18
number of retry intervals, 23-3
Application Navigator, 11-5
reliable notification service, 23-3
Component Palette, 11-9, 11-10
selecting recipients by browsing the user
configuring notifications, 23-3
directory, 23-12
creating sensors, 24-2
SMS support, 23-9
deploying test suites, 43-21
use case, 23-1
location of Application Navigator, 11-4
using Oracle Application Server Wireless, 23-2
location of Component Palette, 11-4
voice mail support, 23-10
location of Diagram window, 11-4
notifications and reminders
location of Log window, 11-4
in tasks, 28-20
location of Process Activities, 11-4
numeric values
location of Property Inspector, 11-4
assigning, 12-11
location of Structure window, 11-4
Log window, 11-12
O overview of design environment, 11-2
Process Activities, 11-9
obant
Property Inspector, 11-11
using the developer prompt, 11-2
Services, 11-10
onAlarm branch
Structure window, 11-11
of pick activity, 19-2
transformations, 4-1
one-to-many mapping, 9-3
Oracle Mediator
onMessage branch
define routing rules, 6-2
of pick activity, 19-2
overview, 5-1
Oracle Application Server Wireless
routing rules, 6-1
wireless and voice component, 23-2
Beta Draft -9
Oracle Mediator component creation onMessage branch, 19-2
mediator files, 5-3 populating cross reference tables, 10-7
Oracle Mediator error handling xref
actions, 7-4 populateXRefRow function, 10-7
conditions, 7-2 populateXRefRow1M function, 10-12
fault bindings, 7-4 port types
fault policies, 7-1 definition, 13-4
introduction, 7-1 in asynchronous services, 14-3
using, 7-5 in synchronous services, 13-4
XML schema files, 7-5 ports
Oracle SOA Suite in synchronous services, 13-2
components, 1-3 position function
introduced, 1-2 description, 12-21
organizing data objects, 32-8 Priority property, 5-19
overview, 24-1 Process Activities
definition, 11-9
location of in Oracle JDeveloper, 11-4
P
process code coverage tests
parallel flows overview, 43-3
definition, 15-1 process initiation
use case, 15-1 in BPEL test suites, 43-3
parseEscapedXML function processes
description, 12-25 naming conventions, 11-3
partial processing processXSLT function
BPEL process as the client, 22-9 example, 23-9
BPEL process as the service, 22-9 projects
definition, 22-8 BPEL file, 11-5
participant types importing two schema files of the same name into
external routing service, 26-11, 26-38 the same project is not supported, 11-12
FYI assignee, 26-11, 26-37 in Application Navigator, 11-5
group vole, 26-11, 26-27 naming conventions, 11-3
management chain, 26-11, 26-31 WSDL file, 11-5
sequential list of approvers, 26-11, 26-34 property aliases
single approver, 26-10, 26-24 creating for correlation sets, 14-23
partner links Property Inspector
adding to an asynchronous service, 14-10 definition, 11-11
BPEL file code example, 13-2 location of in Oracle JDeveloper, 11-4
definition, 11-14, 13-2 public views
displaying in Diagram window, 11-7 BPEL_ACTIVITY_SENSOR_VALUES, 24-21
in asynchronous services, 14-4, 14-10 BPEL_FAULT_SENSOR_VALUES, 24-21
in synchronous services, 13-2 BPEL_PROCESS_INSTANCES, 24-20
overview, 11-14 BPEL_VARIABLE_SENSOR_VALUES, 24-22
specifying a WSDL file, 11-14 sensors, 24-19
partnerLinkTypes publish types
definition, 13-3, 14-3 creating a custom publisher, 24-8
in asynchronous services, 14-3 custom, 24-2
in synchronous services, 13-3 database, 24-2
partnerRole attribute definition, 24-2
definition, 14-5 JMS Adapter, 24-2
patterns JMS Queue, 24-2
of interaction between a BPEL process and another JMS Topic, 24-2
application, 22-1
permissions, copying, 32-5
permissions, data objects, 32-4
Q
permissions, setting on folders, 32-9 Qname
pick activity fault name, 17-3
code example, 19-3 qualifier, 9-2
condition branches, 19-2 qualifier order, 9-2
for timeouts, 19-1 qualifier order, 9-2
onAlarm branch, 19-2