Oracle BPEL Process Manager Developer'

Oracle® BPEL Process Manager
Developer’s Guide
10g (10.1.3.1.0)
B28981-01
September 2006
Oracle BPEL Process Manager Developer’s Guide, 10g (10.1.3.1.0)
B28981-01
Copyright © 2005, 2006, Oracle. All rights reserved.
Primary Author:
Contributor:
teams
Deanna Bradshaw and Mark Kennedy
Oracle BPEL Process Manager development, product management, and quality assurance
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.
Contents
Preface ............................................................................................................................................................. xxiii
Audience...................................................................................................................................................
Documentation Accessibility .................................................................................................................
Related Documents .................................................................................................................................
Conventions .............................................................................................................................................
xxiii
xxiii
xxiv
xxiv
What’s New in Oracle BPEL Process Manager?................................................................... xxvii
Part I
1
Introduction and Concepts
Introduction to Oracle BPEL Process Manager
What Is BPEL? ........................................................................................................................................... 1-1
What Is Oracle BPEL Process Manager? .............................................................................................. 1-2
What Is Oracle JDeveloper? ................................................................................................................... 1-3
How to Use This Guide........................................................................................................................... 1-4
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials..... 1-6
What Demonstrations Are Available? ............................................................................................ 1-7
What Activity and Conceptual References Are Available? ......................................................... 1-8
What Tutorials Are Available?...................................................................................................... 1-10
Summary ................................................................................................................................................. 1-15
2
Getting Started with Oracle BPEL Process Manager
Overview of Oracle BPEL Process Manager Components ............................................................... 2-1
Starting Oracle BPEL Process Manager Components ....................................................................... 2-2
Overview of the BPEL Designer Environment................................................................................... 2-3
Overview of BPEL Project Creation and Oracle JDeveloper ....................................................... 2-3
Application Navigator ............................................................................................................... 2-5
Diagram Window ....................................................................................................................... 2-6
Source Window ........................................................................................................................... 2-8
History Window.......................................................................................................................... 2-9
Component Palette .................................................................................................................. 2-10
Property Inspector ................................................................................................................... 2-12
Structure Window.................................................................................................................... 2-12
Log Window ............................................................................................................................. 2-13
Editing Project Files in Oracle JDeveloper ........................................................................... 2-14
iii
Overview of Activities..........................................................................................................................
Overview of Partner Links ..................................................................................................................
Overview of Oracle BPEL Server .......................................................................................................
Overview of Oracle BPEL Control .....................................................................................................
Overview of Oracle BPEL Process Manager Services ....................................................................
Overview of Oracle BPEL Process Manager Technology Adapters.............................................
Summary .................................................................................................................................................
Part II
3
2-15
2-16
2-17
2-17
2-18
2-20
2-21
Reviewing Key BPEL Development Concepts and Code Samples
Manipulating XML Data in BPEL
Use Cases for Manipulating XML Data in BPEL ............................................................................... 3-1
Overview of Manipulating XML Data in BPEL Concepts ............................................................... 3-2
How XML Data Works in BPEL....................................................................................................... 3-2
About Data Manipulation and XPath Standards .......................................................................... 3-2
Initializing a Variable with Expression Constants or Literal XML ................................................ 3-4
Copying Between Variables ................................................................................................................... 3-5
Accessing Fields Within Complex Type Variables ............................................................................ 3-5
Assigning Numeric Values ..................................................................................................................... 3-6
Mathematical Calculations with XPath Standards ............................................................................ 3-6
Assigning String Literals ........................................................................................................................ 3-7
Concatenating Strings ............................................................................................................................. 3-7
Assigning Boolean Values ...................................................................................................................... 3-8
Assigning Date or Time .......................................................................................................................... 3-8
Manipulating Attributes ......................................................................................................................... 3-9
Manipulating XML Data Sequences That Use Arrays...................................................................... 3-9
Statically Indexing into an XML Data Sequence That Uses Arrays......................................... 3-10
Determining Sequence Size ........................................................................................................... 3-11
Dynamically Indexing by Applying a Trailing XPath to an Expression................................. 3-11
Dynamic Indexing Example ................................................................................................... 3-11
Using the bpel:append Extension to Append New Items to a Sequence ........................ 3-12
Merging Data Sequences......................................................................................................... 3-12
Dynamically Indexing with the BPEL getElement Function............................................. 3-13
SOAP-Encoded Arrays Not Supported ....................................................................................... 3-13
Converting from a String to an XML Element................................................................................. 3-14
Differences Between Document-Style and RPC-Style WSDL Files ........................................... 3-14
Enclosing the Operation Name with RPC-Style WSDL Messages .......................................... 3-15
Using Binary Attachments in SOAP Messages ............................................................................... 3-16
Use Case: SOAP Message with Binary Attachment Using MIME........................................... 3-17
WSDL File Contents ................................................................................................................ 3-18
BPEL File Contents .................................................................................................................. 3-20
Java Client Using SAAJ ........................................................................................................... 3-21
Displaying the Attachment Key for Binary Attachments Using the DIME Protocol in
Oracle BPEL Control....................................................................................................................... 3-24
Summary ................................................................................................................................................. 3-24
iv
4
Invoking a Synchronous Web Service
Use Case for Synchronous Web Services.............................................................................................
Overview of Synchronous Service Concepts......................................................................................
Establishing the Partner Link ...........................................................................................................
Defining the Partner Link in the BPEL Code ..........................................................................
Using the WSDL File to Enable the Web Services to Work with a BPEL Process .............
Performing Lookups for Services that Use Partner Links.....................................................
Accessing Web Services on Remote Servers ...........................................................................
Using the Invoke Activity to Perform a Request...........................................................................
Calling a Synchronous Service ..............................................................................................................
Summary ....................................................................................................................................................
5
4-1
4-2
4-2
4-2
4-3
4-4
4-4
4-5
4-5
4-7
Invoking an Asynchronous Web Service
Use Case for Asynchronous Web Services .......................................................................................... 5-1
Overview of Asynchronous Callback Concepts................................................................................. 5-3
partnerLinkTypes for Asynchronous Services .............................................................................. 5-3
Calling the Service from BPEL ......................................................................................................... 5-4
How the Invoke and Receive Activities Work............................................................................... 5-5
Managing Multiple Active BPEL Process Instances Using Correlation Methods .................... 5-7
WS-Addressing ........................................................................................................................... 5-7
Using Correlation Sets to Coordinate Asynchronous Message Body Contents ............. 5-10
Using the Reply Activity to Send Messages in Response to a Receive Activity ................... 5-10
Using Dehydration Points to Maintain Long-Running Asynchronous Processes ................ 5-10
Calling an Asynchronous Service ...................................................................................................... 5-11
Step 1: Adding a Partner Link for an Asynchronous Service ................................................... 5-11
Step 2: Adding an Invoke Activity ............................................................................................... 5-12
Step 3: Adding a Receive Activity ................................................................................................ 5-13
Step 4: Performing Additional Activities..................................................................................... 5-14
Using Correlation Sets in an Asynchronous Service...................................................................... 5-14
Step 1: Creating a Project ............................................................................................................... 5-15
Step 2: Configuring Partner Links and File Adapter Services.................................................. 5-15
Creating an Initial Partner Link and File Adapter Service ................................................ 5-15
Creating a Second Partner Link and File Adapter Service ................................................ 5-17
Creating a Third Partner Link and File Adapter Service ................................................... 5-18
Step 3: Creating Three Receive Activities .................................................................................... 5-19
Creating an Initial Receive Activity ...................................................................................... 5-19
Creating a Second Receive Activity ...................................................................................... 5-20
Creating a Third Receive Activity ......................................................................................... 5-20
Step 4: Creating Correlation Sets .................................................................................................. 5-21
Creating an Initial Correlation Set......................................................................................... 5-21
Creating a Second Correlation Set......................................................................................... 5-21
Step 5: Associating Correlation Sets with Receive Activities ................................................... 5-22
Associating the First Correlation Set with a Receive Activity........................................... 5-22
Associating the Second Correlation Set with a Receive Activity ...................................... 5-22
Associating the Third Correlation Set with a Receive Activity......................................... 5-23
Step 6: Creating Property Aliases ................................................................................................. 5-24
v
Creating Property Aliases for NameCorr.............................................................................
Creating Property Aliases for IDCorr ...................................................................................
Step 7: Reviewing WSDL File Content.........................................................................................
Summary .................................................................................................................................................
6
Parallel Flow
Use Case for Parallel Flows ....................................................................................................................
Overview of Parallel Flow Concepts ....................................................................................................
Defining a Parallel Flow .........................................................................................................................
Customizing the Number of Flow Activities by Using the flowN Activity .................................
BPEL Code Example of the FlowN Activity ..................................................................................
Summary ....................................................................................................................................................
7
6-1
6-1
6-2
6-4
6-6
6-7
Conditional Branching
Use Case for Conditional Branching ....................................................................................................
Overview of Conditional Branching Concepts ..................................................................................
Using a Switch Activity to Define Conditional Branching..............................................................
Using a While Activity to Define Conditional Branching ...............................................................
Summary ....................................................................................................................................................
8
5-24
5-24
5-25
5-26
7-1
7-1
7-2
7-4
7-5
Fault Handling
Use Case for Fault Handling .................................................................................................................. 8-1
Overview of Fault Handling Concepts ................................................................................................ 8-1
Defining a Fault Handler........................................................................................................................ 8-2
Types of BPEL Faults ............................................................................................................................... 8-3
Using the Scope Activity to Manage a Group of Activities ............................................................. 8-3
Throwing Internal Faults ........................................................................................................................ 8-4
Returning External Faults ....................................................................................................................... 8-4
Returning a Fault in a Synchronous Interaction............................................................................ 8-4
Returning a Fault in an Asynchronous Interaction....................................................................... 8-5
Using a Fault Handler within a Scope ................................................................................................. 8-5
Using the Empty Activity to Insert No-Op Instructions into a Business Process..................... 8-5
Using Compensation After Undoing a Series of Operations .......................................................... 8-6
Using the Terminate Activity to Stop a Business Process Instance ................................................ 8-7
Catching Run-Time Faults Example ..................................................................................................... 8-8
Fault Handling Example ......................................................................................................................... 8-8
Summary ................................................................................................................................................. 8-10
9
Incorporating Java and J2EE Code in BPEL Processes
Overview of Java and J2EE Code in BPEL Concepts.........................................................................
Using Java Code with WSIF Binding ..............................................................................................
Using Java Code Wrapped as a SOAP Service ..............................................................................
Directly Embedding Java Code in a BPEL Process .......................................................................
Using the bpelx:exec Tag to Embed Java Code Snippets into a BPEL Process ..................
Using an XML Facade to Simplify DOM Manipulation........................................................
bpelx:exec Built-in Methods ......................................................................................................
vi
9-1
9-1
9-2
9-2
9-2
9-3
9-4
Using Java Embedding in a BPEL Process........................................................................................... 9-5
Summary .................................................................................................................................................... 9-6
10
Events and Timeouts
Use Case for Events and Timeouts.....................................................................................................
Overview of Event and Timeout Concepts.......................................................................................
Using the Pick Activity to Select Between Continuing a Process or Waiting............................
Using the Wait Activity to Set an Expiration Time .........................................................................
Setting Timeouts for Synchronous Processes ..................................................................................
Defining a Timeout...............................................................................................................................
Summary .................................................................................................................................................
11
Invoking a BPEL Process
Use Case for Invoking a BPEL Process..............................................................................................
Overview of Invoking BPEL Process Concepts...............................................................................
Sending Messages to a BPEL Process from a Java or JSP Application .......................................
Invoking a BPEL Process with the Generic Java API.................................................................
Connecting to Oracle BPEL Process Manager with the Locator Class.............................
Passing XML Messages Through Java ..................................................................................
Invoking a Two-Way Operation Through the Java API ....................................................
Invoking a One-Way Operation Through the Java API .....................................................
Retrieving Status or Results from Asynchronous BPEL Processes..........................................
Using the Java API from a Remote Client ...................................................................................
Invoking a BPEL Process with the Web Service/SOAP Interface ...........................................
Summary .................................................................................................................................................
12
11-1
11-1
11-1
11-2
11-2
11-3
11-3
11-4
11-5
11-5
11-6
11-6
Interaction Patterns
One-Way Message .................................................................................................................................
Synchronous Interaction......................................................................................................................
Asynchronous Interaction ...................................................................................................................
Asynchronous Interaction with Timeout..........................................................................................
Asynchronous Interaction with a Notification Timer....................................................................
One Request, Multiple Responses.....................................................................................................
One Request, One of Two Possible Responses ...............................................................................
One Request, a Mandatory Response, and an Optional Response .............................................
Partial Processing ..................................................................................................................................
Multiple Application Interactions ...................................................................................................
Summary ...............................................................................................................................................
Part III
13
10-1
10-1
10-2
10-4
10-4
10-4
10-6
12-1
12-2
12-3
12-4
12-5
12-6
12-7
12-8
12-9
12-10
12-11
Oracle BPEL Process Manager Services
XSLT Mapper and Transformations
Use Case for Transformation............................................................................................................... 13-1
Creating an XSL Map File.................................................................................................................... 13-1
Creating a New XSL Map File....................................................................................................... 13-2
vii
Creating an XSL Map File from Imported Source and Target Schema Files..........................
Overview of the XSLT Mapper ...........................................................................................................
Notes on the Mapper ......................................................................................................................
Using the XSLT Mapper.......................................................................................................................
Simple Copy by Linking Nodes....................................................................................................
Setting Constant Values .................................................................................................................
Adding Functions............................................................................................................................
Editing Function Parameters..................................................................................................
Chaining Functions................................................................................................................
Named Templates..................................................................................................................
Importing User-Defined Functions .....................................................................................
Editing XPath Expressions...........................................................................................................
Adding XSLT Constructs .............................................................................................................
Conditional Processing with xsl:if.......................................................................................
Conditional Processing with xsl:choose .............................................................................
Handling Repetition or Arrays ............................................................................................
Automatically Mapping Nodes ..................................................................................................
Auto Map with Confirmation ..............................................................................................
Viewing Unmapped Target Nodes ............................................................................................
Generating Dictionaries ...............................................................................................................
Creating Map Parameters and Variables...................................................................................
Creating a Map Parameter....................................................................................................
Creating a Map Variable .......................................................................................................
Searching Source and Target Nodes ..........................................................................................
Ignoring Elements in the XSLT Document................................................................................
Replacing a Schema in the XSLT Mapper..................................................................................
Testing the Map ...................................................................................................................................
Test XSL Map Window ................................................................................................................
Generating Reports .......................................................................................................................
Correcting Memory Errors When Generating Reports ....................................................
Sample XML Generation ..............................................................................................................
Summary ...............................................................................................................................................
14
Oracle BPEL Process Manager Notification Service
Use Cases for Notification Service.....................................................................................................
Overview of Notification Service Concepts.....................................................................................
Reliable Notification Service..........................................................................................................
Configuring the Notification Service in Oracle JDeveloper ........................................................
The E-mail Notification Channel ..................................................................................................
Setting E-mail Attachments ....................................................................................................
Formatting the Body of an E-mail Message as HTML .......................................................
The Fax Notification Channel........................................................................................................
The Pager Notification Channel..................................................................................................
The SMS Notification Channel....................................................................................................
The Voice Notification Channel ..................................................................................................
Setting E-mail Addresses and Telephone Numbers Dynamically ........................................
Selecting Notification Recipients by Browsing the User Directory .......................................
viii
13-3
13-5
13-6
13-6
13-7
13-7
13-8
13-9
13-10
13-10
13-10
13-11
13-12
13-12
13-13
13-14
13-15
13-17
13-18
13-19
13-19
13-20
13-20
13-21
13-22
13-23
13-23
13-24
13-26
13-27
13-27
13-28
14-1
14-1
14-2
14-3
14-4
14-5
14-8
14-8
14-10
14-11
14-12
14-13
14-14
Starting Business Processes with the E-mail Activation Agent.............................................. 14-14
XML Validation Failure with the Notification Service ............................................................ 14-15
Summary ............................................................................................................................................... 14-15
15
Oracle BPEL Process Manager Workflow Services
Oracle BPEL Process Manager Workflow Services 10.1.2 and 10.1.3.1.0 Compatibility ..........
Overview of Workflow Services.........................................................................................................
Workflow Functionality: A Procurement Process Example .....................................................
Workflow Services Components...................................................................................................
Use Cases for Workflow Services.......................................................................................................
Assigning a Task to a User or Role...............................................................................................
Using the Various Participant Types............................................................................................
Escalation, Expiration, and Delegation ......................................................................................
Automatic Assignment and Delegation.....................................................................................
Work Queues and Proxy Support...............................................................................................
The Oracle BPEL Worklist Application .....................................................................................
Participant Types in Workflow Services .........................................................................................
Continuing Workflows from Other Workflows .......................................................................
Overview of the Modeling Process..................................................................................................
Create a Human Task Definition with the Human Task Editor ............................................
Associate the Human Task Definition with a BPEL Process ..................................................
Generate the Task Display Form ................................................................................................
Task 1: Creating the Human Task Definition with the Human Task Editor............................
Accessing the Human Task Editor .............................................................................................
From the Application Navigator .........................................................................................
From the Component Palette ...............................................................................................
Reviewing the Sections of the Human Task Editor..................................................................
Specifying the Task Title, Priority, Outcome, and Owner ......................................................
Specifying a Task Title and Priority ....................................................................................
Specifying a Task Outcome ..................................................................................................
Specifying a Task Owner ......................................................................................................
Specifying the Task Payload Data Structure .............................................................................
Assigning Task Participants ........................................................................................................
Configuring the Single Approver Participant Type .........................................................
Configuring the Group Vote Participant Type..................................................................
Configuring the Management Chain Participant Type....................................................
Configuring the Sequential List of Approvers Participant Type....................................
Configuring the FYI Assignee Participant Type ...............................................................
Configuring the External Routing Service Participant Type ...........................................
Allowing All Participants to Invite Other Participants ....................................................
Abruptly Completing a Condition ......................................................................................
Escalating, Renewing, or Ending the Task ................................................................................
Overview or Escalation and Expiration Policy..................................................................
Never Expire Policy ...............................................................................................................
Expire After Policy.................................................................................................................
Renew After Policy ................................................................................................................
Escalate After Policy ..............................................................................................................
15-2
15-2
15-5
15-6
15-8
15-9
15-9
15-10
15-10
15-10
15-10
15-11
15-12
15-13
15-13
15-13
15-13
15-14
15-14
15-14
15-15
15-15
15-16
15-17
15-17
15-18
15-21
15-22
15-23
15-26
15-29
15-31
15-34
15-35
15-36
15-37
15-38
15-38
15-40
15-40
15-41
15-42
ix
Specifying Participant Notification Preferences .......................................................................
Notifying Recipients of Changes to Task Status ...............................................................
Editing the Notification Message ........................................................................................
Setting Up Reminders ...........................................................................................................
Securing Notifications, Making Messages Actionable, and Sending Attachments .....
Specifying Advanced Settings.....................................................................................................
Specifying Escalation Rules ..................................................................................................
Specifying WordML Style Sheets for Attachments...........................................................
Specifying Style Sheets for Attachments ............................................................................
Specifying Multilingual Settings..........................................................................................
Overriding Default System Actions ....................................................................................
Overriding Default Exception Management......................................................................
Specifying Callback Classes on Task Status.......................................................................
Allowing Task and Routing Customization in BPEL Callbacks .....................................
Exiting the Human Task Editor and Saving Your Changes ...................................................
Task 2: Associating the Human Task with a BPEL Process .........................................................
Associating a Human Worklist Task with a BPEL Process.....................................................
Opening a Human Task Activity Already Associated with a BPEL Process .......................
Defining the Human Task Activity Title, Initiator, Priority, and Parameter Variables......
Specifying the Task Title .......................................................................................................
Specifying the Task Initiator and Task Priority.................................................................
Specifying Task Parameters..................................................................................................
Defining the Human Task Activity Advanced Features ........................................................
Specifying a Scope Name and a Global Task Variable Name .........................................
Specifying a Task Owner ......................................................................................................
Specifying an Identification Key..........................................................................................
Including the Task History of Other Human Tasks .........................................................
Allowing Task and Routing Customizations in BPEL Callbacks ...................................
Viewing the Generated Human Task Activity .........................................................................
BPEL Callbacks.......................................................................................................................
Including the Task History from Other Workflows .........................................................
Outcome-Based Modeling ...........................................................................................................
Payload Updates ....................................................................................................................
Case Statements for Other Task Conclusions ....................................................................
Task 3: Generating the Task Display Form.....................................................................................
Overview of Task Display Forms ...............................................................................................
Selecting a Task Display Form ....................................................................................................
Preview Release of Task Display Form Support for ADF Data Controls......................
Automatically Generating a Simple Task Display Form.........................................................
Payload File for the Autogenerated JSP .............................................................................
Generating a Custom Task Display Form .................................................................................
Autogenerated JSP .................................................................................................................
Custom JSP..............................................................................................................................
Default JSP ..............................................................................................................................
XSL ...........................................................................................................................................
Deploying Task Display Forms...................................................................................................
Creating Custom JSP Forms ........................................................................................................
x
15-42
15-43
15-44
15-45
15-45
15-46
15-46
15-47
15-47
15-47
15-48
15-50
15-50
15-51
15-52
15-52
15-53
15-53
15-54
15-54
15-54
15-55
15-56
15-57
15-57
15-58
15-58
15-58
15-59
15-61
15-63
15-63
15-64
15-64
15-65
15-65
15-65
15-66
15-67
15-67
15-73
15-74
15-75
15-76
15-76
15-76
15-76
Adding Update Support in the Custom JSP ......................................................................
How Changes to a Workflow Appear in Worklist Application .................................................
Notifications from Workflow Services............................................................................................
Configuring the Notification Channel .......................................................................................
Contents of Notification ...............................................................................................................
Configuring Messages in Different Languages ........................................................................
Sending Actionable E-mails.........................................................................................................
Sending Inbound and Outbound Attachments ........................................................................
Sending Inbound Comments.......................................................................................................
Reliability Support ........................................................................................................................
Sending Secure Notifications.......................................................................................................
Channels Used for Notifications .................................................................................................
Sending Reminders .......................................................................................................................
End-to-End Workflow Examples ......................................................................................................
Vacation Request Example ..........................................................................................................
Prerequisites...................................................................................................................................
Modeling the Vacation Request Process....................................................................................
Creating the Vacation Request Process and Importing the Schema ..............................
Adding a Human Task to the Order Approval Process...................................................
Assigning Input and Output Parameters for the Human Task ......................................
Creating a Task Form for the Worklist ...............................................................................
Modeling the Task Outcome ................................................................................................
Validating, Compiling, and Deploying the Order Approval Process............................
Running the Order Approval Process ................................................................................
Workflow Services ..............................................................................................................................
EJB, SOAP, and Java Support for the Workflow Services.......................................................
Security Model for Services .........................................................................................................
Security in SOAP Web Services ...........................................................................................
Security in EJBs.......................................................................................................................
Creating Workflow Context on Behalf of a User...............................................................
Task Service....................................................................................................................................
Task Query Service .......................................................................................................................
Identity Service ............................................................................................................................
Creating Users and Groups ................................................................................................
Identity Service Providers ..................................................................................................
User and Role Properties ....................................................................................................
Multirealm Support .............................................................................................................
Authentication, Authorization, and Identity Service Providers ...................................
Notification Service.....................................................................................................................
Task Metadata Service................................................................................................................
User Metadata Service ................................................................................................................
Runtime Config Service..............................................................................................................
Internationalization of Attribute Labels ...........................................................................
Configuring the Assignment Service ............................................................................................
Dynamic Assignment Functions...............................................................................................
Implementing a Dynamic Assignment Function ............................................................
Configuring Dynamic Assignment Functions.................................................................
15-78
15-78
15-79
15-79
15-80
15-81
15-81
15-82
15-82
15-83
15-83
15-83
15-83
15-84
15-85
15-85
15-87
15-87
15-88
15-90
15-92
15-92
15-93
15-93
15-95
15-95
15-96
15-96
15-96
15-97
15-97
15-99
15-100
15-102
15-102
15-104
15-105
15-106
15-106
15-107
15-107
15-109
15-110
15-111
15-111
15-112
15-115
xi
Configuring Display Names for Dynamic Assignment Functions...............................
Dynamically Assigning Task Participants with the Assignment Service...........................
Assignment Service Overview...........................................................................................
Implementing an Assignment Service ..............................................................................
Example of Assignment Service Implementation ...........................................................
Custom Escalation Function ......................................................................................................
Workflow Service and Identity Service Related XPath Extension Functions .......................
Deprecated Workflow Service and Identity Service Functions............................................
NLS Configuration............................................................................................................................
Summary .............................................................................................................................................
15-115
15-116
15-116
15-116
15-117
15-119
15-119
15-120
15-121
15-121
16 Worklist Application
Use Cases for the Worklist Application ............................................................................................
Overview of Worklist Application Concepts...................................................................................
Worklist Application User Types .................................................................................................
Task Components............................................................................................................................
Features of the Worklist Application.................................................................................................
Using the Task Details Page ..........................................................................................................
Task Actions ...........................................................................................................................
Request Status ........................................................................................................................
Header Section........................................................................................................................
Payload Section ......................................................................................................................
Comments and Attachments Section ..................................................................................
History Section .......................................................................................................................
Routing ....................................................................................................................................
Requesting More Information..............................................................................................
Reassignment..........................................................................................................................
Parallel Tasks ..........................................................................................................................
Determining Action Permissions.........................................................................................
Using Advanced Search ...............................................................................................................
Viewing a Bar Chart of Task Status............................................................................................
Using Work Queues......................................................................................................................
Setting Preferences ........................................................................................................................
Vacation Preferences .............................................................................................................
My Rules..................................................................................................................................
Group Rules ............................................................................................................................
Custom Views.........................................................................................................................
Display Preferences ...............................................................................................................
Using the Administration Functions ..........................................................................................
Manage Rules .........................................................................................................................
Flex Field Mappings ..............................................................................................................
Application Customization ..................................................................................................
Creating Reports............................................................................................................................
Unattended Tasks Report .....................................................................................................
Tasks Priority Report.............................................................................................................
Tasks Cycle Time Report ......................................................................................................
Tasks Productivity Report ....................................................................................................
xii
16-1
16-2
16-3
16-3
16-4
16-8
16-10
16-11
16-13
16-13
16-13
16-14
16-15
16-15
16-15
16-17
16-17
16-17
16-19
16-20
16-21
16-21
16-22
16-24
16-25
16-26
16-27
16-27
16-28
16-32
16-33
16-34
16-35
16-36
16-37
User and Group Information.......................................................................................................
Accessing the Worklist Application in Local Languages ............................................................
Customizing the Worklist Application ...........................................................................................
Worklist Application Architecture .............................................................................................
Customizing the Login Page ................................................................................................
Customizing Header Information .......................................................................................
Customizing the Task Details Page.....................................................................................
Changing the Client-Service Binding for the Worklist Application...............................
Deploying the Custom Application ....................................................................................
Customizing the Worklist Application Using Preferences..............................................
Configuring Display Names for Task Attributes Using WorkflowLabels.properties .
Controlling Access to Information and Actions for Different Users .....................................
Building Clients for Workflow Services.........................................................................................
Packages and Classes for Building Clients................................................................................
Workflow Service Client ..............................................................................................................
The IWorkflowServiceClient Interface ...............................................................................
Classpaths for Java Clients ..........................................................................................................
EJB References in Web Applications ..........................................................................................
Initiating a Task .............................................................................................................................
Creating a Task.......................................................................................................................
Creating a Payload Element in a Task ................................................................................
Initiating a Task Programmatically .....................................................................................
Writing a Worklist Application Using the HelpDeskUI Sample ...........................................
Summary ...............................................................................................................................................
17
16-39
16-39
16-41
16-41
16-44
16-44
16-45
16-45
16-46
16-46
16-46
16-47
16-48
16-50
16-50
16-52
16-53
16-53
16-54
16-54
16-55
16-55
16-56
16-63
Sensors
Use Cases for Sensors ...........................................................................................................................
Overview of Sensor Concepts.............................................................................................................
Implementing Sensors and Sensor Actions in Oracle JDeveloper..............................................
Configuring Sensors .......................................................................................................................
Configuring Sensor Actions...........................................................................................................
Publishing to Remote Topics and Queues...................................................................................
Creating a Custom Data Publisher ...............................................................................................
Registering the Sensors and Sensor Actions in bpel.xml ........................................................
Sensors and Oracle BPEL Control....................................................................................................
Viewing Sensor and Sensor Action Definitions........................................................................
Viewing Sensor Data ....................................................................................................................
Sensor Integration with Oracle Business Activity Monitoring..................................................
Creating a Connection to Oracle BAM Server ..........................................................................
Creating a Sensor...........................................................................................................................
Creating a BAM Sensor Action ...................................................................................................
Sensor Public Views ...........................................................................................................................
BPM Schema ..................................................................................................................................
Sensor Actions XSD File ....................................................................................................................
Summary ...............................................................................................................................................
17-1
17-1
17-2
17-3
17-6
17-8
17-8
17-11
17-11
17-11
17-12
17-13
17-14
17-15
17-15
17-18
17-18
17-23
17-31
xiii
18
BPEL Process Integration with Business Rules
Business Rules and Decision Service Concepts ..............................................................................
Business Rules and Business Rule Engines .................................................................................
Decision Service...............................................................................................................................
Oracle Business Rules with Oracle BPEL Process Manager .....................................................
Decision Service Architecture.............................................................................................................
Decision Service Components .......................................................................................................
Interaction with Other Components ............................................................................................
Contents of Decision Service Configuration File........................................................................
Use Cases for Integration of Business Processes and Business Rules ........................................
Integration of BPEL Processes with Business Rules ......................................................................
Create Rule Engine Connection Wizard ......................................................................................
Decision Service Wizard ................................................................................................................
Selecting an Invocation Pattern............................................................................................
Selecting a Business Rule ......................................................................................................
Specifying Input and Output Facts .....................................................................................
Importing Schema Files.........................................................................................................
Decide Activity ..............................................................................................................................
Mapping Input and Output Facts to BPEL Variables.......................................................
Methodology for Rule Set Modeling and Integration with a BPEL Process ...........................
Recommended Methodology ......................................................................................................
Methodology One: Modeling Fact Types Based on an XML Schema ...................................
Task 1: Create a Data Model for Rule Authoring..............................................................
Task 2: Create a New Rule Repository and Dictionary in the Rule Author..................
Task 3: Import the XML Schema into the Data Model of the Rule Dictionary .............
Task 4: Create a New Rule Set and Model Rules ..............................................................
Methodology Two: Modeling Rules Based on Existing RL or JavaBeans Fact Types ........
Task 1: Define a Contract between BPEL and Business Rules ........................................
Task 2: Create a New Data Model Using the RL Fact Types ...........................................
Task 3: Create a New Rule Set and Rules...........................................................................
Task 4: Create the RL Function Contract............................................................................
Invoking the Sample Rule Set from a BPEL Process................................................................
Task 1: Create a Connection to the Rule Engine................................................................
Task 2: Create a BPEL Project...............................................................................................
Task 3: Create a Decision Service Partner Link .................................................................
Task 4: Create a Decide Activity ..........................................................................................
Summary of Methodology...........................................................................................................
Decision Service Deployment and Run Time ...............................................................................
Decision Service Partner Link Directory Structure ..................................................................
Deployment....................................................................................................................................
Run Time ........................................................................................................................................
Oracle Enterprise Manager 10g Application Server Control Console Support ............
Oracle BPEL Control Support ..............................................................................................
Advanced Decision Service Features...............................................................................................
Using WSIF Bindings....................................................................................................................
Enabling Logging of Oracle Business Rules Rule Session Events..........................................
Customizing assertXPath .............................................................................................................
xiv
18-1
18-1
18-2
18-2
18-3
18-4
18-4
18-5
18-7
18-7
18-7
18-9
18-10
18-11
18-12
18-13
18-14
18-14
18-17
18-17
18-17
18-18
18-19
18-20
18-23
18-28
18-28
18-28
18-30
18-31
18-33
18-33
18-33
18-34
18-36
18-39
18-39
18-39
18-42
18-43
18-43
18-45
18-47
18-47
18-48
18-50
Example of BPEL Process Integration with Business Rules .......................................................
Task 1: Update a Rule Using Oracle Business Rules Rule Author.........................................
Task 2: Create a Connection to the Business Rule Repository................................................
Task 3: Create a BPEL Process and Import the Schema ..........................................................
Task 4: Create a Decision Service Partner Link ........................................................................
Task 5: Create a Decide Activity .................................................................................................
Part IV
19
Development and Deployment Life Cycle
BPEL Process Deployment and Domain Management
Compiling and Deploying a BPEL Process ......................................................................................
Compiling and Deploying in Oracle JDeveloper .......................................................................
Compiling Without Deploying in Oracle JDeveloper ........................................................
BPEL Suitcase JAR File ...................................................................................................................
Creating and Managing a BPEL Domain..........................................................................................
Logging into Domains ....................................................................................................................
Changing Domain Passwords .......................................................................................................
Creating a BPEL Domain ...............................................................................................................
Changing Oracle BPEL Server Mode ...........................................................................................
Deploying a BPEL Suitcase to a Specific Domain ......................................................................
Undeploying a BPEL Process from a Specific Domain..............................................................
Managing Processes in Oracle BPEL Control ..................................................................................
Dashboard Tab: Viewing Deployed, Running, and Completed Processes ............................
Viewing and Changing Domains ........................................................................................
BPEL Processes Tab: Managing the Process Life Cycle...........................................................
Clearing the WSDL Cache ....................................................................................................
Deploying New Processes ....................................................................................................
Performing Manual Recovery ..............................................................................................
Refreshing the Alarm Table..................................................................................................
Viewing the Process Logs .....................................................................................................
Managing the Process Life Cycle.........................................................................................
Instances Tab: Viewing Process Instances .................................................................................
Activities Tab: Viewing Process Activities ................................................................................
Build and Command Line Tools.......................................................................................................
ant ....................................................................................................................................................
bpelc ................................................................................................................................................
Examples .................................................................................................................................
schemac...........................................................................................................................................
Examples .................................................................................................................................
Summary ...............................................................................................................................................
20
18-51
18-51
18-53
18-55
18-55
18-59
19-1
19-2
19-4
19-5
19-5
19-6
19-7
19-7
19-7
19-8
19-9
19-9
19-9
19-10
19-10
19-11
19-11
19-11
19-12
19-12
19-12
19-22
19-23
19-23
19-24
19-24
19-24
19-25
19-26
19-27
Testing BPEL Processes
Overview of the BPEL Test Framework ............................................................................................
Test Cases Overview.......................................................................................................................
Test Suites Overview ......................................................................................................................
Emulations Overview.....................................................................................................................
20-1
20-2
20-2
20-2
xv
Assertions Overview ......................................................................................................................
Process Code Coverage Overview................................................................................................
JUnit Support Overview ................................................................................................................
Components of a Test Suite.................................................................................................................
Process Initiation .............................................................................................................................
Emulations .......................................................................................................................................
Assertions .........................................................................................................................................
Include Files .....................................................................................................................................
Creating Test Suites in Oracle JDeveloper .......................................................................................
Creating Test Suites in Oracle JDeveloper...................................................................................
Importing Test Cases in Oracle JDeveloper ................................................................................
Creating Test Cases in Oracle JDeveloper ...................................................................................
Editing Test Cases in Oracle JDeveloper .....................................................................................
Creating Emulations in Oracle JDeveloper ........................................................................
Creating Assertions in Oracle JDeveloper..........................................................................
Creating External Calls in Oracle JDeveloper....................................................................
Creating a Test Case from Oracle BPEL Control ......................................................................
Deploying a Test Suite .......................................................................................................................
Deploying from Oracle JDeveloper ............................................................................................
Deploying from an ant Task ........................................................................................................
Running a Test Suite and Viewing Report Results ......................................................................
Running from Oracle BPEL Control...........................................................................................
Running from an ant Task ...........................................................................................................
Advanced Test Suite Design Features .............................................................................................
Setting Dynamic Values at Run Time ........................................................................................
Asynchronous Event Emulation .................................................................................................
Verifying External Actions ..........................................................................................................
Custom Reporting .........................................................................................................................
Database Views .............................................................................................................................
admin_list_td ..........................................................................................................................
admin_list_tdef.......................................................................................................................
XML Schemas ................................................................................................................................
Client APIs .....................................................................................................................................
21
Oracle BPEL Portlets
OracleAS Portal Introduction .............................................................................................................
Step 1: Installing and Configuring the Required Oracle Application Server Components...
Configuring Realms (10.1.3.1.0 Only) ..........................................................................................
Step 2: Deploying the Portlets ............................................................................................................
Deploying Portlets with dcmctl ....................................................................................................
Deploying Portlets with Oracle Enterprise Manager 10g Application Server Control
Console .............................................................................................................................................
Step 3: Registering Web Providers with OracleAS Portal .............................................................
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources .................................
Defining Oracle BPEL Control Report Portlet Parameters and Accessing Portlet Data
Sources ..............................................................................................................................................
Instance State ..........................................................................................................................
xvi
20-2
20-3
20-3
20-3
20-4
20-4
20-5
20-6
20-6
20-6
20-7
20-9
20-9
20-10
20-14
20-16
20-17
20-19
20-19
20-20
20-21
20-21
20-24
20-27
20-27
20-29
20-29
20-29
20-30
20-30
20-31
20-32
20-32
21-1
21-3
21-3
21-4
21-4
21-4
21-6
21-9
21-9
21-11
Instance Execution Time .......................................................................................................
Performance............................................................................................................................
Activity Sensor .......................................................................................................................
Process Time Distribution ....................................................................................................
Fault Sensor.............................................................................................................................
Defining Oracle BPEL Worklist Application Portlet Parameters and Accessing Portlet
Data Sources...................................................................................................................................
Listing Portlet Customization ..............................................................................................
Listing Portlet View ...............................................................................................................
Analysis Portlet Customization ...........................................................................................
Analysis Portlet View ............................................................................................................
Step 5: Mapping Portlet Parameters with Page Parameters ........................................................
Summary ...............................................................................................................................................
22
21-13
21-14
21-16
21-17
21-19
21-20
21-23
Oracle BPEL Control Reports
Creating Oracle BPEL Control Reports.............................................................................................
Creating Process Reports ...............................................................................................................
Creating Performance Reports ......................................................................................................
Creating Activity Sensor Reports .................................................................................................
Creating Fault Sensor Reports.......................................................................................................
Creating Process Time Distribution Reports.............................................................................
Summary ...............................................................................................................................................
Part V
A
21-11
21-12
21-13
21-13
21-13
22-1
22-3
22-5
22-7
22-9
22-10
22-11
Reference Information
Troubleshooting and Workarounds
Troubleshooting General Issues...........................................................................................................
Developer Prompt on Windows 2000 ............................................................................................
Correcting Validation Errors in Complex Processes....................................................................
Handling Long-Running Processes................................................................................................
Creating an Empty BPEL Process and Importing a Schema.......................................................
Troubleshooting Sensors—The Custom Data Publisher.................................................................
Data Publisher Is Not Working.......................................................................................................
Data Publisher Works, But Business Process Runs Slowly.........................................................
Caching Data in the Data Publisher Is Not Supported................................................................
Unexpected Errors in the Data Publisher ......................................................................................
Data Extracted to XML Is Difficult to Work With ........................................................................
Troubleshooting Oracle BPEL Worklist Application .......................................................................
Not Able to Log In to the Worklist Application ...........................................................................
Information Is Displayed in a Different Language ......................................................................
Dates and Times Are Displayed Incorrectly .................................................................................
The User Is Not Permitted to Perform an Action .........................................................................
Expected Task Is Not Listed Under Task Titles............................................................................
Summary ...................................................................................................................................................
A-1
A-1
A-1
A-1
A-2
A-2
A-2
A-3
A-3
A-3
A-3
A-4
A-4
A-4
A-4
A-4
A-4
A-5
xvii
B
BPEL Process Activities and Services
Process Activities Overview..................................................................................................................
Tabs Common to Many Activities ..................................................................................................
Assign Activity ..................................................................................................................................
Compensate Activity ........................................................................................................................
Decide Activity ..................................................................................................................................
Email Activity ....................................................................................................................................
Empty Activity ..................................................................................................................................
Fax Activity ........................................................................................................................................
Flow Activity ...................................................................................................................................
FlowN Activity ................................................................................................................................
Human Task Activity .....................................................................................................................
Invoke Activity ................................................................................................................................
Java Embedding Activity ...............................................................................................................
Pager Activity ..................................................................................................................................
Pick Activity.....................................................................................................................................
Receive Activity...............................................................................................................................
Reply Activity ..................................................................................................................................
Scope Activity ..................................................................................................................................
Sequence Activity............................................................................................................................
SMS Activity ....................................................................................................................................
Switch Activity ................................................................................................................................
Terminate Activity ..........................................................................................................................
Throw Activity ................................................................................................................................
Transform Activity..........................................................................................................................
Voice Activity ..................................................................................................................................
Wait Activity ....................................................................................................................................
While Activity..................................................................................................................................
Services Overview.................................................................................................................................
AQ Adapter......................................................................................................................................
Database Adapter............................................................................................................................
Decision Service...............................................................................................................................
EJB Web Service...............................................................................................................................
File Adapter .....................................................................................................................................
FTP Adapter.....................................................................................................................................
Java Web Service .............................................................................................................................
JMS Adapter.....................................................................................................................................
MQ Adapter .....................................................................................................................................
Oracle Applications ........................................................................................................................
PartnerLink ......................................................................................................................................
Validation When Loading a Process Diagram .................................................................................
Changes Made In Oracle JDeveloper Do Not Update Automatically.....................................
Summary .................................................................................................................................................
C
B-1
B-2
B-3
B-4
B-5
B-6
B-8
B-9
B-11
B-12
B-12
B-14
B-16
B-17
B-19
B-20
B-21
B-22
B-24
B-25
B-27
B-27
B-28
B-29
B-30
B-31
B-32
B-33
B-34
B-34
B-34
B-35
B-35
B-35
B-35
B-35
B-36
B-36
B-36
B-37
B-38
B-38
Deployment Descriptor Properties
Deployment Descriptor Preference Properties.................................................................................. C-1
Defining a Preference Property....................................................................................................... C-1
xviii
Updating a Preference at Run Time ...............................................................................................
Getting the Value of a Preference within a BPEL Process...........................................................
Encrypting a Preference Value........................................................................................................
Deployment Descriptor Configuration Properties ...........................................................................
Defining a Configuration Property ................................................................................................
Summary ...................................................................................................................................................
D
C-3
C-3
C-3
C-4
C-5
C-8
XPath Extension Functions
Advanced Functions ...............................................................................................................................
create-nodeset-from-delimited-string ............................................................................................
generate-guid .....................................................................................................................................
lookup-dvm........................................................................................................................................
lookup-xml .........................................................................................................................................
BPEL Extension Functions.....................................................................................................................
getLinkStatus .....................................................................................................................................
getVariableData .................................................................................................................................
getVariableProperty..........................................................................................................................
BPEL XPath Extension Functions .........................................................................................................
addQuotes ..........................................................................................................................................
appendToList .....................................................................................................................................
copyList ..............................................................................................................................................
countNodes ........................................................................................................................................
doc .......................................................................................................................................................
formatDate .........................................................................................................................................
generateGUID....................................................................................................................................
getContentAsString...........................................................................................................................
getConversationId.............................................................................................................................
getCreator...........................................................................................................................................
getCurrentDate ..................................................................................................................................
getCurrentDateTime.........................................................................................................................
getCurrentTime ...............................................................................................................................
getDomainId ....................................................................................................................................
getElement........................................................................................................................................
getGroupIdsFromGroupAlias.......................................................................................................
getInstanceId....................................................................................................................................
getNodeValue ..................................................................................................................................
getNodes...........................................................................................................................................
getPreference....................................................................................................................................
getProcessId .....................................................................................................................................
getProcessOwnerId.........................................................................................................................
getProcessURL.................................................................................................................................
getProcessVersion ...........................................................................................................................
getUserAliasId .................................................................................................................................
integer ...............................................................................................................................................
parseEscapedXML ..........................................................................................................................
processXQuery ................................................................................................................................
processXSLT.....................................................................................................................................
D-1
D-1
D-2
D-2
D-3
D-4
D-4
D-4
D-5
D-5
D-5
D-6
D-6
D-7
D-7
D-8
D-8
D-8
D-9
D-9
D-9
D-9
D-10
D-10
D-10
D-11
D-11
D-11
D-11
D-12
D-12
D-12
D-12
D-13
D-13
D-13
D-13
D-14
D-14
xix
processXSQL ....................................................................................................................................
readBinaryFromFile ........................................................................................................................
readFile .............................................................................................................................................
writeBinaryToFile............................................................................................................................
Database Functions ...............................................................................................................................
lookup-table .....................................................................................................................................
query-database ................................................................................................................................
sequence-next-val............................................................................................................................
Date Functions .......................................................................................................................................
add-dayTimeDuration-to-dateTime.............................................................................................
current-date......................................................................................................................................
current-dateTime.............................................................................................................................
current-time......................................................................................................................................
day-from-dateTime .........................................................................................................................
format-dateTime..............................................................................................................................
hours-from-dateTime .....................................................................................................................
implicit-timezone ............................................................................................................................
minutes-from-dateTime .................................................................................................................
month-from-dateTime ....................................................................................................................
seconds-from-dateTime..................................................................................................................
subtract-dayTimeDuration-from-dateTime ................................................................................
timezone-from-dateTime ...............................................................................................................
year-from-dateTime ........................................................................................................................
Mathematical Functions.......................................................................................................................
abs......................................................................................................................................................
Identity Service Functions ...................................................................................................................
getDefaultRealmName ...................................................................................................................
getGroupProperty ...........................................................................................................................
getManager ......................................................................................................................................
getReportees.....................................................................................................................................
getSupportedRealmNames............................................................................................................
getUserProperty ..............................................................................................................................
getUserRoles ....................................................................................................................................
getUsersInGroup .............................................................................................................................
isUserInRole.....................................................................................................................................
lookupGroup ...................................................................................................................................
lookupUser.......................................................................................................................................
Workflow Service Functions ...............................................................................................................
clearTaskAssignees .........................................................................................................................
createWordMLDocument ..............................................................................................................
getNotificationProperty .................................................................................................................
getNumberOfTaskApprovals........................................................................................................
getPreviousTaskApprover.............................................................................................................
getTaskAttachmentByIndex ..........................................................................................................
getTaskAttachmentByName..........................................................................................................
getTaskAttachmentContents .........................................................................................................
getTaskAttachmentsCount ............................................................................................................
xx
D-15
D-15
D-15
D-16
D-16
D-16
D-17
D-17
D-18
D-18
D-18
D-19
D-19
D-19
D-20
D-20
D-20
D-21
D-21
D-21
D-21
D-22
D-22
D-23
D-23
D-23
D-23
D-24
D-24
D-25
D-25
D-25
D-26
D-26
D-27
D-27
D-28
D-28
D-28
D-29
D-29
D-30
D-30
D-30
D-30
D-31
D-31
getTaskResourceBundleString ......................................................................................................
wfDynamicGroupAssign ...............................................................................................................
wfDynamicUserAssign ..................................................................................................................
String Functions.....................................................................................................................................
compare ............................................................................................................................................
compare-ignore-case.......................................................................................................................
create-delimited-string ...................................................................................................................
ends-with..........................................................................................................................................
format-string ....................................................................................................................................
get-content-as-string .......................................................................................................................
get-localized-string .........................................................................................................................
index-within-string .........................................................................................................................
last-index-within-string..................................................................................................................
left-trim .............................................................................................................................................
lower-case.........................................................................................................................................
matches .............................................................................................................................................
right-trim ..........................................................................................................................................
upper-case ........................................................................................................................................
Utility Functions....................................................................................................................................
authenticate ......................................................................................................................................
batchProcessActive .........................................................................................................................
batchProcessCompleted .................................................................................................................
format................................................................................................................................................
genEmptyElem ................................................................................................................................
getChildElement..............................................................................................................................
getMessage .......................................................................................................................................
listUsers ............................................................................................................................................
max-value-among-nodeset ............................................................................................................
min-value-among-nodeset.............................................................................................................
search ................................................................................................................................................
square-root .......................................................................................................................................
translateFromNative.......................................................................................................................
translateToNative............................................................................................................................
Summary .................................................................................................................................................
D-31
D-32
D-33
D-33
D-34
D-34
D-35
D-35
D-36
D-36
D-36
D-37
D-37
D-38
D-38
D-39
D-39
D-39
D-40
D-40
D-40
D-40
D-41
D-41
D-41
D-42
D-42
D-42
D-43
D-43
D-43
D-44
D-44
D-44
Index
xxi
xxii
Preface
This manual describes how to use Oracle BPEL Process Manager.
This preface contains the following topics:
■
Audience
■
Documentation Accessibility
■
Related Documents
■
Conventions
Audience
This manual is intended for anyone who is interested in using Oracle BPEL Process
Manager.
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/
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of text
that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or
organizations that Oracle does not own or control. Oracle neither evaluates nor makes
any representations regarding the accessibility of these Web sites.
xxiii
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 Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Administrator’s Guide
■
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging User’s Guide
■
Oracle Application Server Adapter Concepts
■
Oracle Application Server Adapter for Oracle Applications User’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:
xxiv
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.
xxv
xxvi
What’s New in Oracle BPEL Process
Manager?
The new features of Oracle BPEL Process Manager 10g (10.1.3.1.0) include:
■
Redesign of human task workflow, which includes
–
A new design-time interface: a re-entrant Human Task editor for declarative
task configuration
–
Metadata-driven workflow with minimal BPEL code generated
–
A modeling tool for creating and configuring complex patterns
–
Built-in dispatching functions: round-robin, least-busy, and most-productive
–
Dynamic assignment APIs for writing custom assignment services
–
New demos: OrderApproval, HelpDeskRequest, and ExpenseApproval
See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for more
information.
■
New Worklist Application functionality, which includes
–
Support for user profiles: end user, supervisor, process owner, group owner,
and administrator
–
Support for custom work queues and proxy support
–
Four new reports: Unattended Tasks Report, Tasks Priority Report, Tasks
Cycle Time Report, Tasks Productivity Report
–
Ability to define custom vacation rules and delegation rules
–
Admin pages for managing rules and flex field mappings
–
An improved design that supports enhancements to search capabilities,
identity browser, user and group rules, page customization, and more
See Chapter 16, "Worklist Application" for more information.
■
A comprehensive unit testing framework for BPEL, which enables you to
–
Automate testing of BPEL processes
–
Emulate partners and services and specify your own return data (instead of
actually invoking those services)
–
Create assertions to verify that your process works as expected
–
Calculate code coverage and highlight code that was not run
xxvii
–
Create unit tests from a BPEL audit trail
–
Integrate into Ant-JUnit reports
See Chapter 20, "Testing BPEL Processes" for more information.
■
Integration of Oracle BPEL Process Manager with business rules and the decision
service
–
Design-time support for business rules engines with a new decision service
activity and wizard
–
Design-time integration for Oracle Business Rules and iLog JRules
See Chapter 18, "BPEL Process Integration with Business Rules" for more
information.
■
Integration of Oracle BPEL Process Manager with JAAS and application server
J2EE security
See the following for more information:
■
–
"Logging into Domains" on page 19-6
–
"Oracle BPEL Control and Oracle BPEL Admin Console Users and Roles" on
page 1-21 of Oracle BPEL Process Manager Administrator’s Guide
Adapter improvements, which include
–
File/FTP adapter: using an invoke activity, you can read a file synchronously
using the File adapter or get a file using the FTP adapter
–
MQSeries adapter: a new adapter that exposes the JMS functionality provided
by IBM WebSphere MQ and native WebSphere MQ functionality
See the following for more information:
■
–
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging User’s Guide
for more information on all the adapters.
–
The online help in the Adapter Configuration Wizard
Oracle JDeveloper enhancements, which enable you to
–
Create a custom template from an existing BPEL process
–
Generate WSDLs with Java and EJB WSIF bindings automatically
–
Import a schema during project creation
–
Bookmark specific activities in a BPEL process to locate them quickly
–
Search for and jump to a specific activity in a BPEL process, show and hide
types of activities, and zoom in on containers (helpful for large, complex
processes)
–
Optimize a BPEL diagram layout
–
Use bpelx extensions for XML data manipulation
See the online help in Oracle JDeveloper for more information.
■
Improved clustering support: You can deploy to one node in a cluster with
automatic deployment to all other nodes, because deployment suitcases are now
stored in the dehydration store.
See Oracle BPEL Process Manager Installation Guide for more information.
■
xxviii
Support for standard ant.
Part I
Introduction and Concepts
This part introduces Oracle BPEL Process Manager.
This part contains the following chapters:
■
Chapter 1, "Introduction to Oracle BPEL Process Manager"
■
Chapter 2, "Getting Started with Oracle BPEL Process Manager"
1
Introduction to
Oracle BPEL Process Manager
This chapter provides a brief introduction to the Business Process Execution Language
(BPEL), Oracle BPEL Process Manager, and Oracle JDeveloper, which enables you to
design BPEL processes. An overview of how to use the information in this guide and
references to additional tutorials and demonstrations installed with Oracle BPEL
Process Manager are also provided.
This chapter contains the following topics:
■
What Is BPEL?
■
What Is Oracle BPEL Process Manager?
■
What Is Oracle JDeveloper?
■
How to Use This Guide
■
■
Getting Started with Demonstrations, Activity and Conceptual References, and
Tutorials
Summary
Oracle recommends that you perform the tutorials described
in Oracle BPEL Process Manager Quick Start Guide and Oracle BPEL
Process Manager Order Booking Tutorial before using this guide. These
tutorials provide you with an introduction to designing and deploying
BPEL processes.
Note:
What Is BPEL?
BPEL is an XML-based language for enabling task sharing across multiple enterprises
using a combination of Web services. BPEL is based on the XML schema, simple object
access protocol (SOAP), and Web services description language (WSDL). BPEL
provides enterprises with an industry standard for business process orchestration and
execution. Using BPEL, you design a business process that integrates a series of
discrete services into an end-to-end process flow. This integration reduces process cost
and complexity. The BPEL language enables you to define how to:
■
Send XML messages to, and asynchronously receive XML messages from, remote
services
■
Manipulate XML data structures
■
Manage events and exceptions
Introduction to Oracle BPEL Process Manager
1-1
What Is Oracle BPEL Process Manager?
■
Design parallel flows of process execution
■
Undo portions of processes when exceptions occur
See Also:
■
■
http://www.oracle.com/technology/bpel for specific
BPEL details, including links to BPEL specifications, white papers,
product demonstrations, and discussion groups
Chapter 3, "Manipulating XML Data in BPEL" through
Chapter 12, "Interaction Patterns" for a review of key BPEL
development concepts and code samples
What Is Oracle BPEL Process Manager?
Oracle BPEL Process Manager provides a framework for easily designing, deploying,
monitoring, and administering processes based on BPEL standards. Oracle BPEL
Process Manager provides support for the following features:
■
■
Web service standards such as XML, SOAP, and WSDL
Dehydration (enables the states of long-running processes to be automatically
maintained in a database) and correlation of asynchronous messages
■
Service-oriented architecture (SOA)
■
Parallel processing of tasks
■
Fault handling and exception management during both design time and run time
■
Event timeouts and notifications
■
Compensation mechanisms for the implementation of long-running transactions
■
Scalability and reliability of processes
■
Management and administration of processes
■
Version control
■
Audit trails for tracing business flow history
■
Installation on multiple operating systems and integration with multiple
application servers (for example, Oracle Application Server, BEA WebLogic, and
JBoss) and databases.
Oracle BPEL Process Manager adds value and ease of use to BPEL functionality by
providing support for the following in Oracle JDeveloper:
■
■
■
Transformations, workflows, worklists, notifications, sensors, and business rules
Technology adapters (file, FTP, database, advanced queuing (AQ), Java Messaging
Service (JMS), IBM WebSphere MQ, and Oracle Applications for Oracle E-Business
Suite)
Third-party adapters, including J.D. Edwards OneWorld, PeopleSoft, SAP R/3,
Siebel, Tuxedo, CICS, VSAM, IMS/TM, and IMS/DB
Oracle BPEL Process Manager can also be integrated with Oracle Business Activity
Monitoring, Oracle Application Server Portal, Oracle Application Server Integration
B2B, and Oracle Application Server Integration InterConnect.
1-2 Oracle BPEL Process Manager Developer’s Guide
What Is Oracle JDeveloper?
See Also:
■
■
■
■
■
■
"Sensor Integration with Oracle Business Activity Monitoring" on
page 17-13 for details about integrating Oracle BPEL Process
Manager with Oracle Business Activity Monitoring
Chapter 21, "Oracle BPEL Portlets" for details about integrating
Oracle BPEL Process Manager with OracleAS Portal
Oracle Application Server Integration B2B User’s Guide and the
readme file in the B2B_Oracle_Home\ip\install directory
for details about integrating Oracle BPEL Process Manager with
Oracle Application Server Integration B2B
Oracle Application Server Integration InterConnect User’s Guide for
details about integrating Oracle BPEL Process Manager with
Oracle Application Server Integration InterConnect
Oracle BPEL Process Manager Quick Start Guide for additional
Oracle BPEL Process Manager introductory details
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide for details about supported technology adapters
■
Oracle Application Server Adapter for Oracle Applications User’s Guide
■
Oracle Application Server Adapter Concepts
■
■
Oracle BPEL Process Manager Installation Guide for a list of
supported operation systems
The following URL for additional details about Oracle BPEL
Process Manager support for third-party adapters:
http://www.oracle.com/technology/products/integration/
adapters/index.html
What Is Oracle JDeveloper?
Oracle BPEL Process Manager provides support for using Oracle JDeveloper to
graphically design BPEL processes.
Oracle JDeveloper is an integrated development environment (IDE) for building
applications and Web services using Java, XML, and SQL standards. Oracle JDeveloper
supports the entire development life cycle with integrated features for designing,
coding, debugging, testing, profiling, tuning, and deploying applications. A visual and
declarative development approach and the Oracle Application Development
Framework (ADF) work together to simplify application development and reduce
coding tasks.
Oracle JDeveloper uses BPEL as its native format. This means that processes built with
Oracle JDeveloper are 100% portable. Oracle JDeveloper also enables you to view and
modify the BPEL source without decreasing the usefulness of the tool.
You design BPEL processes by dragging and dropping elements (known as activities)
into the process and editing their property pages. This eliminates the need to write
BPEL code. You integrate BPEL processes with external services (known as partner
links). You also integrate adapters and services such as workflows, transformations,
notifications, sensors, worklist task management, and business rules with the process.
Oracle JDeveloper can deploy the developed processes directly to Oracle BPEL Server.
This facilitates the development and maintenance of BPEL processes.
Introduction to Oracle BPEL Process Manager
1-3
How to Use This Guide
Oracle BPEL Process Manager provides support for the following services and
adapters in Oracle JDeveloper:
■
Transformations, workflows, worklists, notifications, sensors, and business rules
■
Technology adapters (file, FTP, database, AQ, JMS, MQ, and Oracle Applications)
Figure 1–1 shows Oracle JDeveloper with a BPEL process being designed.
Figure 1–1 Oracle JDeveloper
See Also:
■
■
■
"Overview of BPEL Project Creation and Oracle JDeveloper" on
page 2-3 for a description of the sections of Oracle JDeveloper
shown in Figure 1–1
Oracle BPEL Process Manager Quick Start Guide and Oracle BPEL
Process Manager Order Booking Tutorial for tutorials that use Oracle
JDeveloper
Online Help available from the Help main menu for additional
details about Oracle JDeveloper
How to Use This Guide
This guide is divided into several parts designed to first familiarize you with key
BPEL development concepts and features and then describe how Oracle BPEL Process
Manager adds value and ease of use to BPEL functionality. This guide layout is
described in Table 1–1.
1-4 Oracle BPEL Process Manager Developer’s Guide
How to Use This Guide
Table 1–1
Developer’s Guide Contents
Part
Description
Part I, "Introduction and
Concepts"
Chapters in this part provide an overview of the following
topics:
■
■
■
■
■
Part II, "Reviewing Key
BPEL Development
Concepts and Code
Samples"
Part III, "Oracle BPEL
Process Manager Services"
BPEL specifications, Oracle BPEL Process Manager, and
Oracle JDeveloper
Demonstrations, tutorials, and activity and conceptual
references provided with Oracle BPEL Process Manager
Starting and stopping key Oracle BPEL Process Manager
components
An introduction to Oracle JDeveloper, including an
overview of designer window sections, and a description of
project files and the drag-and-drop activity functionality
you follow to design and deploy a BPEL process
Oracle BPEL Control for running deployed BPEL processes
Chapters in this part introduce you to key BPEL development
concepts and associated code samples. These chapters are useful
for any developer interested in understanding the underlying
functionality of BPEL. Specific topics discussed include the
following:
■
XML document manipulation
■
Synchronous and asynchronous services invocation
■
Parallel flows
■
Conditioning branching
■
Fault handling and exception management
■
Java/J2EE code integration in BPEL processes
■
Events and timeouts
■
BPEL process invocation
■
Interaction patterns
Once you have gained a solid knowledge of the key BPEL
development concepts described in Part II, you are ready to
learn how Oracle BPEL Process Manager adds value and ease of
use to BPEL functionality to provide support for the following
services:
■
Transformations
■
Notifications
■
Workflows
■
Worklists
■
Sensors
■
Business rules
Part IV, "Development and
Deployment Life Cycle"
Chapters in this part describe how to run and manage deployed
BPEL processes from Oracle BPEL Control, how to test BPEL
processes in a preproduction environment, how to create run
time reports, and how to integrate with OracleAS Portal.
Part V, "Reference
Information"
Appendices in this part provide reference details about
troubleshooting, supported activities, deployment descriptor
properties, and XPath expression functions.
Introduction to Oracle BPEL Process Manager
1-5
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
See Also:
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide for specific details about configuring the file, FTP,
database, AQ, MQ, and JMS adapters in a BPEL process
■
Oracle Application Server Adapter for Oracle Applications User’s Guide
for information on using the Oracle Applications adapter
■
Oracle Application Server Adapter Concepts
■
Getting Started with Demonstrations, Activity and Conceptual
References, and Tutorials
In addition to the contents of this guide, the Oracle BPEL Process Manager Quick Start
Guide, and the Oracle BPEL Process Manager Order Booking Tutorial, a series of
demonstrations, activity and conceptual reference materials, and tutorials are also
provided to increase conceptual knowledge and hands-on experience with Oracle
BPEL Process Manager. These materials are installed with Oracle BPEL Process
Manager in the SOA_Oracle_Home\bpel\samples directory.
Table 1–2 describes the contents of the samples directory. If you are using Oracle
JDeveloper, you can also access details about this directory from the Start Menu by
selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process
Manager > Getting Started with Samples.
You can automatically create the BPEL project for a sample by performing the
following steps:
1.
Select an application in the Application Navigator.
2.
Select Open from the File main menu in Oracle JDeveloper.
3.
Go to the directory of the sample you want to use.
4.
Select the .jpr file of the sample.
This causes the BPEL project for the selected sample to display in the Application
Navigator.
New samples are periodically added. Visit the Oracle BPEL Process Manager site on
the Oracle Technology Network (OTN) periodically for information about
downloading any new samples:
http://www.oracle.com/technology/products/ias/bpel/index.html
Table 1–2
Tutorials, Demonstrations, and Reference Materials
Directory
Description
demos
Contains a set of common business scenarios and describes how they are
implemented with BPEL. Table 1–3 on page 1-7 provides descriptions of the
available demonstrations.
interop
Contains a set of BPEL projects showing the interoperability of Oracle BPEL
Process Manager with Web services implemented with the following:
references
■
Microsoft .Net
■
Apache Axis
■
BEA WebLogic
Contains activities and concepts defined in the BPEL language. Table 1–4 on
page 1-9 provides descriptions of the available activities and concepts.
1-6 Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–2 (Cont.) Tutorials, Demonstrations, and Reference Materials
Directory
Description
tutorials
Contains a set of BPEL processes targeting the various BPEL tasks to which
you are exposed. Table 1–5 on page 1-10 provides descriptions of the
available tutorials.
utils
Contains a set of building block services shared by the BPEL samples
What Demonstrations Are Available?
Table 1–3 describes the BPEL process demonstrations available for use in the demos
directory. See the documentation available in these directories for instructions on
running these demonstrations.
Table 1–3
demos Directory Contents
Directory
Description
AmazonFlow
Describes how to integrate an Amazon Web service with a BPEL
process to search for an item.
Attachment
Describes how to use binary file attachments in SOAP messages
with the Direct Internet Message Encapsulation (DIME) and
Multipurpose Internet Message Extensions (MIME) protocols.
AutoLoanDemo
Describes how to integrate Oracle BPEL Process Manager with a
backend business rules engine. A BPEL process is modeled that
uses the decision service to perform the following:
■
■
Calculate a credit rating for a customer loan request
Provide a recommendation on the bank and APR for the
requested loan
The output of the decision service is passed to a human task for
modification before the loan request is approved or rejected.
BankTransferDemo
Describes how to perform a bank transfer. This sample illustrates
the ability of Oracle BPEL Process Manager transaction
management. The sample shows two types of transaction
management:
■
Internal engine-implemented JTA transaction management
■
Explicit compensating transactions modeled in BPEL
BPELTest
Describes several of the BPEL test framework features. The test
framework provides a structured way to test BPEL processes and
alleviates common problems like dependencies on complex external
systems and performing data assertions.
CheckoutDemo
Describes an interaction between a Java Server Page (JSP) user
interface and a BPEL process
DocumentReview
Describes how to create a business process for reviewing a
document in parallel. A final reviewer reviews comments from each
of the group reviewers. A worklist application views and acts on
the tasks. This example highlights the use of the following features:
■
■
ExpenseRequestAppr
oval
Modeling a group vote participant type in the Oracle
JDeveloper environment
Using Oracle BPEL Worklist Application to view and act on
tasks
Describes how to approve or reject an expense request from an
employee. This demonstrates management chain approval and use
of the decision service to determine the levels of approval required
for a particular expense request.
Introduction to Oracle BPEL Process Manager
1-7
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–3 (Cont.) demos Directory Contents
Directory
Description
GoogleFlow
Describes how to invoke a Google Web service from a BPEL process
HelpDeskServiceReq
uest
Describes how to process a help desk service request. The
demonstration uses an ad hoc participant type for accepting or
rejecting a service request.
HotwireDemo
This sample illustrates the asynchronous multistep conversation
between two BPEL processes. One BPEL process initiates the
conversation and sends the message to the other BPEL process. The
second process waits for 30 seconds and responds asynchronously.
Then the first process waits for 30 seconds and calls the second
process again. The second process responds again after 30 seconds.
IBMSamples
Describes how to execute the BPEL samples shipping with the IBM
Business Process Execution Language for Web Services Java Run
Time (BPWS4J) on Oracle BPEL Server
LoanDemo
Describes how to integrate a synchronous credit rating service and
two asynchronous loan processor services into an end-to-end loan
procurement application with a Java Server Page (JSP) user
interface to initiate the process and view loan offer results
LoanDemoPlus
Describes how to extend the LoanDemo sample to use Java
embedding exception management, including manual processing
steps and development of a richer custom user interface
ParallelSearch
Describes how to use Oracle BPEL Server to perform parallel
synchronous invocations. This sample illustrates how to use the
nonBlockingInvoke property in bpel.xml. This property
enables you to execute a synchronous BPEL process calling multiple
synchronous Web services in flow in real parallel mode. If you set
the nonBlockingInvoke property to false, Oracle BPEL Server
blocks the Web service call until the other is finished.
ResilientDemo
Describes how to use a BPEL process to manage fault handling and
run time exceptions
SalesforceFlow
Describes how to integrate the Salesforce.com sForce Web services
into a BPEL process (including authentication, session management,
and dynamic load balancing)
SleepBroker
Describes how to use a process that receives a number, creates that
number of branches using the flowN activity, and waits for a period
of time based on the index variable setting
This process receives an integer as input. It creates that number of
branches using bpelx:flowN. In each branch, a wait activity is
executed. The wait time is based on the index variable.
VacationRequest
Describes how to approve or reject a vacation request. The approval
or rejection is a one-step process involving the manager of the user
filing the vacation request. This demonstration also describes the
use of workflow for simple approvals, and the use of a deployment
descriptor preference to replace a static parameter value in the
BPEL process.
XSLMapper
Describes how to create a transformation that maps a purchase
order schema to an invoice schema
What Activity and Conceptual References Are Available?
Table 1–4 describes the activity and conceptual references available for review and use
in the references directory. The comment lines in each bpel.xml file and .bpel
file describe the specific context in which the activity is being used.
1-8 Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–4
references Directory Contents
Directory
Activity Description
Assign
Shows how to receive an input string, prefix Hello to it using an
assign activity, and asynchronously return the result
BPELTest
Illustrates the features of the BPEL test framework. The BPEL test
framework provides emulation and assertion capabilities and eases
the automation of testing BPEL processes.
Catch
Shows how an exception can be raised using the throw activity and
managed using a catch activity
CustomXPathFunctio
n
Shows how to use custom XPath functions within assign activities
DynamicPartnerLink
Shows how to update dynamic partner links
Event
Shows how to enable an asynchronous BPEL process and use event
handlers to receive and process events while waiting for the
asynchronous callback
Flow
Shows how to create parallel paths of execution within a BPEL
process
FlowN
Shows how to receive an integer and create that number of
branches
Invoke
Shows how to invoke a synchronous integer increment service
JavaExec
Shows how to use the BPEL exec extension to invoke a Java class
from within a BPEL process
Link
Shows how a link defines dependencies between executions of
activities. In this sample, a link in a flow activity sequences the
execution of two service invocations.
Pick
Shows how to invoke an asynchronous loan service and use a BPEL
pick activity to receive an asynchronous response or a timeout
message. If the loan amount is more than 10000, it takes about 30
seconds for the server to process it, causing a timeout to be raised.
Receive
Shows how to invoke an asynchronous loan service and wait for an
asynchronous callback message using the BPEL receive activity
Replay
Shows how to replay an activity, such as a scope
Reply
Shows how to receive a string as input, perform an assign, and use
the reply activity to synchronously return the modified string
Switch
Shows how to use a switch activity to return a different text
message based on whether the input value is greater or less than
zero
Terminate
Shows how to invoke a synchronous stock quoting service. The
terminate activity then aborts, causing the final callback invoke
activity to be skipped.
Throw
Shows how to throw a BPEL fault (without handling it) and cause
the instance to fault
Wait
Shows how to receive input, wait for 60 seconds, and
asynchronously call back a client
While
Shows how to invoke an incremental service n times with a while
activity, where n is provided as an input value
Xpath
Shows how to receive an invalid application, perform several XPath
copies, and asynchronously return the application. This showcases
the use of namespace-qualified XPath query strings in assign
activities.
Introduction to Oracle BPEL Process Manager
1-9
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–4 (Cont.) references Directory Contents
Directory
Activity Description
XPathFunction
Shows how to define and use custom XPath functions within BPEL
assign activities
See Also:
Chapter 3, "Manipulating XML Data in BPEL" through
Chapter 12, "Interaction Patterns" for activity development
concepts and code samples
■
Appendix B, "BPEL Process Activities and Services" for specific
details about activities that you drag and drop in Oracle
JDeveloper
■
What Tutorials Are Available?
Table 1–5 describes the tutorials available for use in the tutorials directory. See the
documentation available in these directories for instructions on running these
tutorials.
Table 1–5
tutorials Directory Contents
Directory
Description
101.HelloWorld
This sample takes a string as input, appends Hello to it, and
asynchronously generates a greeting as a response.
102.InvokingProce
sses
This sample invokes a variety of processes, including JSPs and
remote method invocations (RMIs).
103.XMLDocuments
This sample shows how to use XML variables and the assign activity
to manipulate XML documents.
104.SyncQuoteCons
umer
This sample shows how to use the invoke activity to invoke a
synchronous stock quote service.
105.AsyncComposit
eLoanBroker
This sample shows how to use the receive activity to receive a
callback from an asynchronous loan processor Web service.
106.ParallelFlows
This sample shows how to use the flow activity to define parallel
paths of execution within a process. In this sample, two asynchronous
loan processing services are invoked in parallel.
107.Exceptions
This sample shows how to use fault handling to manage faults
generated by invoke and throw activities. The process uses a pick
activity to receive the response from a loan validator. If an exception
message is received, it throws an error that is handled in a catch fault
handler.
108.Timeouts
This sample shows how to define and manage timeouts using the
pick activity.
109.CorrelationSe
ts
This sample shows how to use correlation sets to correlate
asynchronous message exchanges between buyer and seller services.
It shows content-based correlation of asynchronous messages.
112.Arrays
This sample shows how to design a BPEL process that uses arrays.
This sample illustrates how you can handle array structures present
in your XML payload by using the while activity in the BPEL process.
113.ABCARouting
This sample shows how to coordinate the flow of messages across
three services: A, B, and C.
1-10 Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
114.XSLTTransform
ations
This sample shows how to invoke XSLT transformations to perform
complex data manipulations. The process takes in complex invoice
data as input. It uses the ora:processXSLT function to pass this
data as input to be the XSLT service and returns the transformed
content.
115.XQueryTransfo
rmations
This sample shows the use of XQuery functions in Oracle BPEL
Process Manager. This sample requires XQuery libraries available
only in the Oracle BPEL Process Manager for OracleAS Middle Tier
installation type or one of the Oracle Application Server SOA
installation types. This sample cannot be used with the Oracle BPEL
Process Manager for Developers installation type.
117.ReceiveEmails
This sample shows how to receive an e-mail in a BPEL process.
121.FileAdapter
These samples show how to use the file adapter. The following
tutorials are provided:
■
■
■
■
■
COBOL Copybook — Processes native data defined using a
COBOL copybook
Complex structures — Processes native data defined in a custom
format
Debatching — Processes native data containing multiple
messages defined in a custom format
Flat structure — Processes address book entries from a CSV
(Comma Separated Values) file. This is then transformed to a
new address format (fixed-length format).
Opaque with headers — Handles native data in an opaque
format (for example, GIF or JPEG files)
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
Introduction to Oracle BPEL Process Manager 1-11
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
122.DBAdapter
The following samples show how to use the database adapter:
■
■
■
■
■
■
■
■
■
■
■
■
■
■
advanced—Advanced samples that insert and extract XML data
stored in a database as a CLOB, set up sequencing, and insert
into multiple databases as part of a single transaction
Delete — A record is passed to the operation and the database
row with the primary key is deleted.
File2StoredProcedure—Data is provided to a stored procedure,
which is then executed.
File2Table —The file adapter, XSLT Mapper, and database
adapter take an inbound purchase order, transform it to another
order format, and produce an outbound message.
Insert — A record is passed to the operation and inserted into the
database as relational data.
InsertWithCatch—Adds fault handling to an insert operation
MasterDetail—Replicates data in the table of one database to the
tables of another database
Merge —A record is passed to the operation and a database row
is either inserted or updated.
PollingControlTableStrategy—An inbound operation polls XML
instances. A control table stores the primary key of every row
that has yet to be processed.
PollingLastReadIdStrategy—An inbound operation polls XML
instances. A helper table remembers a sequence value. A
sequence value of 1000 means that every record with a sequence
less than that value has already been processed.
PollingLastUpdatedStrategy—An inbound operation polls XML
instances. A helper table remembers the last-updated value.
PollingLogicalDeleteStrategy—An inbound operation polls XML
instances. A special field is updated on each row processed. The
WHERE clause is updated at run time to filter out processed rows.
QueryByExample—An outbound query by example operation
RefCursor—A BPEL process takes user input and executes a
stored procedure. Output from a REF CURSOR is returned.
■
ResultSetConverter—An alternative using REF CURSOR
■
SelectAll—An outbound Select All operation
■
SelectAllByTitle—An outbound SelectAllByTitle operation
■
SelectCount—Pure SQL support in 10.1.3.1
■
SelectGroupBy—Pure SQL support in 10.1.3.1
■
SelectStar—Pure SQL support in 10.1.3.1
■
sql—SQL*Server example
■
■
Update—A record is passed to the operation and the database
row with the same primary key is updated
UpdateAll—Pure SQL support in 10.1.3.1
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
1-12 Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
123.JMSAdapter
This samples shows the ability of the JMS Adapter to process
incoming messages in a JMS destination (a queue) and write the same
message to another JMS destination (a topic).
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
124.AQAdapter
These samples show how to use the AQ adapter:
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
ADT — A message is received from the AQ adapter, the payload
copied to an outbound message, and the AQ adapter invoked
with the outbound message. ADT queues are used.
ADT_with_CLOB_Payload — A message is received from the
AQ adapter, the CLOB payload and payload header copied to an
outbound message, and the AQ adapter invoked with the
outbound message.
ADT_with_CLOB_Payload_as_Opaque — A process uses a
non-XML CLOB field as a payload field.
ADT_with_XMLType_Payload—A process receives a message
from the AQ adapter, copies the payload and PayloadHeader to
an outbound message, and invokes the AQ adapter with the
outbound message.
AQ_10_1_3_Supported_ADT_Types— Uses SQL Oracle
primitive and ANSI types supported by the AQ adapter ADT
AQMessageRejectionHandler — Rejected messages are handled
through the rejectedMessageHandler property.
AQOutboundCorrelation — Correlations are used to correlate an
outbound invoke activity with an inbound receive activity.
AQSupportedADTTypes — All SQL primitive types supported
by the AQ adapter ADT are used.
File2AQBLOB2File — Reads GIF files from a directory every 10
seconds with the file adapter and enqueues the whole file into a
BLOB column field of an ADT queue using the AQ adapter
MulticonsumerInbound — The AQ adapter listens on the
INBOUND_PUBLISHER queue for message recipients named
blue. Any message the adapter retrieves starts a BPEL instance.
The message is sent to the INBOUND_CONSUMED queue. The
queues involved are RAW queues.
MulticonsumerOutbound — Sets the AQ recipient in a
multiconsumer queue. The recipient list is set in the
InteractionSpec parameter or the AQ header
recipientlist parameter.
Raw — A message is received from the AQ adapter, the payload
copied to an outbound message, and the AQ adapter invoked
with the outbound message. RAW queues are used.
RawQueuePayloadUsingNativeFormat — The AQ Adapter and
Native Format Builder wizard are used together. The native
format used is comma-separated value (CSV).
RuleBasedSubscription_Header — A rule-based subscriber is
created. The subscriber gets messages and passes them on.
RuleBasedSubscription_Payload — A rule-based subscriber
subscribes to a magazine with a specific title. The message
selector rule is used.
Simple_XMLType_Payload— Simple XMLType payload use
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
Introduction to Oracle BPEL Process Manager 1-13
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
125.ReportsSchema
This sample shows how to build custom reports using the BPEL
Process Manager reports schema.
126.DataAggregato
r
This sample shows how to take a single XML document, divide it
into several smaller documents, perform tasks on each smaller
document, reassemble the smaller documents into a single XML
document, and return the single document to the invoker.
127.OrderBookingT
utorial
This sample shows how to design and execute a sophisticated process
that uses synchronous and asynchronous services, parallel flows of
execution, conditional branching logic, fault handling and exceptions
management, transformations, file adapter and database adapter
functionality, and human workflow, notification, and sensor
functionality.
128.GoogleFlow
This sample shows a process that uses an external Web service to
present information to the client. Processes designed with sensors are
also used.
129.FTPAdapter
These samples show how to use the file adapter:
■
■
FTPDebatching—This sample shows how to use the FTP adapter
to process a file containing a batch of business records (invoices
and purchase orders) and transform and write the records to
separate output files.
SynchronousRead—This sample shows a midprocess
synchronous read operation through an invoke activity.
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
130.SendEmailWith
Attachments
This sample shows how to send an e-mail with attachments through
Oracle JDeveloper.
132.UserTasks
This process demonstrate a simple user task. The process has a quote
to buy and sell a particular stock and the approver has to select
whether to buy or sell the stock.
133.SecureInvokin
gProcesses
This sample illustrates how to securely invoke a BPEL Process. The
following types of clients are covered in this sample:
■
Invoking from JSP
■
Invoking from HTTP directly
■
Invoking over SOAP
■
Invoking from Java RMI client
140.AdapterFramew
ork
This sample shows how to use dynamic JCA partner links in BPEL
150.AppsAdapter
These samples show how to use the Oracle Applications adapter:
■
■
■
■
■
701.LargeProcesse
s
ChangeOrderAPI—Changes a purchase order in Oracle
E-Business Suite
GetPOAckBusinessEvent—Demonstrates outbound business
events
OrderImportConcurrentProgram— Imports and creates a
purchase order in Oracle E-Business Suite
POAckOutboundXMLGateway—Integrates with Oracle XML
gateway to retrieve a purchase order acknowledgement
POInboundXMLGateway—Integrates with Oracle XML gateway
to create a purchase order in Oracle E-Business Suite
This sample shows how support is provided for processes with a
large number of work items (10,000 or more).
1-14 Oracle BPEL Process Manager Developer’s Guide
Summary
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
702.Bindings
This sample shows how to:
See Also:
■
Integrate Enterprise Java Beans (EJB) in a BPEL process
■
Call the HTTP get method from a BPEL process
■
Call a Java method from a BPEL process
The following guides for additional tutorials you can run:
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
Summary
This chapter introduces BPEL, how Oracle BPEL Process Manager supports BPEL, and
how Oracle JDeveloper enables you to design BPEL processes. An overview of how to
use this guide and references to additional tutorials, demonstrations, and other helpful
materials installed with Oracle BPEL Process Manager are also provided.
Introduction to Oracle BPEL Process Manager 1-15
Summary
1-16 Oracle BPEL Process Manager Developer’s Guide
2
Getting Started with
Oracle BPEL Process Manager
This chapter describes how to start key Oracle BPEL Process Manager components,
including Oracle JDeveloper, Oracle BPEL Server, and Oracle BPEL Control. An
overview of the main sections of Oracle JDeveloper that you use to design BPEL
processes is also provided. Key BPEL design components such as activities and
partner links and the services and adapters that Oracle BPEL Process Manager
provides to add value and ease of use to standard BPEL functionality are also
described.
This chapter contains the following topics:
■
Overview of Oracle BPEL Process Manager Components
■
Starting Oracle BPEL Process Manager Components
■
Overview of the BPEL Designer Environment
■
Overview of Activities
■
Overview of Partner Links
■
Overview of Oracle BPEL Server
■
Overview of Oracle BPEL Control
■
Overview of Oracle BPEL Process Manager Services
■
Overview of Oracle BPEL Process Manager Technology Adapters
■
Summary
Overview of Oracle BPEL Process Manager Components
The Oracle BPEL Process Manager consists of the three components shown in
Figure 2–1.
Figure 2–1 Oracle BPEL Process Manager Components
Design
Deployment
Management
Oracle
JDeveloper
BPEL
Server
Oracle
BPEL
Control
Each component enables you to perform a specific set of tasks:
Getting Started with Oracle BPEL Process Manager
2-1
Starting Oracle BPEL Process Manager Components
The design environment (Oracle JDeveloper) enables you to design and deploy
BPEL processes. You design BPEL processes by dragging and dropping elements
(known as activities) into the process and editing their property pages. You
integrate BPEL processes with external services that you also design and edit
(known as partner links). You also integrate technology adapters and services such
as workflows, worklists, transformations, notifications, sensors, and business rules
with the process.
■
When design is complete, you deploy the process from the design environment to
Oracle BPEL Server.
■
If deployment is successful, you can run and manage the BPEL process from
Oracle BPEL Control.
■
This chapter provides an overview of getting started with these components.
Starting Oracle BPEL Process Manager Components
Follow the instructions in Table 2–1 to start and stop Oracle BPEL Process Manager
components.
Table 2–1
Starting and Stopping Oracle BPEL Process Manager Components
To Access The...
On Windows...
Oracle BPEL Server Select Start > All Programs > Oracle Oracle_Home > Start SOA suite
On UNIX...
To start Oracle BPEL Server:
From $ORACLE_HOME/bpel/bin:
startorabpel.sh
To stop Oracle BPEL Server:
From $ORACLE_HOME/bpel/bin:
shutdownorabpel.sh
Oracle JDeveloper
Click JDev_Oracle_
Home\JDev\bin\jdev.exe or create a
shortcut
$ORACLE_HOME/jdev/bin/jdev
Oracle BPEL
Control
You must first start Oracle BPEL Server.
First start Oracle BPEL Server.
To start Oracle BPEL Control:
To start Oracle BPEL Control:
1.
Select Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process
Manager > BPEL Control
You can also start Oracle BPEL Control using
the URL for your installation, which can
found in SOA_Oracle_
Home\install\bpelsetupinfo.txt.
2-2 Oracle BPEL Process Manager Developer’s Guide
■
Log on to the URL for your installation,
which can found in
bpelsetupinfo.txt.
Overview of the BPEL Designer Environment
Table 2–1 (Cont.) Starting and Stopping Oracle BPEL Process Manager Components
To Access The...
On Windows...
On UNIX...
Developer Prompt
Select Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process
Manager > Developer Prompt to open up a
command prompt at the SOA_Oracle_
Home\bpel\samples directory. This
enables you to easily access demonstrations
and start any required Web services.
Set the Developer Prompt (for example, in the
Bourne shell):
$ ORACLE_
HOME=/home/oracle/installs/midtier
$ export ORACLE_HOME
$ PATH=$ORACLE_HOME/bpel/bin:$PATH
$ export PATH
Oracle BPEL
Process Manager
Samples and
Tutorials
For details about BPEL samples and
additional tutorials available for use:
Log into the following URL:
Sample Worklist
Application
To access the login window for Oracle BPEL
Worklist Application:
Select Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process
Manager > Getting Started with Samples
Select Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process
Manager > Sample Worklist Application
$ORACLE_
HOME/bpel/samples/sampleshome.html
First start Oracle BPEL Server.
To start Oracle BPEL Worklist Application:
■
Log on to the URL for your installation,
which is found in bpelsetupinfo.txt.
You may also start Oracle BPEL Worklist
Application using the URL for your
installation, which is found in SOA_
Oracle_
Home\install\bpelsetupinfo.txt.
Always use the Developer Prompt to open an operating
system command prompt when deploying services with ant or
obant. This sets all required paths. Opening an operating system
command prompt in any other way is not supported.
Note:
Overview of the BPEL Designer Environment
This section provides an overview of the Oracle JDeveloper environment.
Overview of BPEL Project Creation and Oracle JDeveloper
This section provides an overview of Oracle JDeveloper. In this overview, you first
create an application and a project. An application is a container in which to place
projects. A project contains the BPEL process.
1.
Create an application by selecting New > Application from the File main menu
and providing the required details in the Create Application window (including
not selecting any application template).
2.
Ensure that the directory path of an application does not include any blank spaces.
For example, the following is not permitted:
C:\Program Files\projects\myapplication\Loanflow
3.
Click Cancel on the Create Project window.
4.
Right-click the newly created application and select New Project.
5.
Double-click BPEL Process Project and provide the required details (including
BPEL process name) in the BPEL Project Creation Wizard windows. A single
Getting Started with Oracle BPEL Process Manager
2-3
Overview of the BPEL Designer Environment
project can contain only one BPEL process. Always use completely unique names
when creating BPEL projects. Do not create:
■
A project name that begins with a number
■
A project name that includes a dash (for example, Loan-Flow)
■
Two projects with the same name, but with different capitalization
Notes: You can also import existing projects into Oracle JDeveloper
by selecting Import > BPEL Process from the File main menu.
However, do not import or add XSD files in a ZIP file into a BPEL
project. Always extract the XSD files from a ZIP file before importing
them.
After you create the application and project, Oracle JDeveloper displays the sections
shown in Figure 2–2. You can also access this view by selecting View > Application
Navigator and double-clicking the .bpel file of the project. In this example, the project
is an asynchronous type and is named OrderBooking.
Figure 2–2 Oracle JDeveloper Sections
Each section of this view enables you to perform specific design and deployment
tasks. Table 2–2 identifies the sections listed in Figure 2–2 and provides references to
sections that describe their capabilities.
2-4 Oracle BPEL Process Manager Developer’s Guide
Overview of the BPEL Designer Environment
Table 2–2
Oracle JDeveloper Sections
Section
Location in Figure 2–2
See Section
Application Navigator
Upper left
"Application Navigator" on
page 2-5
Diagram window, Source
window, and History
window
Middle
"Diagram Window" on page 2-6,
"Source Window" on page 2-8,
and "History Window" on
page 2-9
Process Activities selection of Upper right
the Component Palette
"Component Palette" on
page 2-10
Property Inspector section
Lower right
"Property Inspector" on
page 2-12
Structure Window
Lower left
"Structure Window" on page 2-12
Log Window
Bottom
"Log Window" on page 2-13
See Also: Oracle BPEL Process Manager Quick Start Guide and Oracle
BPEL Process Manager Order Booking Tutorial for tutorials in which you
create applications and projects
Application Navigator
The Application Navigator shown in the upper left part of Figure 2–2 displays the
project files. Double-click a node (for example, the Integration Content node) to
display its contents. Right-click a node to display a context-sensitive menu of
commands. The menu commands that are available depend on the node selected. For
example, if you right-click the FulfillOrders project in Figure 2–3, you can compile
and deploy this BPEL process to Oracle BPEL Server.
Figure 2–3 shows the files that appear under the Integration Content folder when you
first create a project in Oracle JDeveloper (in this example, named FulfillOrders inside
an application named myBPELapplication).
Figure 2–3 Application Navigator
Table 2–3 describes these initial project files.
Table 2–3
Initial Project Files
File
Description
bpel.xml
The deployment descriptor file that defines the locations of the WSDL
files for services to be called by this BPEL process flow. This file
references the public interface for the service.
See Also: Appendix C, "Deployment Descriptor Properties"
Getting Started with Oracle BPEL Process Manager
2-5
Overview of the BPEL Designer Environment
Table 2–3 (Cont.) Initial Project Files
File
Description
FulfillOrder.bpel
The source file, which, depending upon the project type you selected,
initially contains a minimal set of activities (if you selected to create an
asynchronous project, then receive and invoke activities appear). You
add syntax to this file when you drag and drop activities, create
variables, create partner links, and so on.
FulfillOrder.wsdl
The WSDL client interface, which defines the input and output
messages for this BPEL process flow, the supported client interface and
operations, and other features. This functionality enables the BPEL
process flow to be called as a service.
As you design the project, additional files, folders, and elements can appear in the
Application Navigator. For example, Figure 2–4 shows the files that appear for a
project in which you imported schemas (OrderBookingPO.xsd and Orders.xsd),
configured the database adapter (the WriteDBRecord.wsdl file), and created a
transform activity (Transformation_1.xsl under the Integration Content folder). The
Application Sources node contains Java source files. The Java classes are used inside
callouts from the BPEL process. Additional folders can appear, such as BPEL-INF (a
special directory for Java JAR files).
Figure 2–4 Application Navigator (Expanded)
If you want to learn more about the Application Navigator,
place the cursor in this section and press F1 to display online Help.
Note:
Diagram Window
The Diagram window shown in the middle of Figure 2–2 provides a visual view of the
BPEL process that you design. This view displays when you perform one of the
following actions:
■
Double-click the .bpel file name in the Application Navigator
■
Click the Diagram tab at the bottom of the window with the .bpel file selected
Figure 2–5 shows the activities automatically created with an asynchronous project. In
the tutorials described in Oracle BPEL Process Manager Quick Start Guide and Oracle
2-6 Oracle BPEL Process Manager Developer’s Guide
Overview of the BPEL Designer Environment
BPEL Process Manager Order Booking Tutorial, you add to the BPEL process by dragging
and dropping activities, creating variables, creating partner links, and so on.
Figure 2–5 Diagram (After Creation of an Asynchronous Project)
As you design the project by dragging and dropping activities, creating partner links,
and so on, the Diagram window changes. Figure 2–6 shows the Diagram 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).
Figure 2–6 Diagram (After Design Phase)
Getting Started with Oracle BPEL Process Manager
2-7
Overview of the BPEL Designer Environment
Source Window
Click Source at the bottom to view the syntax inside the BPEL process project files. As
you drag and drop activities and partner links, and perform other tasks, the syntax in
these source files is immediately updated to reflect these changes. For example,
Figure 2–7 shows the property sheet as it is being edited.
Figure 2–7 CreditRatingService Partner Link Icon and Property Sheet
Click Source at the bottom of the window. Figure 2–8 shows part of the Source of a
.bpel file. Details about the CreditRatingService partner link you created appear in
the file.
2-8 Oracle BPEL Process Manager Developer’s Guide
Overview of the BPEL Designer Environment
Figure 2–8 Source View of a .bpel File
See Also: The following documentation for examples and
descriptions of the types of syntax that appear in project files:
■
■
Chapter 3, "Manipulating XML Data in BPEL" through
Chapter 12, "Interaction Patterns"
SOA_Oracle_Home\bpel\samples directory
History Window
Click History at the bottom to perform such tasks as viewing the revision history of a
file and viewing read-only and editable versions of a file side-by-side. Figure 2–9
shows the History view for a BPEL file.
Getting Started with Oracle BPEL Process Manager
2-9
Overview of the BPEL Designer Environment
Figure 2–9 History View
Note: If you want to learn more about the History view, place the
cursor in this section and press F1 to display online Help.
Component Palette
Activities are the building blocks of the BPEL process. The Process Activities selection
of the Component Palette shown in the upper right part of Figure 2–2 displays a set of
activities that you drag and drop into the Diagram window of the BPEL process. The
Component Palette displays only those pages relevant to the state of the Diagram
window. Process Activities or Services are nearly always visible. However, if you are
designing a transformation in a transform activity, the Component Palette only
displays selections relevant to that activity, such as String Functions, Mathematical
Functions, and Node-set Functions.
Figure 2–10 shows the Process Activities selection of the Component Palette. This list
enables you to select activities to drag and drop into your BPEL process.
2-10 Oracle BPEL Process Manager Developer’s Guide
Overview of the BPEL Designer Environment
Figure 2–10 Component Palette - Process Activities
Figure 2–11 shows the Services selection of the Component Palette. This list enables
you to drag and drop adapters, partner links, or decision services into your BPEL
process.
Figure 2–11 Component Palette - Services
Figure 2–12 shows the String Functions category of the Component Palette that
displays when you work in the transformation window of a transform activity.
Getting Started with Oracle BPEL Process Manager
2-11
Overview of the BPEL Designer Environment
Figure 2–12 Component Palette - Functions
If you want to learn more about the Component Palette, place
the cursor in this section and press F1 to display online Help.
Note:
Property Inspector
The Property Inspector shown in the lower right part of Figure 2–2 enables you to
view details about an activity. Single-click an activity in the Diagram window. For
example, single-clicking the receiveInput receive activity shown in Figure 2–5 on
page 2-7 displays the information shown in Figure 2–13.
Figure 2–13 Property Inspector
Structure Window
The Structure Window shown in the lower left part of Figure 2–2 offers a structural
view of the data in the project currently selected in the Diagram window. You can
perform a variety of tasks from this section, including:
■
Importing project schemas
■
Defining message types
■
■
Managing (creating, editing, and deleting) elements such as variables, aliases,
correlation sets, partner links, and sensors
Editing activities in the BPEL process flow sequence that displays in the Diagram
window
2-12 Oracle BPEL Process Manager Developer’s Guide
Overview of the BPEL Designer Environment
Figure 2–14 shows the Structure Window. In this example, the window has been
expanded to display the imported project schemas and the sequence of activities in the
Diagram window for an OrderBooking project.
Figure 2–14 Structure Window (Expanded)
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 project.
Ensure that the files have unique names.
Log Window
You validate, compile, and deploy a process by right-clicking the project name in the
Application Navigator, selecting Deploy, and selecting a deployment method. The
Log Window shown at the bottom of Figure 2–2 then displays messages about the
status of the deployment.
To ensure that a process validates correctly, you must ensure that the following
information is correct:
■
The process must have an input variable.
■
A partner link must be selected.
■
A partner role must be selected.
■
The operation must not be empty.
■
The input variable type must match the partner link operation type.
Figure 2–15 shows a successful deployment message for a BPEL process. You can then
run, monitor, and administer the process from Oracle BPEL Control.
Getting Started with Oracle BPEL Process Manager
2-13
Overview of the BPEL Designer Environment
Figure 2–15 Successful Deployment Message
If deployment is unsuccessful, messages appear that describe the type and location of
the error, as shown in Figure 2–16. Double-click the error to navigate directly to the
offending line in the source file referenced.
Figure 2–16 Unsuccessful Deployment Message
If you want to learn more about the Log Window, place the
cursor in this section and press F1 to display online Help.
Note:
See Also:
■
■
"Overview of Oracle BPEL Control" on page 2-17
Chapter 19, "BPEL Process Deployment and
Domain Management" for specific details about deploying and
running BPEL processes
Editing Project Files in Oracle JDeveloper
Note the following issues when editing the bpel.xml, WSDL, and BPEL files:
■
■
■
The bpel.xml file content is only read into memory when the file is opened.
Therefore, if you change the content of bpel.xml after the file is opened, the
changes are not made in memory. After changing the content of the BPEL file, close
and reopen the file for the changes to take effect.
Do not edit the bpel.xml file through a combination of Oracle JDeveloper and a
text editor such as Notepad or Wordpad. Use only a single editing environment
such as Oracle JDeveloper.
Do not edit the bpel.xml file, BPEL files, and WSDL files while changing the
design of the process. If you want to edit a file:
1.
Ensure that the BPEL files are not being edited in Oracle JDeveloper. If they
are being edited (that is, a tab for that file is visible), close it and save changes
as needed.
2.
Edit the required file and save the changes.
2-14 Oracle BPEL Process Manager Developer’s Guide
Overview of Activities
Overview of Activities
The term activities has been mentioned frequently in both Chapter 1, "Introduction to
Oracle BPEL Process Manager" and in this chapter. Activities are the building blocks of
a BPEL process. Oracle JDeveloper includes a set of activities that you drag and drop
into a BPEL process. You then double-click an activity to define its attributes (property
values). Figure 2–6 on page 2-7 provides an example of this design process. Activities
enable you to perform specific tasks within a process. 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.
A receive activity waits for an asynchronous callback response message from a
service.
Figure 2–17 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.
Figure 2–17 Invoke Activity Example
Getting Started with Oracle BPEL Process Manager
2-15
Overview of Partner Links
See Also:
■
■
■
■
Appendix B, "BPEL Process Activities and Services" for
descriptions of available activities
Part II, "Reviewing Key BPEL Development Concepts and Code
Samples" for activity concepts and code examples
SOA_Oracle_Home\bpel\samples\references directory for
additional activity code examples
Oracle BPEL Process Manager Quick Start Guide and Oracle BPEL
Process Manager Order Booking Tutorial for tutorials in which you
drag and drop activities in BPEL processes and define their
attributes
Overview of Partner Links
The term partner link has also been mentioned frequently in both Chapter 1,
"Introduction to Oracle BPEL Process Manager" and in this chapter. A partner link
enables you to define the external services with which the BPEL process is to interact.
Figure 2–18 shows the partner link icon (in this example, named CreditRating).
Figure 2–18 PartnerLink Icon
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 2–6 on page 2-7 shows an example of a partner link named
WriteDBRecord being invoked by a BPEL process.
Figure 2–19 shows an example of the attributes of a partner link for a service named
CreditRating.
2-16 Oracle BPEL Process Manager Developer’s Guide
Overview of Oracle BPEL Control
Figure 2–19 PartnerLink Window
Table 2–4 describes the fields of the PartnerLink window.
Table 2–4
PartnerLink Window Fields
Field
Description
Name
A unique and recognizable name you provide for the partner link.
WSDL File
The name and location of the Web Services Description Language
(WSDL) file that you select for the partner link. Click the Service
Explorer flashlight icon (second icon from the left above the WSDL
File field) to access a window for selecting the WSDL file to use.
Partner Link Type
The partner link defined in the WSDL file.
Partner Type
The role performed by the partner link (in this example, the
CreditRatingService service). In this case, CreditRatingService is the
provider.
My Role
The role performed by the BPEL process. In this case, the BPEL process
does not have a role because it is a synchronous process.
Overview of Oracle BPEL Server
After you complete the design of the BPEL process, you compile and deploy the
process to Oracle BPEL Server. If compilation and deployment are successful, you can
run and manage the BPEL process from Oracle BPEL Control.
Deployment sends the Oracle BPEL Process Manager archive (a set of files in a JAR file
with a directory structure similar to the project directory structure) to Oracle BPEL
Server. The deployment operation automatically validates and compiles the project
directory into the BPEL archive.
See Also: Chapter 19, "BPEL Process Deployment and
Domain Management"
Overview of Oracle BPEL Control
Oracle BPEL Control enables you to run, monitor, and administer BPEL processes
designed and deployed with Oracle JDeveloper. You can also manage BPEL domains
Getting Started with Oracle BPEL Process Manager
2-17
Overview of Oracle BPEL Process Manager Services
from Oracle BPEL Control. Access Oracle BPEL Control on Windows by selecting Start
> All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL
Control.
Figure 2–20 shows the main page of Oracle BPEL Control. In this example, a number
of deployed BPEL processes and external services appear in the Dashboard tab.
Figure 2–20 Oracle BPEL Control
See Also:
■
■
■
"Starting Oracle BPEL Process Manager Components" on page 2-2
for instructions on accessing Oracle BPEL Control on UNIX
Chapter 19, "BPEL Process Deployment and
Domain Management" for specific details about running a
deployed process from Oracle BPEL Control
Oracle BPEL Process Manager Quick Start Guide and Oracle BPEL
Process Manager Order Booking Tutorial for tutorials in which you
run deployed BPEL processes
Overview of Oracle BPEL Process Manager Services
Oracle BPEL Process Manager and Oracle JDeveloper provide support for services that
add value and ease of use to BPEL functionality.
Table 2–5 identifies and describes the services and provides references to sections of
this guide that describe their capabilities.
2-18 Oracle BPEL Process Manager Developer’s Guide
Overview of Oracle BPEL Process Manager Services
Table 2–5
Oracle BPEL Process Manager Services
Types
Description
See Section
Transformations
A transform activity is provided that enables you
to create transformations that map source data to
target data. For example, you can map incoming
purchase order source data into outgoing
purchase order acknowledgment target data.
Chapter 13, "XSLT
Mapper and
Transformations"
Notification channels enable you to send
notifications about an event to a user, group, or
destination address. You can send a notification
by e-mail, voice mail, fax, pager, or short
message service (SMS).
Chapter 14,
"Oracle BPEL
Process Manager
Notification Servic
e"
Notification channels
"Transform
Activity" on
page B-29
Appendix B,
"BPEL Process
Activities and
Services"
Workflows
Workflow enables you to integrate systems and
services with human workflow into a single
process flow.
Chapter 15,
"Oracle BPEL
Process Manager
Workflow
Services"
A Human Task editor is provided that enables
you to specify human task settings, such as task
outcome, payload structure, task participants,
"Human Task
assignment and routing policy, expiration and
Activity" on
escalation policy, notification settings, and so on. page B-12
The criteria that you define with the Human
Task editor enables you to use the Oracle BPEL
Worklist Application when you run the BPEL
process.
Oracle BPEL Worklist
Application
Oracle BPEL Worklist Application takes actions
on tasks such as approving an employee
vacation request, evaluating a job applicant, or
escalating a purchasing decision. Based on the
user profile, you access a URL that enables you
to see all the tasks relevant to you and specify
search criteria for displaying tasks.
Chapter 16,
"Worklist
Application"
Sensors
You create sensors that you assign to activities,
variables, and faults that you want to monitor
during BPEL process run time.
Chapter 17,
"Sensors"
Business rules
You integrate BPEL processes with the rules
defined in a business rule engine.
Chapter 18, "BPEL
Process Integration
with Business
Rules"
See Also: The following documentation for tutorials that describe
how to design BPEL processes that use the services described in
Table 2–5
■
■
Oracle BPEL Process Manager Order Booking Tutorial
"Getting Started with Demonstrations, Activity and Conceptual
References, and Tutorials" on page 1-6
Getting Started with Oracle BPEL Process Manager
2-19
Overview of Oracle BPEL Process Manager Technology Adapters
Overview of Oracle BPEL Process Manager Technology Adapters
The Partner Link Window shown in Figure 2–19 on page 2-17 also enables you to take
advantage of another key feature that Oracle BPEL Process Manager and Oracle
JDeveloper provide. Click the Define Adapter Service icon shown in Figure 2–21 to
access the Adapter Configuration wizard.
Figure 2–21 Defining an Adapter
Adapters enable you to integrate the BPEL processes with access to file systems, FTP
servers, 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 2–22 for use with the BPEL process:
Figure 2–22 Adapter Types
When you select an adapter type, the Service Name window shown in Figure 2–23
prompts you to enter a name. For this example, File Adapter was selected in
Figure 2–22. When the wizard completes, a WSDL file by this service name appears in
the Application Navigator for the BPEL process (for this example, named
ReadFile.wsdl). This file includes the adapter configuration settings you specify with
this wizard. Other configuration files (such as header files and files specific to the
adapter) are also created and display in the Application Navigator.
2-20 Oracle BPEL Process Manager Developer’s Guide
Summary
Figure 2–23 Adapter Service Name
The Adapter Configuration wizard windows that appear after the Service Name
window are based on the adapter type you selected.
See Also:
■
■
■
■
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide for specific details about configuring the file, FTP,
database, AQ, MQ, and JMS adapters in a BPEL process with the
Adapter Configuration wizard
Oracle Application Server Adapter for Oracle Applications User’s Guide
for information on using the Oracle Applications adapter for
Oracle E-Business Suite
"PartnerLink" on page B-36
Oracle BPEL Process Manager Order Booking Tutorial for tutorials
that describe how to design BPEL processes that use the database
adapter and the file read and write functionality of the file adapter
Summary
This chapter describes how to start key Oracle BPEL Process Manager components,
including Oracle JDeveloper, Oracle BPEL Server, and Oracle BPEL Control. An
overview of the main sections of Oracle JDeveloper that you use to design BPEL
processes is also provided. Key BPEL design components such as activities and
partner links and the services and adapters that Oracle BPEL Process Manager
provides to add value and ease of use to standard BPEL functionality are also
described.
Getting Started with Oracle BPEL Process Manager
2-21
Summary
2-22 Oracle BPEL Process Manager Developer’s Guide
Part II
Reviewing Key BPEL Development
Concepts and Code Samples
This part introduces key BPEL development concepts and code samples.
This part contains the following chapters:
■
Chapter 3, "Manipulating XML Data in BPEL"
■
Chapter 4, "Invoking a Synchronous Web Service"
■
Chapter 5, "Invoking an Asynchronous Web Service"
■
Chapter 6, "Parallel Flow"
■
Chapter 7, "Conditional Branching"
■
Chapter 8, "Fault Handling"
■
Chapter 9, "Incorporating Java and J2EE Code in BPEL Processes"
■
Chapter 10, "Events and Timeouts"
■
Chapter 11, "Invoking a BPEL Process"
■
Chapter 12, "Interaction Patterns"
3
Manipulating XML Data in BPEL
This chapter describes how to manipulate XML data in BPEL, including the use of
XPath expressions.
This chapter contains the following topics:
■
Use Cases for Manipulating XML Data in BPEL
■
Overview of Manipulating XML Data in BPEL Concepts
■
Initializing a Variable with Expression Constants or Literal XML
■
Copying Between Variables
■
Accessing Fields Within Complex Type Variables
■
Assigning Numeric Values
■
Mathematical Calculations with XPath Standards
■
Assigning String Literals
■
Concatenating Strings
■
Assigning Boolean Values
■
Assigning Date or Time
■
Manipulating Attributes
■
Manipulating XML Data Sequences That Use Arrays
■
Converting from a String to an XML Element
■
Differences Between Document-Style and RPC-Style WSDL Files
■
Using Binary Attachments in SOAP Messages
■
Summary
Use Cases for Manipulating XML Data in BPEL
This chapter covers a variety of use cases for manipulating XML data. Topics include
how to work with variables, sequences, and arrays, and how to perform tasks such as
mathematical calculations. The explanations are largely by example, and provide an
introduction to the supporting specifications.
Most of the examples in this chapter assume that the WSDL file defining the associated
message types is document-literal style rather than the RPC style. There is a difference
in how XPath query strings are formed for RPC-style WSDL definitions. If you are
working with a type defined in an RPC WSDL file, see "Differences Between
Document-Style and RPC-Style WSDL Files" on page 3-14.
Manipulating XML Data in BPEL 3-1
Overview of Manipulating XML Data in BPEL Concepts
See Also:
■
The sample files located at
SOA_Oracle_
Home\bpel\samples\tutorials\103.XMLDocuments
Overview of Manipulating XML Data in BPEL Concepts
This section covers the following topics:
■
How XML Data Works in BPEL
■
About Data Manipulation and XPath Standards
How XML Data Works in BPEL
In a BPEL process, every piece of data is in XML format. This includes the messages
passed to and from the BPEL process, the messages exchanged with external services,
and local variables used by the flow. You define the types for these messages and
variables with the XML schema, usually in the WSDL file for the flow or in the WSDL
files for the services it invokes. Therefore, all variables in BPEL are XML data, and any
BPEL process uses much of its code to manipulate these XML variables. This typically
includes performing data transformation between representations required for
different services, and local manipulation of data (for example, to combine the results
from several service invocations).
About Data Manipulation and XPath Standards
The starting point for data manipulation in BPEL is the assign activity, which builds on
the XPath standard. XPath queries, expressions, and functions play a large part in this
type of manipulation. In addition, more advanced methods are available that involve
using XQuery, XSLT, or Java, usually to do more complex data transformation or
manipulation.
This section provides a general overview of how to manipulate XML data in BPEL. It
summarizes the key building blocks used in various combinations and provides
examples. The remaining sections in this chapter discuss and illustrate how to apply
these building blocks to perform specific tasks.
You use the assign activity to copy data from one XML variable to another, or to
calculate the value of an expression and store it in a variable. A copy element within
the activity specifies the source and target of the assignment (what to copy from and
to), which must be of compatible types. The formal syntax as shown in the Business
Process Execution Language for Web Services Specification is as follows:
<assign standard-attributes>
standard-elements
<copy>+
from-spec
to-spec
</copy>
</assign>
This syntax is described in detail in that specification. The from-spec and to-spec
typically specify a variable or variable part, as in:
<assign>
<copy>
<from variable="c1" part="address"/
<to variable="c3"/>
3-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Manipulating XML Data in BPEL Concepts
</copy>
</assign>
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.
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. For example:
<from variable="input" part="payload"
query="/p:CreditFlowRequest/p:ssn">
For XPath version 1.0, the value of the query attribute must be an absolute 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. 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.
■
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.
Manipulating XML Data in BPEL 3-3
Initializing a Variable with Expression Constants or Literal XML
■
BPEL XPath extension functions: Oracle provides some additional XPath
functions that use the capabilities built into BPEL and XPath standards for adding
new functions.
These functions are defined in the namespace
http://schemas.oracle.com/xpath/extension and indicated by the
prefix ora:.
See Also:
■
Appendix D, "XPath Extension Functions"
Custom functions: You can also create custom XPath functions. If you do, you
must register them in the BPEL process deployment descriptor or in the following
XML files:
–
SOA_Oracle_
Home\bpel\domains\default\config\xpath-functions.xml
Then, package the source implementing them into a BPEL suitcase or Oracle BPEL
Process Manager startup environment. For more information about writing
custom XPath functions, refer to:
http://www.oracle.com/technology/bpel
Sophisticated data manipulation can be difficult to perform with the BPEL assign
activity and the core XPath functions. However, you can perform complex data
manipulation and transformation by using XSLT or Java, or as a Web service. For more
information on calling Java code from within BPEL, see the tutorial under the BPEL
Tutorials link at http://www.oracle.com/technology/bpel. For XSLT, Oracle
BPEL Process Manager includes XPath functions that execute these transformations.
See Also: The following XPath and XQuery transformation code
examples:
■
■
SOA_Oracle_
Home\bpel\samples\tutorials\114.XSLTTransformations
Chapter 13, "XSLT Mapper and Transformations"
The following sections show related definitions in the BPEL and WSDL files that help
explain the examples.
Initializing a Variable with Expression Constants or Literal XML
It is often useful to assign literal XML to a variable in BPEL, for example, to initialize a
variable before copying dynamic data into a specific field within the XML data content
for the variable. This is also useful for testing purposes when you want to hard code
XML data values into the process.
This example assigns a literal result element to the payload part of the output
variable:
<assign>
<!-- copy from literal xml to the variable -->
<copy>
<from>
<result xmlns="http://samples.otn.com">
<name/>
<symbol/>
<price>12.3</price>
<quantity>0</quantity>
<approved/>
3-4 Oracle BPEL Process Manager Developer’s Guide
Accessing Fields Within Complex Type Variables
<message/>
</result>
</from>
<to variable="output" part="payload"/>
</copy>
</assign>
See Also:
■
The following samples:
SOA_Oracle_Home\bpel\samples\references\Assign
Copying Between Variables
When you copy between variables, you copy directly from one variable (or part) to
another variable of a compatible type, without needing to specify a particular field
within either variable. In other words, there is no need to specify an XPath query.
The following example performs two assignments, first copying between two
variables of the same type and then copying a variable part to another variable with
the same type as that part.
<assign>
<copy>
<from variable="c1"/>
<to variable="c2"/>
</copy>
<copy>
<from variable="c1" part = "address"/>
<to variable="c3"/>
</copy>
</assign>
The BPEL file defines the variables as follows:
<variable name="c1" messageType="x:person"/>
<variable name="c2" messageType="x:person"/>
<variable name="c3" element="x:address"/>
The WSDL file defines the person message type as follows:
<message name="person" xmlns:x="http://tempuri.org/bpws/example">
<part name="full-name" type="xsd:string"/>
<part name="address" element="x:address"/>
</message>
Section 9.3.2 of the Business Process Execution Language for
Web Services Specification for this code example
See Also:
Accessing Fields Within Complex Type Variables
Given the types of definitions present in most WSDL files, you must go down to the
level of copying from or to a field within part of a complex type variable. To do this,
you specify an XPath query in the from or to clause of the assign activity.
This example copies the ssn field from the CreditFlow process’s input message into
the ssn field of the credit rating service’s input message.
<assign>
<copy>
<from variable="input" part="payload"
query="/tns:CreditFlowRequest/tns:ssn"/>
Manipulating XML Data in BPEL 3-5
Assigning Numeric Values
<to variable="crInput" part="payload" query="/tns:ssn"/>
</copy>
</assign>
The BPEL file defines the variables involved in this assignment as follows:
<variable name="input" messageType="tns:CreditFlowRequestMessage"/>
<variable name="crInput"
messageType="services:CreditRatingServiceRequestMessage"/>
The crInput variable is used as an input message to a credit rating service. Its
message type, CreditFlowRequestMessage, is defined in
CreditFlowService.wsdl as follows:
<message name="CreditFlowRequestMessage">
<part name="payload" element="tns:CreditFlowRequest"/>
</message>
CreditFlowRequest is defined with a field named ssn. The message type
CreditRatingServiceRequestMessage is defined in
CreditRatingService.wsdl as follows:
<message name="CreditRatingServiceRequestMessage">
<part name="payload" element="tns:ssn"/>
</message>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\utils\CreditRatingService
Assigning Numeric Values
You can assign numeric values in XPath expressions. The following example shows
how to assign an XPath expression with the integer value 100.
<assign>
<!-- copy from integer expression to the variable -->
<copy>
<from expression="100"/>
<to variable="output" part="payload" query="/p:result/p:quantity"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\Assign
Mathematical Calculations with XPath Standards
You can use simple mathematical expressions like the one in the following example,
which increments a numeric value.
In this example, the BPEL XPath function getVariableData retrieves the value
being incremented. The arguments to getVariableData are equivalent to the
variable, part, and query attributes of the from clause (including the last two
arguments, which are optional).
<assign>
<copy>
<from expression="bpws:getVariableData('input', 'payload',
3-6 Oracle BPEL Process Manager Developer’s Guide
Concatenating Strings
'/p:value') + 1"/>
<to variable="output" part="payload" query="/p:result"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\Assign
Assigning String Literals
This example copies an expression evaluating from the string literal 'GE' to the
symbol field within the indicated variable part. (Note the use of the double and single
quotes.)
<assign>
<!-- copy from string expression to the variable -->
<copy>
<from expression="'GE'"/>
<to variable="output" part="payload" query="/p:result/p:symbol"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\Assign
Concatenating Strings
Rather than copy the value of one string variable (or variable part or field) to another,
you first can perform string manipulation, such as concatenating several strings
together. An example is shown in the following syntax. The concatenation is
accomplished with the core XPath function named concat; in addition, the variable
value involved in the concatenation is retrieved with the BPEL XPath function
getVariableData.
In this example, getVariableData fetches the value of the name field from the
input variable’s payload part. The string literal 'Hello ' is then concatenated to
the beginning of this value.
<assign>
<!-- copy from XPath expression to the variable -->
<copy>
<from expression="concat('Hello ',
bpws:getVariableData('input', 'payload', '/p:name'))"/>
<to variable="output" part="payload" query="/p:result/p:message"/>
</copy>
</assign>
Other string manipulation functions available in XPath are listed in section 4.2 of the
XML Path Language (XPath) Specification.
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\Assign
Manipulating XML Data in BPEL 3-7
Assigning Boolean Values
Assigning Boolean Values
In this example of assigning Boolean values, the XPath expression in the from clause
is a call to XPath’s Boolean function true, and the specified approved field is set to
true. The function false is also available.
<assign>
<!-- copy from boolean expression function to the variable -->
<copy>
<from expression="true()"/>
<to variable="output" part="payload" query="/result/approved"/>
</copy>
</assign>
The XPath specification recommends that you use the "true()" and "false()"
functions as a method for returning Boolean constant values.
If you instead use "boolean(true)" or "boolean(false)", the true or false
inside the Boolean function is interpreted as a relative element step, and not as any
true or false constant. 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.
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\Assign
Assigning Date or Time
You can assign the current value of a date or time field by using the BPEL XPath
function getCurrentDate, getCurrentTime, or getCurrentDateTime,
respectively. In addition, if you have a date-time value in the standard XSD format,
you can convert it to characters more suitable for output by calling the BPEL XPath
function formatDate.
For related information, see section 9.1.2 of the Business Process Execution Language for
Web Services Specification.
<!-- execute the XPath extension function getCurrentDate() -->
<assign>
<copy>
<from expression="ora:getCurrentDate()"/>
<to variable="output" part="payload"
query="/invoice/invoiceDate"/>
</copy>
</assign>
In the next example, 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).
<!-- execute the XPath extension function formatDate() -->
<assign>
<copy>
<from expression="ora:formatDate('2005-06-10T15:56:00',
'MMM dd, yyyy')"/>
<to variable="output" part="payload"
query="/invoice/formattedDate"/>
</copy>
</assign>
3-8 Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences That Use Arrays
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\references\XPathFunction
Manipulating Attributes
You may want to copy to or from something defined as an XML attribute. An at sign
(@) in XPath query syntax refers to an attribute instead of a child element.
The following code example fetches and copies the custId attribute from this XML
data:
<invalidLoanApplication xmlns="http://samples.otn.com">
<application xmlns = "http://samples.otn.com/XPath/autoloan">
<customer custId = "111" >
<name>
Mike Olive
</name>
...
</customer>
...
</application>
</invalidLoanApplication>
The following example selects the custId attribute of the customer field and assigns
it to the variable custId:
<assign>
<!-- get the custId attribute and assign to variable custId -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/@custId"/>
<to variable="custId"/>
</copy>
</assign>
The namespace prefixes in this example are optional and not integral to the example.
The WSDL file defines a customer to have a type in which custId is defined as an
attribute, as follows:
<complexType name="CustomerProfileType">
<sequence>
<element name="name" type="string"/>
...
</sequence>
<attribute name="custId" type="string"/>
</complexType>
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\XPath
Manipulating XML Data Sequences That Use Arrays
Data sequences are one of the most basic data models used in XML. However,
manipulating them can be nontrivial. One of the most common data sequence patterns
used in BPEL processes are arrays. Based on the XML schema, the way you can
identify a data sequence definition is by its attribute maxOccurs being set to a value
Manipulating XML Data in BPEL 3-9
Manipulating XML Data Sequences That Use Arrays
of more than one or marked as unbounded. See the XML Schema Specification at
http://www.w3.org/TR for more information.
The examples in this section illustrate several basic ways of manipulating data
sequences in BPEL. However, there are other associated requirements, such as
performing looping or dynamic referencing of endpoints. For additional code samples
and further information regarding real-world use cases for data sequence
manipulation in BPEL, see http://www.oracle.com/technology/bpel.
Each of the following sections describes a particular requirement for data sequence
manipulation. For a code example that describes all data sequences, see
ArraySample.bpel, which takes a data sequence as input and loops through it,
adding together individual line items in each data sequence element into a total value.
See Also:
■
The ArraySample.bpel sample file located at:
SOA_Oracle_Home\bpel\samples\tutorials\112.Arrays
Statically Indexing 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 the following example, addresses[1] selects the first element of the addresses
data sequence:
<assign>
<!-- get the first address and assign to variable address -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/autoloan:addresses[1]"/>
<to variable="address"/>
</copy>
</assign>
In this query, addresses[1] is equivalent to addresses[position()=1], where
position is one of the core XPath functions (see sections 2.4 and 4.1 of the XML Path
Language (XPath) Specification). The query in the next example 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).
<assign>
<!-- get the first address's street and assign to street1 -->
<copy>
<from variable="input" part="payload"
query="/tns:invalidLoanApplication/autoloan:application
/autoloan:customer/autoloan:addresses[position()=1]
/autoloan:street"/>
<to variable="street1"/>
</copy>
</assign>
If you review the definition of the input variable and its payload part in the WSDL file,
you go several levels down before coming to the definition of the addresses field.
There you see the maxOccurs="unbounded" attribute. The two XPath indexing
methods are functionally identical; you can use whichever method you prefer.
3-10 Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences That Use Arrays
See Also:
■
The following sample:
SOA_Oracle_Home\bpel\samples\references\XPath
Determining Sequence Size
If you need to know the run-time size of a data sequence—that is, the number of nodes
or data items in the sequence—you can get it by using the combination of the XPath
built-in count() function and the BPEL built-in getVariableData() function.
This example calculates the number of elements in the item sequence and assigns it to
the integer variable lineItemSize:
<assign>
<copy>
<from expression="count(bpws:getVariableData(’outpoint’, ’payload’,
'/p:invoice/p:lineItems/p:item')"/>
<to variable="lineItemSize"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\references\XPathFunction
Dynamically Indexing by Applying a Trailing XPath to an Expression
Often a dynamic value is needed to index into a data sequence—that is, you need to
get the nth node out of a sequence, where the value of n is defined at run time. This
section covers the following methods for dynamically indexing by applying a trailing
XPath into expressions:
■
Dynamic Indexing Example
■
Using the bpel:append Extension to Append New Items to a Sequence
■
Merging Data Sequences
■
Dynamically Indexing with the BPEL getElement Function
Dynamic Indexing Example
The dynamic indexing method shown here applies a trailing XPath to the result of
bwps:getVariableData(), instead of using an XPath as the last argument of
bpws:getVariableData(). The trailing XPath references to an integer-based index
variable within the position predicate (that is, [...]):
<variable name="idx" type="xsd:integer"/>
...
<assign>
<copy>
<from expression="bpws:getVariableData('input','payload'
)/p:line-item[bpws:getVariableData('idx')]/p:line-total" />
<to variable="lineTotalVar" />
</copy>
</assign>
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" />
Manipulating XML Data in BPEL 3-11
Manipulating XML Data Sequences That Use Arrays
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')
If the XPath is used trailing behind the bwps:getVariableData()function, the root
element name does not need to be specified in the XPath.
For example:
bpws:getVariableData('input', 'payload')/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
standard XPath semantics.
Using the bpel:append Extension to Append New Items to a Sequence
The bpelx:append extension under assign enables BPEL processes to append new
elements to an existing parent element:
<assign name="assign-3">
<copy>
<from expression="bpws:getVariableData('idx')+1" />
<to variable="idx"/>
</copy>
<bpelx:append>
<bpelx:from variable="partInfoResultVar" part="payload" />
<bpelx:to variable="output" part="payload" />
</bpelx:append>
...
</assign>
The bpelx:append logic in this example appends the payload element of the
partInfoResultVar variable as a child to the payload element of the output
variable. In others words, the payload element of output variable is used as the
parent element.
See Also:
■
■
The following samples:
"Assign Activity" on page B-3 for details about using multiple
copies of this extension in a single assign activity
SOA_Oracle_
Home\bpel\samples\tutorials\126.DataAggregator\Ag
gregationTutorial
Merging Data Sequences
You can merge two sequences into a single data sequence. This pattern is common
when the data sequences are in an array (that is, the sequence of data items of
compatible types).
3-12 Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences That Use Arrays
The following two append operations under assign demonstrate how to merge data
sequences:
<assign>
<!-- initialize "mergedLineItems" variable
to an empty element -->
<copy>
<from> <p:lineItems /> </from>
<to variable="mergedLineItems" />
</copy>
<bpelx:append>
<bpelx:from variable="input" part="payload"
query="/p:invoice/p:lineItems/p:lineitem" />
<bpelx:to variable="mergedLineItems" />
</bpelx:append>
<bpelx:append>
<bpelx:from variable="literalLineItems"
query="/p:lineItems/p:lineitem" />
<bpelx:to variable="mergedLineItems" />
</bpelx:append>
</assign>
See Also:
■
The ArraySample.bpel sample file located at:
SOA_Oracle_Home\bpel\samples\tutorials\112.Arrays
Dynamically Indexing with the BPEL getElement Function
If you do not want to use the two-step process of creating an XPath query to
dynamically index into a sequence, you can use the XPath function getElement
instead. This function takes a sequence and an index (which can be a dynamic value,
such as a variable) and returns the appropriate sequence element.
<variable name="lineItemIndex" type="xsd:int"/>
...
<!-- execute the XPath extension function getElement(arrayOfElements[],
index) to fetch one element from an array of elements
-->
<assign>
<copy>
<from expression="ora:getElement('output', 'payload',
'/invoice/lineItems/item',
bpws:getVariableData('lineItemIndex'))"/>
<to variable="myLineItem"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\references\XPathFunction
SOAP-Encoded Arrays Not Supported
Oracle BPEL Process Manager does not support SOAP-encoded arrays
(soapenc:arrayType).
Use one of the following workarounds:
■
Apache Axis supports document-literal style services. This means you can change
the service to not use soapenc:arrayType.
Manipulating XML Data in BPEL 3-13
Converting from a String to an XML Element
■
■
A wrapper can be placed around the service (also using Apache Axis) so that the
BPEL process talks to the document literal wrapper service, which in turn calls the
underlying service with soapenc:arrayType.
Call a service with soapenc:arrayType from BPEL, but construct the XML
message more manually in the BPEL code. This enables you to avoid changing or
wrapping the service. However, each time you want to call that service from BPEL,
you must take extra steps.
Converting from a String to an XML Element
Sometimes a service is defined to return a string, but the content of the string is
actually XML data. The problem is that, although BPEL provides support for
manipulating XML data (using XPath queries, expressions, and so on), this
functionality is not available if the variable or field is of type string. With Java, you use
document object model (DOM) functions to convert the string to a structured XML
object type. You can use the BPEL XPath function parseEscapedXML to do the same
thing. This function takes XML data, parses it through DOM, and returns structured
XML data that can be assigned to a typed BPEL variable. For example:
<!-- execute the XPath extension function
parseEscapedXML('&lt;item&gt;') and assign to a variable
-->
<assign>
<copy>
<from expression="ora:parseEscapedXML(
'&lt;item xmlns=&quot;http://samples.otn.com&quot;
sku=&quot;006&quot;&gt;
&lt;description&gt;sun ultra sparc VI server
&lt;/description&gt;
&lt;price&gt;1000
&lt;/price&gt;
&lt;quantity&gt;2
&lt;/quantity&gt;
&lt;lineTotal&gt;2000
&lt;/lineTotal&gt;
&lt;/item&gt;')"/>
<to variable="escapedLineItem"/>
</copy>
</assign>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\references\XPathFunction
Differences Between Document-Style and RPC-Style WSDL Files
The examples shown up to this point have been for document-style WSDL files, in
which a message is defined with an XML schema element, as in the following
example:
<message name="LoanFlowRequestMessage">
<part name="payload" element="s1:loanApplication"/>
</message>
This is in contrast to RPC-style WSDL files, in which the message is defined with an
XML schema type, as in:
3-14 Oracle BPEL Process Manager Developer’s Guide
Differences Between Document-Style and RPC-Style WSDL Files
<message name="LoanFlowRequestMessage">
<part name="payload" type="s1:LoanApplicationType"/>
</message>
This affects the material in this chapter because there is a difference in how XPath
queries are constructed for the two WSDL message styles. For an RPC-style message,
the top-level element (and therefore the first node in an XPath query string) is the part
name (payload in the previous example). In document-style, the top-level node is the
element name (for example, loanApplication).
The following example shows what an XPath query string looks like if the
LoanServices used in BPEL demo applications (such as LoanFlow) were RPC style.
RPC-Style WSDL File
<message name="LoanServiceResultMessage">
<part name="payload" type="s1:LoanOfferType"/>
</message>
<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>
RPC-Style BPEL File
<variable name="output"
messageType="tns:LoanServiceResultMessage"/>
...
<assign>
<copy>
<from expression="9.9"/>
<to variable="output" part="payload" query="/payload/APR"/>
</copy>
</assign>
See Also:
The following samples:
■
SOA_Oracle_
Home\bpel\samples\utils\AsyncLoanService
(LoanServices)
■
SOA_Oracle_
Home\bpel\samples\demos\LoanDemo\LoanFlow (BPEL
demo application)
Enclosing the Operation Name with RPC-Style WSDL Messages
If you use RPC-style messaging, you must enclose the input XML message with an
operation name (in the following example, process):
<process xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">
<payload xmlns=""
xmlns:client="http://xmlns.oracle.com/MessageParts_referingToComplexTypes"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="client:TestInput">
<input
xmlns="http://xmlns.oracle.com/MessagePartsreferingToComplexTypes">yoo</input
Manipulating XML Data in BPEL 3-15
Using Binary Attachments in SOAP Messages
>
<input1
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">boo</input
1>
<input2
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">woo</input
2>
<input3
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">foo</input
3>
<input4
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">goo</input
4>
</payload>
</process>
If you want to verify the correctness of the XML file, set the validateXML property to
true in the Manage BPEL Domain window of Oracle BPEL Control.
Using Binary Attachments in SOAP Messages
There are two supported methods for transferring opaque data in a SOAP call:
■
Embedding data
This method embeds opaque data as element or attribute content. XML supports
opaque data as content through either base64 or hexadecimal text encoding. XML
schema's two binary data types, xs:base64Binary and xs:hexBinary, are
used with this method. Since the opaque data is converted to a basic XML schema
type, it can be manipulated like other XML data in a BPEL process in terms of
being assigned, sent, and received in standard BPEL activities.
Data encoded in base64 format expands by a factor of 1.33 times the original size.
Hexadecimal encoded data expands by a factor of 2 times. This is assuming an
underlying UTF-8 text encoding is used in both cases; if the underlying text
encoding used is UTF-16, these numbers double. To achieve better performance at
both the SOAP layer and BPEL execution layer, keep the original data as it is when
transferring it through SOAP. The second method described below, SOAP with an
attachment, provides a technique for doing this.
■
SOAP with an attachment
SOAP with an attachment can be achieved through use of HTTP with the
Multipurpose Internet Mail Extensions (MIME) or Direct Internet Message
Encapsulation (DIME) protocols. The SOAP envelope and opaque data are
wrapped in MIME or DIME sections.
The following example shows a message using SOAP with an attachment through
use of the MIME protocol. The attachment is passed by reference through use of an
identifying key, instead of being copied. Note that with MIME, the XML part and
the binary part must appear in separate parts. The XML part contains a reference
to the binary attachment part. This differs from DIME, which does not have this
restriction.
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary;
type=text/xml; start="<mymessage.xml@collaxa.com>"
Content-Description: A SOAP Envelope with pdf
--MIME_boundary
3-16 Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@collaxa.com>
<s:Envelope xmlns:s='http://www.w3.org/2002/12/soap-envelope' >
<s:Body>
<m:applyLoan xmlns:m='http://samples.Collaxa.com/MIMEService' >
<customerName>John Doe</customerName>
<pdf data="1234567890" />
</m:applyLoan>
</s:Body>
</s:Envelope>
--MIME_boundary
Content-Type: application/pdf
Content-Transfer-Encoding: binary
Content-Location: 1234567890
fd a5 8a 29 aa 46 1b 24
--MIME_boundary
The binary data is still typed as base64binary or hexBinary. However, the
data remains in binary format through transporting and processing. There is no
overhead added with encoding and decoding.
Notes:
■
If you use large binary attachment files in SOAP messages with
Oracle Database Lite, your BPEL process may not complete
processing, which can cause you to run out of system memory.
Oracle Database Lite is largely for testing purposes. To use large
binary attachment files in SOAP messages, use an Oracle
Database as your dehydration store.
See Also:
■
SOA_Oracle_Home\bpel\samples\demos\Attachment for
demonstrations of using SOAP with an attachment through
MIME and DIME
Use Case: SOAP Message with Binary Attachment Using MIME
This section provides a use case and describes design implementation issues. You
cannot currently model a SOAP message with an attachment through Oracle
JDeveloper. You must manually edit the necessary BPEL and WSDL files.
In this use case:
■
■
The BPEL process acts as a service to receive and reply to a SOAP message with an
attachment.
The BPEL process acts as a client to send and receive a response to a SOAP
message with an attachment.
■
Binary data is assigned to another variable.
■
Binary data is read from a URL.
■
Binary data is saved to a local file.
Two BPEL processes are constructed:
Manipulating XML Data in BPEL 3-17
Using Binary Attachments in SOAP Messages
■
■
MIMEService is essentially an echo service of a SOAP message with an
attachment. This process does the following:
–
Receives a SOAP message with an attachment and saves the opaque data to a
local file.
–
Assigns the opaque data to an output variable.
–
Uses the output variable to reply to a SOAP message with an attachment to
the invoker.
MIMERequester is the client of the first service. This process does the following:
–
Reads the binary data from a URL and assigns it to a variable.
–
Uses the variable as input to perform an invoke on the first process.
–
Receives a SOAP message with an attachment.
WSDL File Contents
The following WSDL file defines MIMEService. This file uses the WSDL binding
MIME extension to define the SOAP message with an attachment.
<?xml version="1.0" encoding="UTF-8"?>
<definitions
. . .
. . .
<types>
. . .
. . .
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/ws/2003/03/addressing"
schemaLocation="http://gmi-pc:9700/orabpel/xmllib/ws-addressing.xsd" />
</schema>
</types>
<message name="ReplyToHeader">
<part name="ReplyTo" element="wsa:ReplyTo" />
</message>
<message name="MessageIDHeader">
<part name="MessageID" element="wsa:MessageID" />
</message>
<message name="RelatesToHeader">
<part name="RelatesTo" element="wsa:RelatesTo" />
</message>
<message name="MIMEServiceRequestMessage">
<part name="payload" type="xsd:int"/>
<part name="bin" type="xsd:anyType"/>
</message>
<message name="MIMEServiceResponseMessage">
<part name="payload" type="xsd:int"/>
<part name="bin" type="xsd:anyType"/>
</message>
<portType name="MIMEService">
<operation name="initiate">
<input message="tns:MIMEServiceRequestMessage"/>
</operation>
<operation name="process">
<input message="tns:MIMEServiceRequestMessage"/>
<output message="tns:MIMEServiceResponseMessage"/>
</operation>
3-18 Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
</portType>
<portType name="MIMEServiceCallback">
<operation name="onResult">
<input message="tns:MIMEServiceResponseMessage"/>
</operation>
</portType>
<binding name="MIMEServiceBinding" type="tns:MIMEService">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="initiate">
<soap:operation style="rpc" soapAction="initiate"/>
<input>
<mime:multipartRelated>
<mime:part>
<soap:header message="tns:MessageIDHeader"
part="MessageID" use="literal"/>
<soap:header message="tns:ReplyToHeader"
part="ReplyTo" use="literal"/>
<soap:body parts="payload" use="literal"/>
</mime:part>
<mime:part>
<mime:content part="bin" type="binary"/>
</mime:part>
</mime:multipartRelated>
</input>
</operation>
<operation name="process">
<soap:operation style="rpc" soapAction="process"/>
<input>
<mime:multipartRelated>
<mime:part>
<soap:header message="tns:RelatesToHeader"
part="RelatesTo" use="literal"/>
<soap:body parts="payload" use="literal"/>
</mime:part>
<mime:part>
<mime:content part="bin" type="binary"/>
</mime:part>
</mime:multipartRelated>
</input>
<output>
<mime:multipartRelated>
<mime:part>
<soap:body parts="payload" use="literal"/>
</mime:part>
<mime:part>
<mime:content part="bin" type="binary"/>
</mime:part>
</mime:multipartRelated>
</output>
</operation>
</binding>
<binding name="MIMEServiceCallbackBinding" type="tns:MIMEServiceCallback">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="onResult">
<soap:operation style="rpc" soapAction="onResult"/>
<input>
<mime:multipartRelated>
Manipulating XML Data in BPEL 3-19
Using Binary Attachments in SOAP Messages
<mime:part>
<soap:header message="tns:RelatesToHeader"
part="RelatesTo" use="literal"/>
<soap:body use="literal" />
</mime:part>
<mime:part>
<mime:content part="bin" type="binary"/>
</mime:part>
</mime:multipartRelated>
</input>
</operation>
</binding>
<plnk:partnerLinkType name="MIMEService">
<plnk:role name="MIMEServiceProvider">
<plnk:portType name="tns:MIMEService"/>
</plnk:role>
<plnk:role name="MIMEServiceRequester">
<plnk:portType name="tns:MIMEServiceCallback"/>
</plnk:role>
</plnk:partnerLinkType>
</definitions>
In this WSDL, the schema type of the binary data is xsd:anyType. This is because
xsd:binary was deprecated from XSD version 2000 to version 2001. (Web Services
Description Language (WSDL) Specification 1.1 has an example using xsd:binary. This
has become an outstanding issue.)
To ensure that payload validation is successful, use xsd:anyType with either MIME
or DIME.
BPEL File Contents
The MIMERequester.bpel file shows how to use binary data in BPEL:
<process . . .
. . .
. . .
<sequence>
<!-- receive input from requestor -->
<receive name="receiveInput" partnerLink="client"
portType="tns:MIMERequester"
operation="initiate" variable="input"
createInstance="yes"/>
<!-- initialize the input of MIMEService -->
<assign>
<copy>
<from variable="input" part="payload" query="/tns:value"/>
<to variable="request" part="payload" query="/payload"/>
</copy>
<copy>
<from expression="ora:readBinaryFromFile('request.bin')"/>
<to variable="request" part="bin"/>
</copy>
</assign>
<invoke name="invoke" partnerLink="MIMEService"
portType="services:MIMEService"
operation="initiate" inputVariable="request"/>
<receive name="receive" partnerLink="MIMEService"
3-20 Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
portType="services:MIMEServiceCallback"
operation="onResult" variable="response"/>
<assign>
<copy>
<from variable="response" part="payload" query="/payload"/>
<to variable="request" part="payload" query="/payload"/>
</copy>
<copy>
<from expression="ora:writeBinaryToFile('response', 'bin',
'C:/Temp/response.bin')"/>
<to variable="response" part="bin"/>
</copy>
<copy>
<from expression="ora:readBinaryFromFile('request2.bin')"/>
<to variable="request" part="bin"/>
</copy>
</assign>
<invoke name="invoke" partnerLink="MIMEService"
portType="services:MIMEService"
operation="process" inputVariable="request"
outputVariable="response"/>
<assign>
<copy>
<from variable="response" part="payload" query="/payload"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
<copy>
<from expression="ora:writeBinaryToFile('response', 'bin',
'C:/Temp/response2.bin')"/>
<to variable="response" part="bin"/>
</copy>
</assign>
<!-- respond output to requestor -->
<invoke name="replyOutput" partnerLink="client"
portType="tns:MIMERequesterCallback"
operation="onResult" inputVariable="output"/>
</sequence>
</process>
In this example, XPath extension function ora:readBinaryFromFile( ) reads the
binary file and ora:writeBinaryToFile( ) writes the binary content to a file.
The binary data can be assigned to another variable like a normal XML document by
using the standard BPEL assign activity. The BPEL assign activity is extended here to
accommodate the binary data.
Java Client Using SAAJ
MIMEService can be accessed from a Java client. There are two access options:
■
Java API for XML-Based RPC (JAX-RPC)
■
SOAP with Attachments API Java (SAAJ)
Example 3–1 uses Axis’ implementation of SAAJ to invoke MIMEService. This
example is used to unit test the interoperability of the created service. The sample
request sent by this example is shown in Example 3–2 on page 3-23.
Example 3–1 SAAJ Example
public boolean initiateUsingSAAJ(String filename) throws Exception {
Manipulating XML Data in BPEL 3-21
Using Binary Attachments in SOAP Messages
String endPointURLString = "http://localhost:" +opts.getPort() +
"/orabpel/default/MIMEService/1.0";
SOAPConnectionFactory soapConnectionFactory =
javax.xml.soap.SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection =
soapConnectionFactory.createConnection();
MessageFactory messageFactory =
MessageFactory.newInstance();
SOAPMessage soapMessage =
messageFactory.createMessage();
MimeHeaders hd = soapMessage.getMimeHeaders();
hd.addHeader("SOAPAction", "initiate");
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope requestEnvelope =
soapPart.getEnvelope();
SOAPBody body = requestEnvelope.getBody();
SOAPBodyElement operation = body.addBodyElement
(requestEnvelope.createName("initiate"));
Vector dataHandlersToAdd = new Vector();
dataHandlersToAdd.add(new DataHandler(new FileDataSource(new
File(filename))));
javax.xml.soap.SOAPElement element1 =
operation.addChildElement(requestEnvelope.createName("payload"));
element1.addTextNode("1");
if (dataHandlersToAdd != null) {
ListIterator dataHandlerIterator =
dataHandlersToAdd.listIterator();
while (dataHandlerIterator.hasNext()) {
DataHandler dataHandler = (DataHandler)
dataHandlerIterator.next();
javax.xml.soap.SOAPElement element =
operation.addChildElement(requestEnvelope.createName("bin"));
javax.xml.soap.AttachmentPart attachment =
soapMessage.createAttachmentPart(dataHandler);
soapMessage.addAttachmentPart(attachment);
element.addAttribute(requestEnvelope.createName
("href"), "cid:" + attachment.getContentId());
}
}
javax.xml.soap.SOAPMessage returnedSOAPMessage =
soapConnection.call(soapMessage, endPointURLString);
if (returnedSOAPMessage == null)
return true;
Iterator iterator = returnedSOAPMessage.getAttachments();
if (!iterator.hasNext()) {
//The wrong type of object that what was expected.
System.out.println("Received problem response from server");
throw new AxisFault("", "Received problem response from server", null,
null);
}
//Still here, so far so good.
//Now lets brute force compare the source attachment
3-22 Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
// to the one we received.
DataHandler rdh = (DataHandler)
((AttachmentPart)iterator.next()).getDataHandler();
//From here we'll just treat the data resource as file.
String receivedfileName = rdh.getName();//Get the filename.
if (receivedfileName == null) {
System.err.println("Could not get the file name.");
throw new AxisFault("", "Could not get the file name.", null, null);
}
System.out.println("Going to compare the files..");
boolean retv = compareFiles(filename, receivedfileName);
java.io.File receivedFile = new java.io.File(receivedfileName);
receivedFile.delete();
return retv;
}
}
Example 3–2 shows the sample request sent by the SAAJ program:
Example 3–2 Sample Request
POST /orabpel/default/MIMEService/1.0 HTTP/1.0Content-Type: multipart/related;
type="text/xml"; start="<F090DFD56421FD84AAF98C386AD50A44>"; boundary="----=_
Part_0_27211574.1133404205718"Accept: application/soap+xml, application/dime,
multipart/related, text/*User-Agent: Axis/1.2.1Host: gmi-pc:1234Cache-Control:
no-cachePragma: no-cacheSOAPAction: "initiate"Content-Length: 9307------=_Part_0_
27211574.1133404205718Content-Type: text/xml;
charset=UTF-8Content-Transfer-Encoding: binaryContent-Id:
<F090DFD56421FD84AAF98C386AD50A44><?xml version="1.0"
encoding="UTF-8"?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><initiate
xmlns=""><payload xmlns="">1</payload><bin
href="cid:1A744998BA8527BD121CAE96C022109F"
xmlns=""/></initiate></soapenv:Body></soapenv:Envelope>------=_Part_0_
27211574.1133404205718Content-Type:
application/octet-streamContent-Transfer-Encoding: binaryContent-Id:
<1A744998BA8527BD121CAE96C022109F>
.....................
Manipulating XML Data in BPEL 3-23
Summary
See Also:
The following documentation:
■
http://www.xml.com/pub/a/2003/02/26/binaryxml.html
for XML, SOAP, and Binary Data
■
http://msdn.microsoft.com/msdnmag/issues/02/12/DIME
/default.aspx for DIME: Sending Files, Attachments, and SOAP
Messages Via Direct Internet Message Encapsulation
■
http://gotdotnet.com/team/xml_
wsspecs/dime/WSDL-Extension-for-DIME.htm for WSDL
Extension for SOAP in DIME
■
http://www.w3.org/TR/wsdl.html for Web Services
Description Language (WSDL) Specification 1.1
Displaying the Attachment Key for Binary Attachments Using the DIME Protocol in
Oracle BPEL Control
The optSoapShortcut parameter value defaults to true in Oracle BPEL Control. This
setting causes BPEL processes with SOAP message binary attachments that use the
Direct Internet Message Encapsulation (DIME) protocol to not display their attachment
key in the Oracle BPEL Control audit trail for the process instance. This is because the
binary attachment file is not saved to the dehydration database. Instead, an HTML file
displays in the audit trail. For example:
<PutCompanyInfo>
. . .
. . .
<report href="C:\orabpel\domains\default\tmp\.bpel_DIMERequester_
1.0.jar\report.html"
/>
</PutCompanyInfo>
As a workaround, set optSoapShortcut to false in Oracle BPEL Control. This enables
the file to be saved to the dehydration store and the attachment key to display in the
audit trail for the instance (instead of the HTML file). Copy and paste the attachment
key into the Attachment Key field at the bottom of the audit trail window and click
download to save it as a file for viewing. If you do this, note that the File Download
message initially prompts you to save the attachment key as a JSP file type. Instead,
save the file as an HTML file type.
Summary
This chapter provides an overview of the role of XML data in BPEL processes,
including describing the large role that XPath expressions play in manipulating XML
data.
3-24 Oracle BPEL Process Manager Developer’s Guide
4
Invoking a Synchronous Web Service
Synchronous Web services provide an immediate response to a query. BPEL can
connect to synchronous Web services through a partner link, send data, and then
receive the reply using a synchronous callback.
This chapter contains the following topics:
■
Use Case for Synchronous Web Services
■
Overview of Synchronous Service Concepts
■
Calling a Synchronous Service
■
Summary
Use Case for Synchronous Web Services
Using synchronous Web services is demonstrated in 104.SyncQuoteConsumer. This
sample shows a BPEL process sending a stock code to a Web service and receiving a
stock quote in return. It examines how synchronous functionality is defined in the
stock quote Web service’s CreditRatingService.wsdl file (the Web service to be
called) and the client’s QuoteConsumer.bpel file and bpel.xml deployment
description file.
This chapter demonstrates how to establish a partner link and set up a synchronous
callback. It discusses the components necessary to perform a synchronous callback,
examines how these components are coded, and shows how to set up a synchronous
callback.
See Also:
The following files are used as examples in this chapter.
■
SOA_Oracle_
Home\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel
\QuoteConsumer.bpel
■
SOA_Oracle_
Home\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel
\bpel.xml
■
SOA_Oracle_
Home\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel
\QuoteConsumer.wsdl
■
SOA_Oracle_
Home\bpel\samples\utils\104.StockQuoteService\bpel\Sto
ckQuoteService.wsdl
Invoking a Synchronous Web Service 4-1
Overview of Synchronous Service Concepts
Overview of Synchronous Service Concepts
A synchronous callback requires the following components:
■
■
Partner link: Defines the location and the role of the Web services that the BPEL
process connects to in order to perform tasks, as well as the variables used to carry
information between the Web service and the BPEL process. A partner link is
required for each Web service that the BPEL process calls.
Invoke activity: Opens a port in the BPEL process to send and receive data. It uses
this port to submit the required data and receive the response. In the credit rating
service example, the invoke activity submits the stock code entered by the
customer to the stock quote service and receives a stock quote in return. For
synchronous callbacks, only one port is needed for both the send and receive
functions.
Each domain has the attribute syncMaxWaitTime. This attribute has a default of 60
seconds, but can be reconfigured by the domain administrator. If the BPEL process
does not receive a reply within the specified time, then the activity fails.
See Also: Oracle Application Server Performance Guide for additional
details about syncMaxWaitTime
Establishing the Partner Link
This section covers the following topics:
■
Defining the Partner Link in the BPEL Code
■
Using the WSDL File to Enable the Web Services to Work with a BPEL Process
■
Performing Lookups for Services that Use Partner Links
■
Accessing Web Services on Remote Servers
Defining the Partner Link in the BPEL Code
In the BPEL code, the partner link defines the link name and type, and the role of the
BPEL process in interacting with the partner service.
From the BPEL source code, the StockQuoteService partner link definition is as
follows:
<partnerLinks>
<!-The 'client' role represents the requester of this service. It is
used for callback. The location and correlation information associated
with the client role are automatically set using WS-Addressing.
-->
<partnerLink name="client" partnerLinkType="samples:QuoteConsumer"
myRole="QuoteConsumerProvider" partnerRole="QuoteConsumerRequester"/>
<partnerLink
name="StockQuoteService"partnerLinkType="services:StockQuoteService"
partnerRole="StockQuoteServiceProvider"/>
</partnerLinks>
Following the partner link are global variable definitions that are accessible
throughout the BPEL process. The types for these variables are defined in the WSDL
for the process itself.
<variables>
<!-- Reference to the message passed as input during initiation -->
<variable name="input" messageType="tns:QuoteConsumerRequestMessage"/>
4-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Synchronous Service Concepts
<!-- Reference to the message that will be sent back to the
requestor during callback
-->
<variable name="output" messageType="tns:QuoteConsumerResultMessage"/>
<variable name="request" messageType="services:StockQuoteServiceRequest"/>
<variable name="response" messageType="services:StockQuoteServiceResponse"/>
</variables>
The WSDL file defines the interface to your BPEL process—the messages that it
accepts and returns, operations that are supported, and other parameters.
Using the WSDL File to Enable the Web Services to Work with a BPEL Process
The Web service’s QuoteConsumer.wsdl file contains two sections that enable it to
work with BPEL processes:
■
partnerLinkType Section of the QuoteConsumer.wsdl File
■
portType Section of the QuoteConsumer.wsdl File
partnerLinkType Section of the QuoteConsumer.wsdl File
The partnerLinkType section of the QuoteConsumer.wsdl file defines the
following characteristics of the conversion between a BPEL process and the loan
application approver Web service:
■
■
The role (operation) played by each
The portType provided by each for receiving messages within the context of the
conversation
<!-PartnerLinkType definition
-->
<!-- the QuoteConsumer partnerLinkType binds the service and
requestor portType into an asynchronous conversation.
-->
<plnk:partnerLinkType name="QuoteConsumer">
<plnk:role name="QuoteConsumerProvider">
<plnk:portType name="tns:QuoteConsumer"/>
</plnk:role>
<plnk:role name="QuoteConsumerRequester">
<plnk:portType name="tns:QuoteConsumerCallback"/>
</plnk:role>
</plnk:partnerLinkType>
portType Section of the QuoteConsumer.wsdl File
A port type is a collection of related operations implemented by a participant in a
conversation. A port type defines what information is passed back and forth, the form
of that information, and so forth. A synchronous callback requires only one port type
that both sends a request and receives the response, while an asynchronous callback
(one where the reply is not immediate) requires two port types, one to send the
request, and another to receive the reply when it arrives.
View the portType section of the QuoteConsumer.wsdl file. This is the stock quote
Web service to which the client submits the stock code that the customer has entered.
<!-PortType definition
-->
<!-- portType implemented by the QuoteConsumer BPEL process -->
Invoking a Synchronous Web Service 4-3
Overview of Synchronous Service Concepts
<portType name="QuoteConsumer">
<operation name="initiate">
<input message="tns:QuoteConsumerRequestMessage"/>
</operation>
</portType>
<!-- portType implemented by the requester of QuoteConsumer BPEL process
for asynchronous callback purposes
-->
<portType name="QuoteConsumerCallback">
<operation name="onResult">
<input message="tns:QuoteConsumerResultMessage"/>
</operation>
</portType>
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.
Performing Lookups for Services that Use Partner Links
A Universal Description, Discovery, and Integration (UDDI) browser is provided for
looking up services when creating a partner link. Web Services Inspection Language
(WSIL) and UDDI assist in the publishing and discovery of services.
UDDI is a Web-based distributed directory that enables businesses to list themselves
on the Internet and discover each other, similar to a traditional phone book’s yellow
and white pages. The specification provides a high level of functionality through the
sample object access protocol (SOAP) by specifically requiring an infrastructure to be
deployed.
WSIL approaches service discovery in a decentralized fashion, where service
description information can be distributed to any location using a simple extensible
XML document format. Unlike UDDI, it is not concerned with business entity
information, nor does it specify a particular service description format. WSIL works
under the assumption that you are already familiar with the service provider, and
relies on other service description mechanisms such as WSDL.
To access this registry when creating a partner link, you must first create a connection
to the UDDI registry:
1.
Right-click UDDI Registry in the Connection Navigator of Oracle JDeveloper.
2.
Select New UDDI Registry Connection.
3.
Follow the wizard steps to create a connection.
Accessing Web Services on Remote Servers
When creating a partner link, you can also select Web services on remote servers. To
specify the remote location, edit
SOA_Oracle_Home\bpel\system\services\install\config\inspection.wsil
The Web service is then accessible from Oracle JDeveloper. Click the Service Explorer
icon when creating a partner link on the Create Partner Link window. This displays
the Service Explorer window, which enables you to select the remote Web service.
See Also:
"PartnerLink" on page B-36
4-4 Oracle BPEL Process Manager Developer’s Guide
Calling a Synchronous Service
Using the Invoke Activity to Perform a Request
The invoke activity includes the request global input variable defined in the
variables section. The credit rating Web service uses this request global input
variable. This variable contains the customer’s social security number. The response
variable contains the credit rating returned by the credit rating service.
<sequence>
<!-- Receive input from requestor. Note: This maps to operation defined in
QuoteConsumer.wsdl
-->
<receive name="receiveInput" partnerLink="client" portType="samples:QuoteConsumer"
operation="initiate" variable="input" createInstance="yes"/>
<assign>
<copy>
<from variable="input" part="payload" query="/tns:symbol"/>
<to variable="request" part="symbol" query="/symbol"/>
</copy>
</assign>
<!-- Generate content of output message based on the content of the input message.
-->
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"/>
<assign>
<copy>
<from variable="response" part="result" query="/result"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
</assign>
<!-- Asynchronous callback to the requester. Note: the callback location and
correlation id is transparently handled using WS-addressing. -->
<invoke name="replyOutput" partnerLink="client"
portType="samples:QuoteConsumerCallback" operation="onResult"
inputVariable="output"/>
</sequence>
See Also:
"Invoke Activity" on page B-14
Calling a Synchronous Service
This section examines a synchronous callback operation using the
QuoteConsumer.bpel file. For a more step-by-step approach, see
http://www.oracle.com/technology/bpel and download the files under
Training Material.
Figure 4–1 shows the diagram of the QuoteConsumer.bpel file, which defines a
simple application with five activities.
Invoking a Synchronous Web Service 4-5
Calling a Synchronous Service
Figure 4–1 Diagram of QuoteConsumer.bpel
The following actions take place:
1.
The receiveInput receive activity receives input from the user (client), as defined
in the QuoteConsuter.wsdl file.
2.
The first assign activity packages the data from the client so that it can be accepted
by the invokeStockQuote service.
3.
The invokeStockQuoteService activity sends the repackaged data to the
StockQuoteService service and receives a response.
4.
A second assign activity repackages this response into a replyOutput activity so
that it can be accepted by the client application.
5.
The replyOutput activity sends the repackaged response back to the client.
The following BPEL code performs the synchronous callback:
<assign>
<copy>
<from variable="input" part="payload" query="/tns:symbol"/>
<to variable="request" part="symbol" query="/symbol"/>
</copy>
</assign>
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"
portType="services:StockQuoteService" operation="process"
inputVariable="request" outputVariable="response"/>
4-6 Oracle BPEL Process Manager Developer’s Guide
Summary
<!-- 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>
Summary
This chapter describes the concepts for a BPEL process that invokes a synchronous
Web service and adds a partner link. This service takes a stock code as input from a
client and synchronously returns a stock quote.
Invoking a Synchronous Web Service 4-7
Summary
4-8 Oracle BPEL Process Manager Developer’s Guide
5
Invoking an Asynchronous Web Service
This chapter describes how to call an asynchronous Web service. Asynchronous
messaging styles are very useful for environments in which a service, such as a loan
processor, can take a long time to process a client request. Asynchronous services also
provide a more reliable fault-tolerant and scalable architecture than synchronous
services.
This chapter contains the following topics:
■
Use Case for Asynchronous Web Services
■
Overview of Asynchronous Callback Concepts
■
Calling an Asynchronous Service
■
Using Correlation Sets in an Asynchronous Service
■
Summary
Use Case for Asynchronous Web Services
United Loan publishes an asynchronous Web service that processes a client’s loan
application request and then returns a loan offer. This use case discusses how to
integrate a BPEL process with this asynchronous loan application approver Web
service.
This use case illustrates the key design concepts for requesting information from an
asynchronous service, and then receiving the response. The asynchronous United
Loan service in this example is another BPEL process. However, the same BPEL call
can interact with any properly designed Web service. The target Web service WSDL
file contains the information necessary to request and receive the desired information.
Figure 5–1 provides an overview of how this BPEL process works with the
asynchronous loan processor Web service.
Invoking an Asynchronous Web Service 5-1
Use Case for Asynchronous Web Services
Figure 5–1 Asynchronous Service Invocation
Deployment Descriptor
(bpel.xml)
Client
Application
WSDL
Client
PartnerLink
Oracle
BPEL
Control
BPEL Process
Input
<variable>
d1
<receive>
prepare
loanApp
<assign>
Initiate
service
<invoke>
Wait for
callback
<receive>
Request
<variable>
d3
d4
WSDL
LoanService
PartnerLink
Initiate Port
Callback Port
Async
Loan
Processor
Service
Response
<variable>
Read
offer
<assign>
d2
<reply>
Output
<variable>
Dehydration Point
For scalability and reliability,
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’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 5–1.
5-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
See Also: The following sample file for examples of an asynchronous
Web service that is not a BPEL process:
■
SOA_Oracle_
Home\bpel\samples\interop\axis\BPELCallingAsyncAXIS
Overview of Asynchronous Callback Concepts
This section examines how asynchronous functionality is defined in the loan
application approver Web service’s LoanService.wsdl file (the Web service to be
called) and the client’s LoanBroker.bpel file and bpel.xml deployment
description file. It covers the following topics:
■
partnerLinkTypes for Asynchronous Services
■
Calling the Service from BPEL
■
How the Invoke and Receive Activities Work
■
Managing Multiple Active BPEL Process Instances Using Correlation Methods
■
Using the Reply Activity to Send Messages in Response to a Receive Activity
■
Using Dehydration Points to Maintain Long-Running Asynchronous Processes
See Also:
The following files are used as examples in this chapter.
■
SOA_Oracle_
Home\bpel\samples\utils\AsyncLoanService\LoanServic
e.wsdl
■
SOA_Oracle_
Home\bpel\samples\tutorials\105.AsyncCompositeLoanB
roker\bpel\LoanBroker.bpel
■
SOA_Oracle_
Home\bpel\samples\tutorials\105.AsyncCompositeLoanB
roker\bpel\bpel.xml
partnerLinkTypes for Asynchronous Services
The following sections in the Web service’s LoanService.wsdl file enable it to work
with BPEL processes:
■
portType Section of the LoanService.wsdl File
■
partnerLinkType Section of the LoanService.wsdl File
See Also:
"PartnerLink" on page B-36
portType Section of the LoanService.wsdl File
The portType section of the LoanService.wsdl file defines the ports to be used for
the asynchronous service.
Asynchronous services have two port types. Each port type performs a one-way
operation: one port type initiates the asynchronous process and the other calls back the
client with the asynchronous response. In this example, the portType LoanService
receives the client’s loan application request and the portType
LoanServiceCallback asynchronously calls back the client with the loan offer
response.
Invoking an Asynchronous Web Service 5-3
Overview of Asynchronous Callback Concepts
<!-- portType implemented by the LoanService BPEL process -->
<portType name="LoanService">
<operation name="initiate">
<input message="tns:LoanServiceRequestMessage"/>
</operation>
</portType>
<!-- portType implemented by the requester of LoanService BPEL process
for asynchronous callback purposes
-->
<portType name="LoanServiceCallback">
<operation name="onResult">
<input message="tns:LoanServiceResultMessage"/>
</operation>
</portType>
partnerLinkType Section of the LoanService.wsdl File
The partnerLinkType section of the LoanService.wsdl file defines the following
characteristics of the conversation between the BPEL process and the loan application
approver Web service:
■
■
The role (operation) played by each
The portType provided by each for receiving messages within the context of the
conversation
Partner link types in asynchronous services have two roles: one for the Web service
provider and one for the client requester.
In this conversation, the LoanServiceProvider role and LoanService portType
are used for client request messages and the LoanServiceRequester role and
LoanServiceCallback portType are used for asynchronously returning (calling
back) response messages to the client.
<!-- the LoanService partnerLinkType binds the service and
requestor portType into an asynchronous conversation.
-->
<plnk:partnerLinkType name="LoanService">
<plnk:role name="LoanServiceProvider">
<plnk:portType name="tns:LoanService"/>
</plnk:role>
<plnk:role name="LoanServiceRequester">
<plnk:portType name="tns:LoanServiceCallback"/>
</plnk:role>
</plnk:partnerLinkType>
Two port types are combined into this single asynchronous BPEL process:
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,
there are two operations to perform: initiate in the invoke activity and onResult
in the receive activity.
Calling the Service from BPEL
To call the service from BPEL, you need the following files to define how the process
interfaces with the Web service:
5-4 Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
■
Partner Links Section in the .bpel File
■
Deployment Descriptor File
Partner Links Section in the .bpel File
View the partnerLinks section of the LoanBroker.bpel file. The services with
which a process interacts are designed as partner links. Each partner link is
characterized by a partnerLinkType.
Each partner link is named. This name is used for all service interactions through that
partner link. This is critical in correlating responses to different partner links for
simultaneous requests of the same type.
Asynchronous processes use a second partner link for the callback to the client. In this
example, the second partner link, LoanService, is used by the loan application
approver Web service.
<!-- This process invokes the asynchronous LoanService. -->
<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.
Deployment Descriptor File
Open the bpel.xml deployment descriptor file of
samples\tutorials\105.AsyncCompositeLoanBroker. The loan application
approver Web service appears. This properties id information is added to the file
when you create a second partner link type.
<?xml version="1.0"?>
<bpel-process id="LoanBroker" src="LoanBroker.bpel"
wsdlLocation="LoanBroker.wsdl">
<properties id="LoanService">
<property name="wsdlLocation">
http://hslattertest-pc:9700/orabpel/default/UnitedLoan/UnitedLoan?wsdl</property>
</properties>
See Also:
■
■
"Step 1: Adding a Partner Link for an Asynchronous Service" on
page 5-11 for instructions on creating a partner link
Appendix C, "Deployment Descriptor Properties"
How the Invoke and Receive Activities Work
View the variables and sequence sections of the LoanBroker.bpel file. Two
areas of particular interest concern the invoke and receive activities:
■
An invoke activity invokes a synchronous Web service (as discussed in
Chapter 4, "Invoking a Synchronous Web Service") or initiates an asynchronous
service.
The invoke activity includes the request global input variable defined in the
variables section. The request global input variable is used by the loan
Invoking an Asynchronous Web Service 5-5
Overview of Asynchronous Callback Concepts
application approver Web service. This variable contains the contents of the initial
loan application request document.
■
A receive activity that waits for the asynchronous callback from the loan
application approver Web service. The receive activity includes the response
global output variable defined in the variables section. This variable contains
the loan offer response. The receive activity asynchronously waits for a callback
message from a service. While the BPEL process is waiting, it is dehydrated, or
compressed and stored, until the callback message arrives.
<variables>
<variable name="request"
messageType="services:LoanServiceRequestMessage"/>
<variable name="response"
messageType="services:LoanServiceResultMessage"/>
</variables>
<sequence>
<!-- initialize the input of LoanService -->
<assign>
<!-- initiate the remote process -->
<invoke name="invoke" partnerLink="LoanService"
portType="services:LoanService"
operation="initiate" inputVariable="request"/>
<!-- receive the result of the remote process -->
<receive name="receive_invoke" partnerLink="LoanService"
portType="services:LoanServiceCallback"
operation="onResult" variable="response"/>
When an asynchronous service is initiated with the invoke activity, a correlation ID
unique to the client request is also sent, using WS-Addressing (described in
"WS-Addressing" on page 5-7). Because multiple processes may be waiting for service
callbacks, Oracle BPEL Server must know which BPEL process instance is waiting for a
callback message from the loan application approver Web service. The correlation ID
enables Oracle BPEL Server to correlate the response with the appropriate requesting
instance.
See Also: The following sections for instructions on creating invoke
and receive activities:
■
"Step 2: Adding an Invoke Activity" on page 5-12
■
"Step 3: Adding a Receive Activity" on page 5-13
■
"Invoke Activity" on page B-14
■
"Receive Activity" on page B-20
Using the createInstance Attribute to Start a New Instance
You may have noticed a createInstance attribute in the initial receive activity of
the sequence section of the LoanBroker.bpel file. In this initial receive activity,
the createInstance element is set to yes. This starts a new instance of the BPEL
process. At least one instance startup is required for a conversation. For this reason,
you set the createInstance variable to no in the second receive activity.
The source code for the createInstance attribute appears as follows:
5-6 Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
<!-- receive input from requestor -->
<receive name="receiveInput" partnerLink="client"
portType="tns:LoanBroker"
operation="initiate" variable="input"
createInstance="yes"/>
Managing Multiple Active BPEL Process Instances Using Correlation Methods
Because there can be many active instances at any given point in time, Oracle BPEL
Server must be able to direct Web service responses to the correct BPEL process
instance. You can use the following correlation methods to identify asynchronous
messages to ensure that asynchronous callbacks locate the appropriate client:
■
WS-Addressing
■
Using Correlation Sets to Coordinate Asynchronous Message Body Contents
WS-Addressing
Web Services Addressing (WS-Addressing) is a public specification and is the default
correlation method supported by Oracle BPEL Process Manager. You do not need to
edit the .bpel and .wsdl files to use WS-Addressing. WS-Addressing uses simple
object access protocol (SOAP) headers for asynchronous message correlation.
Messages are independent of the transport or application used. Figure 5–2 provides an
overview.
Figure 5–2 Callback with WS-Addressing Headers
WS-Addressing Header:
· callback location
· correlation id (relatesTo)
BPEL Process
HelloWorld.bpel
WSDL
LoanService
PartnerLink
loanApp
<variable>
Initiate
service
<invoke>
d3
d3
[2.05] receive
[2.06] process
[2.22] callback
Initiate Port
Async
Loan
Processor
Service
loanOffer
<variable>
Wait for
callback
<receive>
d3
Callback Port
d4
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 5–2 shows how messages are passed along with WS headers so that the
response can be sent to the correct destination.
Invoking an Asynchronous Web Service 5-7
Overview of Asynchronous Callback Concepts
The example in this chapter uses WS-Addressing for correlation. To view the
messages, you can use TCP tunneling, which is described in "Using TCP Tunneling to
See Messages Exchanged Between Programs" on page 5-8.
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 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 flow communicates.
You insert a software listener between your BPEL process flow and the Web
service. Your BPEL process 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.
Using TCP Tunneling to See Messages Exchanged Between Programs
The messages that are exchanged between programs and services can be seen through
TCP tunneling. This is particularly useful with Web services and BPEL processes when
you want to see the exact SOAP messages exchanged between the BPEL process flow
and Web services.
To monitor the SOAP messages, insert a software listener between your flow and the
service. Your flow communicates with the listener (called a TCP tunnel) and the
listener forwards your messages to the service, as well as displaying them. Likewise,
responses from the service are returned to the tunnel, which displays them and then
forwards them back to the flow.
To see all the messages exchanged between Oracle BPEL Server and a Web service,
you need only a single TCP tunnel for synchronous services because all the pertinent
messages are communicated in a single request and reply interaction with the service.
For asynchronous services, you must set up two tunnels, one for the invocation of the
service and another for the callback port of the flow.
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
2.
Add a location property in the bpel.xml deployment descriptor file for your
flow to override the endpoint of the service. For example, to see the messages
5-8 Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
exchanged between the LoanFlow demo sample and the CreditRatingService that
it calls, change the definition of the CreditRatingService location as shown below
in the LoanFlow deployment descriptor in SOA_Oracle_
Home\bpel\samples\demos\LoanDemo\LoanFlow\bpel.xml:
<partnerLinkBinding name="creditRatingService">
<property name="wsdlLocation">
http://localhost:9700/orabpel/default/CreditRatingService/
CreditRatingService?wsdl
</property>
<property name="location">
http://localhost:1234/orabpel/default/CreditRatingService
</property>
</partnerLinkBinding>
3.
Compile and deploy the LoanDemo from the operating system command prompt:
prompt> cd SOA_Oracle_Home\bpel\samples\demos\LoanDemo
prompt> ant
Note that while the CreditRatingService is also a BPEL process, the same
technique can be used to see the SOAP messages passed to invoke a BPEL process
as a Web service from another tool kit such as Axis or .NET.
See Also:
The TCP Monitor tool located in the following directory:
SOA_Oracle_Home\bpel\bin\obtunnel.bat
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:
3.
a.
Click Manage BPEL Domain in the upper right of Oracle BPEL Control.
b.
Scroll down to the optSoapShortcut property.
c.
Change the value from true to false.
Access Oracle BPEL Admin Console at:
http://localhost:9700/BPELAdmin
where 9700 in the port if you installed Oracle BPEL Process Manager for
Developers.
4.
Scroll down to the SoapServerUrl property on the Configuration tab.
5.
Change this property to http://localhost:9710.
6.
Click the Apply button.
7.
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.
Invoking an Asynchronous Web Service 5-9
Overview of Asynchronous Callback Concepts
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.
See Also:
■
■
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
Using Correlation Sets to Coordinate Asynchronous Message Body Contents
Correlation sets are a BPEL mechanism that provides for the correlation of
asynchronous messages based on message body contents. To use this method, define
the correlation sets in your .bpel file. This method is designed for services that do not
support WS-Addressing or for certain sophisticated conversation patterns, for
example, when the conversation is in the form A > B > C > A instead of A > B >
A.
See Also:
■
■
The following correlation set examples:
"Using Correlation Sets in an Asynchronous Service" on page 5-14
for a tutorial on creating correlations sets in Oracle JDeveloper
SOA_Oracle_
Home\bpel\samples\tutorials\109.CorrelationSets
Using the Reply Activity to Send Messages in Response to a Receive Activity
The reply activity enables the business process to send a message in reply to a
message that was received through a receive activity. The combination of a receive
and a reply forms a request-response operation on the WSDL portType for the
process.
<reply partnerLink="ncname" portType="qname" operation="ncname"
variable="ncname"? faultName="qname"?
standard-attributes>
standard-elements
<correlations>?
<correlation set="ncname" initiate="yes|no"?>+
</correlations>
</reply>
See Also:
■
"Returning External Faults" on page 8-4
■
"Reply Activity" on page B-21
■
SOA_Oracle_Home\bpel\samples\references\Reply
Using Dehydration Points to Maintain Long-Running Asynchronous Processes
To automatically maintain long-running asynchronous processes and their current
state information in a database while they wait for asynchronous callbacks, you use a
database as a dehydration store. Storing the process in a database preserves the
process and prevents any loss of state or reliability if a system shuts down or a
network problem occurs. This feature increases both BPEL process reliability and
scalability. You can also use it to support clustering and failover.
5-10 Oracle BPEL Process Manager Developer’s Guide
Calling an Asynchronous Service
You insert this point between the invoke activity and receive activity. Figure 5–1 on
page 5-2 shows an example of a dehydration point in the loan application approver
Web service.
Calling an Asynchronous Service
To add asynchronous functionality to a BPEL process, complete the tasks in this
section:
■
Step 1: Adding a Partner Link for an Asynchronous Service
■
Step 2: Adding an Invoke Activity
■
Step 3: Adding a Receive Activity
■
Step 4: Performing Additional Activities
Step 1: Adding a Partner Link for an Asynchronous Service
These instructions describe how to create a partner link named LoanService for the
loan application approver Web service.
1.
Double-click LoanBroker.bpel in the Application Navigator.
2.
In the diagram window, right-click either side of the BPEL process (under
Services).
3.
Select Create Partner Link.
The Create Partner Link window appears.
4.
Enter the following details to create a second partner type and select the loan
application approver Web service:
■
Name: Enter a name for the partner link.
■
Process: The BPEL process name
■
■
■
■
WSDL File: Enter the name of the WSDL file to use. Click the Service
Explorer icon above this field to locate the correct WSDL.
Partner Link Type: Refers to the external service with which the BPEL process
is to interface. Select from the list.
Partner Role: Refers to the role of the external source, for example, provider.
Select from the list.
My Role: Refers to role of the BPEL process in this interaction, for example,
requester. Select from the list.
Invoking an Asynchronous Web Service
5-11
Calling an Asynchronous 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.
See Also:
■
■
"partnerLinkTypes for Asynchronous Services" on page 5-3 for
conceptual details about partner links
"PartnerLink" on page B-36
Step 2: Adding an Invoke Activity
Follow these instructions to create an invoke activity and a global input variable
named request. This activity initiates asynchronous BPEL process activity with the
loan application approver Web service (United Loan). The loan application approver
Web service uses the request input variable to receive the loan request from the client.
1.
Drag an invoke activity from the Component Palette to beneath the receive
activity.
2.
In the .bpel file’s diagram window, right-click either side of the BPEL process
and select View > Variables from the menu.
The Variables window appears.
3.
In the Variables window, select the second Variables folder in the navigation tree,
and click Create.
The Create Variable dialog box appears.
4.
Enter the variable name and select Message Type from the options provided:
■
■
Simple Type: This option lets you select an XML schema simple type, for
example, string, Boolean, and so on.
Message Type: This option enables you to select a WSDL message file
definition of a partner link or of the project WSDL file of the current BPEL
process (for example, a response message or a request message). You can
specify variables associated with message types as input or output variables
for invoke, receive, or reply activities.
To display the message type, select the Message Type option, and then select
its flashlight icon to display the Type Chooser window. From here, expand the
5-12 Oracle BPEL Process Manager Developer’s Guide
Calling an Asynchronous Service
Message Types navigation window to select Message Types > Partner Links >
Loan Service > United Loan > Message Types > LoanServiceRequest
Message.
■
Element: This option lets you select an XML schema element of the project
schema file or project WSDL file of the current BPEL process, or of a partner
link.
5.
Click OK, then click Close.
6.
Double-click the invoke activity to display the Invoke window.
7.
In the Invoke window, select the LoanService partner link from the Partner Link
list and initiate from the Operation list.
8.
Select the input variable you created in Step 4, 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 and the global input variable are created.
See Also:
■
■
9.
"How the Invoke and Receive Activities Work" on page 5-5 for
conceptual details about the invoke activity
"Invoke Activity" on page B-14
Click OK.
Step 3: Adding a Receive Activity
Follow these steps to create a receive activity and a global output variable named
response. This activity waits for the loan application approver Web service’s callback
operation. The loan application approver Web service uses this output variable to send
the loan offer result to the client.
1.
From the Component Palette, drag a receive activity to the location right after the
invoke activity you created in "Step 2: Adding an Invoke Activity" on page 5-12.
2.
Create a variable to hold the receive information by invoking the Create Variable
window, as you did in Step 2 through Step 5, starting on page 5-12.
Invoking an Asynchronous Web Service
5-13
Using Correlation Sets in an Asynchronous Service
3.
Double-click the receive activity and change its name to receive_invoke.
4.
Select LoanService from the Partner Link list and onResult from the Operation
list. Do not select the Create Instance check box.
5.
Select the variable you created in Step 2 through Step 5, starting on page 5-12.
6.
Click OK.
The receive activity and the output variable are created. Because the initial receive
activity in the LoanBroker.bpel file created the initial BPEL process instance, a
second instance does not need to be created.
See Also:
"Receive Activity" on page B-20
Step 4: Performing Additional Activities
In addition to the asynchronous-specific tasks, you must perform the following tasks.
■
■
Create an initial assign activity for data manipulation in front of the invoke
activity that copies the client’s input variable loan application request document
payload into the loan application approver Web service’s request variable
payload.
Create a second assign activity for data manipulation after the receive activity that
copies the loan application approver Web service’s response variable loan
application results payload into the output variable for the client to receive.
See Also: The following documentation for information on creating
and defining an assign activity:
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
Using Correlation Sets in an Asynchronous Service
This tutorial 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.
This section contains the following topics:
5-14 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
■
Step 1: Creating a Project
■
Step 2: Configuring Partner Links and File Adapter Services
■
Step 3: Creating Three Receive Activities
■
Step 4: Creating Correlation Sets
■
Step 5: Associating Correlation Sets with Receive Activities
■
Step 6: Creating Property Aliases
■
Step 7: Reviewing WSDL File Content
Step 1: Creating a Project
1.
Right-click your application in the Application Navigator section of the designer
window.
2.
Select New Project.
3.
Double-click BPEL Process Project in the Items window to display the BPEL
Project Creation Wizard window.
4.
Enter an appropriate name in the Name field (for this example, MyCorrelationSet
is used).
5.
Select Asynchronous BPEL Process from the Template list.
6.
Click Finish.
Step 2: Configuring Partner Links and File Adapter Services
You now create three partner links that use the adapter services.
This section contains these topics:
■
Creating an Initial Partner Link and File Adapter Service
You create an initial partner link with an adapter service for reading a loan
application.
■
Creating a Second Partner Link and File Adapter Service
You create a second partner link with an adapter service for reading an application
response.
■
Creating a Third Partner Link and File Adapter Service
You create a third partner link with an adapter service for reading a customer
response.
Creating an Initial Partner Link and File Adapter Service
1.
Select Services from the Component Palette.
2.
Drag and drop an initial PartnerLink activity onto the right side of the designer
window anywhere beneath the header Services.
3.
Enter FirstReceivePL in the Name field.
4.
Click the third icon at the top (the Define Adapter Service icon). This starts the
Adapter Configuration Wizard.
Invoking an Asynchronous Web Service
5-15
Using Correlation Sets in an Asynchronous Service
5.
Click Next on the Welcome window.
6.
Select File Adapter on the Adapter Type window and click Next.
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 next 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.
13. Click Next.
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.
17. Click Next.
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.
22. Click Finish.
You are returned to the Partner Link window. All other fields are automatically
completed. The window looks as follows:
Field
Value
Name
FirstReceive
WSDL File
file:/c:OraJDev/jdev/mywork/myapplication/MyCorrelationSet/bpel/F
irstReceive.wsdl
where c:/OraJDev represents the Oracle JDeveloper home directory for
this example.
Partner Link Type
Read_plt
Partner Role
Leave unspecified.
My Role
Read_role
5-16 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
23. Click OK.
Creating a Second Partner Link and File Adapter Service
1.
Drag and drop a second PartnerLink activity below the FirstReceivePL partner
link activity.
2.
Enter SecondReceivePL in the Name field.
3.
Click the third icon at the top (the Define Adapter Service icon).
4.
Click Next on the Welcome window.
5.
Select File Adapter in the Adapter Type window and click Next.
6.
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 5-16.
7.
Select Read File as the Operation Type in the Operation window
8.
Change the name in the Operation Name field to Read1.
9.
Click Next.
10. Select Directory Names are Specified as Physical Path.
11. Click Browse next to the Directory for Incoming Files (physical path) field.
12. Select a directory from which to read files (for this example,
C:\files\receiveprocess\SecondInputDir is entered).
13. Click Select.
14. Click Next.
15. Enter appropriate file filtering parameters in the File Filtering window.
16. Click Next.
17. Enter appropriate file polling parameters in the File Polling window.
18. Click Next.
19. Click Browse next to the Schema Location field in the Messages window to
display the Type Chooser window.
20. Select an appropriate XSD schema file. For this example, Book1_5.xsd is the
schema and LoanAppResponse is the schema element selected.
21. Click OK.
The Schema Location field (Book1_5.xsd for this example) and the Schema
Element field (LoanAppResponse for this example) are filled in.
22. Click Next.
23. Click Finish.
You are returned to the Partner Link window. All other fields are automatically
completed. The window looks as follows:
Field
Value
Name
SecondReceive
Invoking an Asynchronous Web Service
5-17
Using Correlation Sets in an Asynchronous Service
Field
Value
WSDL File
file:/c:OraJDev/jdev/mywork/myapplication/MyCorrelationSet/bpel/
SecondFileRead.wsdl
where c:/OraJDev represents the Oracle JDeveloper home directory for
this example.
Partner Link Type
Read1_plt
Partner Role
Leave unspecified.
My Role
Read1_role
24. Click OK.
Creating a Third Partner Link and File Adapter Service
1.
Drag and drop a third PartnerLink activity below the SecondReceivePL partner
link activity.
2.
Enter ThirdReceivePL in the Name field.
3.
Click the third icon at the top (the Define Adapter Service icon).
4.
Click Next on the Welcome window.
5.
Select File Adapter in the Adapter Type window and click Next.
6.
Enter ThirdFileRead in the Service Name field of the Service Name window and
click Next. This name must be unique from the one you entered in Step 7 on
page 5-16 and Step 6 on page 5-17.
7.
Select Read File as the Operation Type in the Operation window
8.
Change the name in the Operation Name field to Read2. This name must be
unique.
9.
Click Next.
10. Select Directory Names are Specified as Physical Path.
11. Click Browse next to the Directory for Incoming Files (physical path) field.
12. Select a directory from which to read files (for this example,
C:\files\receiveprocess\ThirdInputDir is entered).
13. Click Select.
14. Click Next.
15. Enter appropriate file filtering parameters in the File Filtering window.
16. Click Next.
17. Enter appropriate file polling parameters in the File Polling window.
18. Click Next.
19. Click Browse next to the Schema Location field in the Messages window to
display the Type Chooser window.
20. Select an appropriate XSD schema file. For this example, Book1_6.xsd is the
schema and CustResponse is the schema element selected.
21. Click OK.
The Schema Location field (Book1_6.xsd for this example) and the Schema
Element field (CustResponse for this example) are filled in.
5-18 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
22. Click Next.
23. Click Finish.
You are returned to the Partner Link window. All other fields are automatically
completed. The window looks as follows:
Field
Value
Name
ThirdReceive
WSDL File
file:/c:OraJDev/jdev/mywork/myapplication/MyCorrelationSet/bpel/
ThirdFileRead.wsdl
where c:/OraJDev represents the Oracle JDeveloper home directory for
this example.
Partner Link Type
Read2_plt
Partner Role
Leave unspecified.
My Role
Read2_role
24. Click OK.
When complete, the designer window looks as follows:
Step 3: Creating Three Receive Activities
You now create three receive activities; one for each partner link. The receive activities
specify the partner link from which to receive information.
This section contains the following topics:
■
Creating an Initial Receive Activity
■
Creating a Second Receive Activity
■
Creating a Third Receive Activity
Creating an Initial Receive Activity
1.
Drag and drop a Receive activity from the Process Activities list of the
Component Palette section into the designer window.
2.
Double-click the receive icon to display the Receive window.
3.
Enter the following details to associate the first partner link (FirstReceivePL) with
the first receive activity:
Invoking an Asynchronous Web Service
5-19
Using Correlation Sets in an Asynchronous Service
Field
Value
Name
receiveFirst
Partner Link
FirstReceivePL
Create Instance
Select this check box.
The Operation (Read) field is automatically filled in.
4.
Click the first icon to the right of the Variable field. This is the automatic variable
creation icon.
5.
Click OK on the Create Variable window that appears.
A variable named receiveFirst_Read_InputVariable is automatically created in
the Variable field.
6.
Ensure that you selected the Create Instance check box, as mentioned in Step 3.
7.
Click OK.
Creating a Second 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
SecondReceivePL
Create Instance
Do not select this check box.
The Operation (Read1) field is automatically filled in.
4.
Click the first icon to the right of the Variable field.
5.
Click OK on the Create Variable window that appears.
A variable named receiveSecond_Read1_InputVariable is automatically created
in the Variable field.
6.
Click OK.
Creating a Third Receive Activity
1.
Drag and drop a third Receive activity from the Component Palette section to
below the receiveSecond receive activity.
2.
Double-click the receive icon to display the Receive window.
3.
Enter the following details to associate the third partner link (ThirdReceivePL)
with the third receive activity:
Field
Value
Name
receiveThird
5-20 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
Field
Value
Partner Link
ThirdReceivePL
Create Instance
Do not select this check box.
The Operation (Read2) field is automatically filled in.
4.
Click the first icon to the right of the Variable field.
5.
Click OK on the Create Variable window that appears.
A variable named receiveThird_Read2_InputVariable is automatically created in
the Variable field.
6.
Click OK.
Each receive activity is now associated with a specific partner link.
Step 4: Creating Correlation Sets
You now create correlation sets. A set of correlation tokens is a set of properties shared
by all messages in the correlated group.
This section contains the following topics:
■
Creating an Initial Correlation Set
■
Creating a Second Correlation Set
Creating an Initial Correlation Set
1.
Right-click Correlation Sets and select Expand All Child Nodes in the Structure
window of Oracle JDeveloper.
2.
Right-click Correlation Sets and select Create Correlation Set.
3.
Enter CorrelationSet1 in the Name field of the Create Correlation Set window.
4.
Click Add in the Properties section to display the Property Chooser window.
5.
Select Properties, then click Create (first icon at the top) to display the Create
Correlation Set Property window.
6.
Enter NameCorr in the Name field and click the flashlight icon to the right of the
Type field.
7.
Select string in the Type Chooser window and click OK.
8.
Click OK to close the Create Correlation Set Property window, the Property
Chooser window, and the Create Correlation Set window.
Creating a Second Correlation Set
1.
Return to the Correlation Sets section in the Structure window of Oracle
JDeveloper.
2.
Right-click Correlation Sets and select Create Correlation Set.
3.
Enter CorrelationSet2 in the Name field of the Create Correlation Set window.
4.
Click Add in the Properties section to display the Property Chooser window.
5.
Select Properties, then click Create to display the Create Correlation Set Property
window.
Invoking an Asynchronous Web Service
5-21
Using Correlation Sets in an Asynchronous Service
6.
Enter IDCorr in the Name field and click the flashlight icon to the right of the
Type field.
7.
Select double in the Type Chooser window and click OK.
8.
Click OK to close the Create Correlation Set Property window, the Property
Chooser window, and the Create Correlation Set window.
Step 5: Associating Correlation Sets with Receive Activities
You now associate the correlation sets with the receive activities. You perform the
following correlation set tasks:
■
■
For the first correlated group, the first and second receive activities are correlated
with the CorrelationSet1 correlation set.
For the second correlated group, the second and third receive activities are
correlated with the CorrelationSet2 correlation set.
This section contains the following topics:
■
Associating the First Correlation Set with a Receive Activity
■
Associating the Second Correlation Set with a Receive Activity
■
Associating the Third Correlation Set with a Receive Activity
Associating the First Correlation Set with a Receive Activity
1.
Double-click the receiveFirst receive activity to display the Receive window.
2.
Click the Correlations tab.
3.
Click Add, select CorrelationSet1, then click OK.
4.
Set the Initiate column to yes. When set to yes, the set is initiated with the values
of the properties occurring in the message being exchanged.
5.
Click OK.
Associating the Second Correlation Set with a Receive Activity
1.
Double-click the receiveSecond receive activity to display the Receive window.
2.
Click the Correlations tab.
3.
Click Add, select CorrelationSet2, then click OK.
4.
Set the Initiate column to yes.
5.
Click Add and select CorrelationSet1.
6.
Click OK.
5-22 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
7.
Set the Initiate column to no for CorrelationSet1.
8.
Click OK.
This groups the first and second receive activities into a correlated group.
Associating the Third Correlation Set with a Receive Activity
1.
Double-click the receiveThird receive activity to display the Receive window.
2.
Click the Correlations tab.
3.
Click Add and select CorrelationSet2.
4.
Click OK.
5.
Set the Initiate column to no for CorrelationSet2.
6.
Click OK.
This groups the second and third receive activities into a second correlated group.
Invoking an Asynchronous Web Service
5-23
Using Correlation Sets in an Asynchronous Service
Step 6: Creating Property Aliases
Property aliases enable you to map a global property to a field in a specific message
part. This enables the property name to become an alias for the message part and
location. The alias can be used in XPath expressions.
This section contains the following topics:
■
Creating Property Aliases for NameCorr
■
Creating Property Aliases for IDCorr
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 > Partner Links > 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.
9.
Press Ctrl and then the space bar in the Query field to define the following XPath
expression:
/ns4:LoanAppResponse/ns4:APR
Creating Property Aliases for IDCorr
You create the following two property aliases for the IDCorr correlation set.
■
■
Map IDCorr to the 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).
Map IDCorr to the CustResponse message type part of the receiveThird receive
activity. This receive activity is associated with the ThirdReceivePL partner link
(defined by the ThirdFileRead.wsdl file).
1.
Right-click Property Aliases in the Structure section.
2.
Select Create Property Alias.
3.
Select IDCorr in the Property list.
5-24 Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
4.
Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl
> Message Types > LoanAppResponse_msg > Part - LoanAppResponse.
5.
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
Design is now complete.
Step 7: Reviewing WSDL File Content
The NameCorr and IDCorr correlation set properties are defined in the
MyCorrelationSet_Properties.wsdl file in the Application Navigator of Oracle
JDeveloper:
<definitions
name="properties"
targetNamespace="http://xmlns.oracle.com/MyCorrelationSet/correlationset"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<bpws:property name="NameCorr" type="xsd:string"/>
<bpws:property name="IDCorr" type="xsd:double"/>
</definitions>
The property aliases are defined in the MyCorrelationSet.wsdl file:
<bpws:propertyAlias propertyName="ns1:NameCorr"
messageType="ns3:LoanAppl_msg"
part="LoanAppl" query="/ns2:LoanAppl/ns2:Name"/>
<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 is not created as a Web services provider in this example,
the MyCorrelationSet.wsdl file is not referenced in the BPEL process. Therefore,
you must import the MyCorrelationSet.wsdl file inside the
FirstReceive.wsdl file to reference the correlation sets:
Invoking an Asynchronous Web Service
5-25
Summary
<import namespace="http://xmlns.oracle.com/MyCorrelationSet"
location="MyCorrelationSet.wsdl"/>
Summary
This chapter describes the concepts for a BPEL process that invokes an asynchronous
Web service. This service takes a loan application request document as input from a
client and asynchronously returns an approved loan offer. An example of how to
create correlation sets in Oracle JDeveloper is also provided.
5-26 Oracle BPEL Process Manager Developer’s Guide
6
Parallel Flow
Parallel flows enable a BPEL process 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 contains the following topics:
■
Use Case for Parallel Flows
■
Overview of Parallel Flow Concepts
■
Defining a Parallel Flow
■
Customizing the Number of Flow Activities by Using the flowN Activity
■
Summary
Use Case for Parallel Flows
In Chapter 5, "Invoking an Asynchronous Web Service" you learned how to call an
asynchronous Web service for the United Loan service. Because the United Loan
service can take up to several days to return a loan offer but you need to collect
another loan offer from Star Loan, you can define your BPEL process so both tasks run
in parallel.
This use case shows how to program the BPEL flow to perform two asynchronous
callbacks to loan services in parallel.
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\tutorials\106.ParallelFlows
Overview of Parallel Flow Concepts
Sometimes a BPEL process must gather information from multiple asynchronous
sources. Because each callback can take an undefined amount of time (hours or days),
it may take too long to call each service one at a time. By breaking the calls into a
parallel flow, a BPEL process can invoke multiple Web services at once, and receive
the responses as they come in. This method is much more time efficient.
Figure 6–1 provides an overview of a BPEL process performing a parallel flow to
retrieve loan offers from two different Web services. Here, two asynchronous callbacks
execute in parallel, so that one callback does not have to wait for the other to complete
first. Each response is stored in a different global variable.
Parallel Flow 6-1
Defining a Parallel Flow
Figure 6–1 Parallel Flow Invocation
BPEL
Process
<flow>
WSDL
WSDL
<sequence>
<sequence>
Initiate
service
<invoke>
Initiate
service
<invoke>
United
Loan
Star
Loan
Wait for
callback
<receive>
Wait for
callback
<receive>
Defining a Parallel Flow
A flow activity typically contains a number of sequence activities, and each
sequence is performed in parallel. A flow activity can also contain other activities
(although not in this example). For example:
<flow name="flow-1">
<sequence>
<scope name="UnitedLoan">
<sequence>
<invoke name="invoke-2" partnerLink="unitedLoan"
portType="services:LoanService" operation="initiate"
inputVariable="loanApplication"/>
<receive createInstance="no" name="receive-1"
partnerLink="unitedLoan"
portType="services:LoanServiceCallback"
operation="onResult" variable="loanOffer1"/>
</sequence>
</scope>
</sequence>
<sequence>
<scope name="StarLoan">
<sequence>
<invoke name="invoke-1" partnerLink="StarLoan"
portType="services:LoanService" operation="initiate"
inputVariable="loanApplication"/>
<pick name="pick-1">.
.
.
</pick>
</sequence>
</scope>
</sequence>
</flow>
This example shows two sequences, but the flow activity can have many sequences.
6-2 Oracle BPEL Process Manager Developer’s Guide
Defining a Parallel Flow
The following instructions explain how to create a flow activity and a global input
variable named request. This activity initiates an asynchronous BPEL process
activity with a loan offer Web service (United Loan). The loan offer service uses the
request input variable to receive the loan request from the client.
This example shows how to create a flow activity in Oracle JDeveloper.
1.
Drag and drop a flow activity into a scope activity.
2.
Click the + sign to expand the flow activity.
A scope activity is a container for a group of activities that you want to process as
one unit. "Using the Scope Activity to Manage a Group of Activities" on page 8-3
describes scope activities in detail.
3.
The flow activity includes two branches, each with a box for functional elements.
Populate these boxes as you do a scope activity, either by building a function or
dragging activities from the Process Activities list into the boxes.
At this point, you can drag and drop activities onto each side of the flow in order
to invoke multiple services at once.
Parallel Flow 6-3
Customizing the Number of Flow Activities by Using the flowN Activity
See Also: The following documentation for examples of creating
flow activities in Oracle JDeveloper:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Flow Activity" on page B-11
■
"Sequence Activity" on page B-24
Customizing the Number of Flow Activities by Using 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 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 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.
Figure 6–2 shows an Oracle BPEL Control view of a flowN activity that looks up three
hotels. This is different from the view because instead of showing the BPEL process, 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.
6-4 Oracle BPEL Process Manager Developer’s Guide
Customizing the Number of Flow Activities by Using the flowN Activity
Figure 6–2 An Oracle BPEL Control View of the Execution of a flowN activity
Figure 6–3 shows how a flowN activity appears in Oracle JDeveloper.
Figure 6–3 FlowN Activity Setup in the Diagram Window
Figure 6–4 shows the flowN Window, which appears when you double-click the
flowN activity.
Parallel Flow 6-5
Customizing the Number of Flow Activities by Using the flowN Activity
Figure 6–4 flowN Window
The flowN windows enables you to name the flowN activity, enter an expression for
calculating the value of N, and define the index variable.
See Also:
"FlowN Activity" on page B-12
BPEL Code Example of the FlowN Activity
The following code is a reference implementation from a .bpel file that uses the
flowN activity to look up information on an arbitrary number of hotels. The following
actions take place:
1.
First, you name the sequence:
<sequence name="main">
<!-- Received input from requestor.
Note: This maps to operation defined in NflowHotels.wsdl
The requestor send a set of hotels names wrapped into the "inputVariable"
-->
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:
<receive name="receiveInput" partnerLink="client"
portType="client:NflowHotels" operation="initiate" variable="inputVariable"
createInstance="yes"/>
<!-The 'count()' Xpath function is used to get the number of hotelName
noded passed in.
For lisibility, an intermediate varaible called "NbParallelFlow" is
used to store the number of N flows being executed
-->
<assign name="getHotelsN">
<copy>
<from
expression="count(bpws:getVariableData('inputVariable','payload','/client:Nflow
HotelsProcessRequest/client:ListOfHotels/client:HotelName'));"/>
<to variable="NbParallelFlow"/>
</copy>
</assign>
<!-- Initiating the FlowN activity
The N value is initialized with the value stored in the
"NbParallelFlow" variable
The variable call "Index" is defined as the index variable
NOTE: Both "NbParallelFlow" and "Index" variables have to be declared
6-6 Oracle BPEL Process Manager Developer’s Guide
Summary
-->
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.
<bpelx:flowN name="FlowN" N="bpws:getVariableData('NbParallelFlow')"
indexVariable="Index">
<sequence name="Sequence_1">
<!-- Fetching each hotelName by indexing the "inputVariable" with the
"Index" variable.
Note the usage of the "concat()" Xpath function to create the
expression accessing the array element.
-->
4.
Next, the following copy rule uses the index variable to concatenate the hotel
entries into a list:
<assign name="setHotelId">
<copy>
<from expression=
"bpws:getVariableData('inputVariable','payload',concat('/client:Nflo
wHotelsProcessRequest/client:ListOfHotels/client:HotelName[',
bpws:getVariableData('Index'),']'))"/>
<to variable="InvokeHotelDetailInputVariable" part="payload"
query="/ns2:hotelInfoRequest/ns2:id"/>
</copy>
</assign>
5.
Using the hotel information, an invoke activity looks up detailed information for
each hotel through a Web service:
<!-- For each hotel, invoke the Web service giving detailed information
on the hotel
-->
<invoke name="InvokeHotelDetail" partnerLink="getHotelDetail"
portType="ns2:getHotelDetail" operation="process"
inputVariable="InvokeHotelDetailInputVariable"
outputVariable="InvokeHotelDetailOutputVariable"/>
<!-- This procees doesn't do anything with the retrieved inforamtion.
In the real life, it could be then used to continue the process.
Note: Meanwhile an indexing variable is used, unlike a while loop, the
activities a executed in parallel, not sequentially.
-->
</sequence>
</bpelx:flowN>
6.
Finally, the BPEL process sends detailed information on each hotel to the client
partner link:
<invoke name="callbackClient" partnerLink="client"
portType="client:NflowHotelsCallback" operation="onResult"
inputVariable="outputVariable"/>
</sequence>
</sequence>
Summary
This chapter shows how to create a parallel flow using the flow activity to perform
multiple tasks simultaneously. This BPEL process performs two asynchronous
Parallel Flow 6-7
Summary
callbacks in parallel, which can take considerably less time than performing the two
callbacks in series. Another activity, called a flowN activity, allows Oracle BPEL
Process Manager to use data to spawn the necessary number of parallel flows at run
time, and to perform the same activities on multiple data elements. Therefore, as the
information available to the BPEL process changes, so does the behavior of the
process.
6-8 Oracle BPEL Process Manager Developer’s Guide
7
Conditional Branching
This chapter describes conditional branching. Conditional branching introduces
decision points to control the flow of execution of a BPEL process.
This chapter contains the following topics:
■
Use Case for Conditional Branching
■
Overview of Conditional Branching Concepts
■
Using a Switch Activity to Define Conditional Branching
■
Using a While Activity to Define Conditional Branching
■
Summary
Use Case for Conditional Branching
The BPEL process you created in Chapter 6, "Parallel Flow" collected two loan offers,
one from United Loan and another from Star Loan. This chapter describes how to
design the BPEL process to select the loan with the lowest annual percentage rate
(APR) automatically.
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\demos\LoanDemo\LoanFlow
Overview of Conditional Branching Concepts
BPEL applies logic to make choices through conditional branching. You can use either
of the following activities to design your code to select different actions based on
conditional branching:
■
■
Switch activity: In this method, you set up two or more branches, with each
branch in the form of an XPath expression. If the expression is true, then the
branch is executed. If the expression is false, then the BPEL process moves to the
next branch condition, until it either finds a valid branch condition, encounters an
otherwise branch, or runs out of branches. If more than one branch condition is
true, then BPEL executes the first true branch. "Using a Switch Activity to Define
Conditional Branching" on page 7-2 explains how to create switch activities.
While activity: You can use a while activity to create a while loop to select
between two actions. "Using a While Activity to Define Conditional Branching" on
page 7-4 describes while activities.
Conditional Branching 7-1
Using a Switch Activity to Define Conditional Branching
A number of branches are set up, and each branch has a condition in the form of an
XPath expression.
You can program a conditional branch to have a timeout. That is, if a response cannot
be generated in a specified period of time, the BPEL flow can stop waiting and resume
its activities. Chapter 10, "Events and Timeouts" explains this feature in detail.
Using a Switch Activity to Define Conditional Branching
In Chapter 6, the flow activity of the BPEL process gathered two loan offers at the
same time, but did not compare either of the offers. Each offer was stored in its own
global variable. To compare the two offers and make decisions based on that
comparison, the BPEL flow requires a switch activity.
Figure 7–1 provides an overview of a BPEL conditional branching process that has
been defined in a switch activity.
Figure 7–1 Conditional Branching
condition 1 Boolean XPATH Expression
BPEL
Process
<switch>
<case
conditon 1>
Select
unitedLoan
<assign>
?
<otherwise>
Select
starLoan
<assign>
A switch activity, like a flow activity, has multiple branches. In this example, there are
only two branches. The first branch, which selects a loan offer from United Loan, is
executed if a case condition containing an XPath Boolean expression is met. Otherwise,
the second branch, which selects the Star Loan loan offer, is executed. By default, the
switch activity provides two switch cases, but you can add more if you want.
<switch name="switch-1">
<case condition="bpws:getVariableData('loanOffer1','payload',
'/autoloan:loanOffer/autoloan:APR') <;
bpws:getVariableData('loanOffer2','payload','/autoloan:loanOffer/autoloan:APR
')">
<assign name="selectUnitedLoan">
<copy>
<from variable="loanOffer1" part="payload">
</from>
<to variable="selectedLoanOffer" part="payload"/>
</copy>
</assign>
</case>
<otherwise>
7-2 Oracle BPEL Process Manager Developer’s Guide
Using a Switch Activity to Define Conditional Branching
<assign name="selectStarLoan">
<copy>
<from variable="loanOffer2" part="payload">
</from>
<to variable="selectedLoanOffer" part="payload"/>
</copy>
</assign>
</otherwise>
</switch>
Adding a Switch Activity
To add a switch activity to your BPEL flow in Oracle JDeveloper:
1.
Drag a switch activity from the Process Activities list of the Component Palette
into your BPEL flow.
2.
Click the + sign to expand the switch activity.
The switch activity has two switch case branches by default, each with a box for
functional elements. If you want to add more branches, select the entire switch
activity, right-click, and select Add Switch Case from the menu.
3.
Right-click the first branch and select Edit from the menu.
The Switch Case window appears.
4.
Enter an XPath Boolean expression in the Expression field by pressing the Ctrl key
and then the space bar to start the XPath Building Assistant. For example:
bpws:getVariableDate(’loanOffer1’,’payload’,’/loanOffer/APR’) >
bpws:getVariableData(’loanOffer2’,’payload’,’/loanOffer/APR’)
5.
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.
Conditional Branching 7-3
Using a While Activity to Define Conditional Branching
■
If loanOffer1 does not have the lower APR than loanOffer2, then the
otherwise case assigns loanOffer1’s payload to selectedLoanOffer’s
payload.
See Also: The following documentation for examples of creating
switch activities in Oracle JDeveloper:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Switch Activity" on page B-27
■
SOA_Oracle_Home\bpel\samples\references\Switch
Using a While Activity to Define Conditional Branching
Another way to design your BPEL code to select between multiple actions is to use a
while activity to create a while loop. The while loop repeats an activity until a
specified success criteria is met. For example, if a critical Web service is returning a
service busy message in response to requests, you can use the while activity to keep
polling the service until it becomes available. The condition for the while activity is
that the latest message received from the service is busy, and the operation within the
while activity is to check the service again. Once the Web service returns a message
other than service busy, the while activity terminates and the BPEL process continues,
ideally with a valid response from the Web service.
To create a while activity in Oracle JDeveloper:
1.
Drag and drop a while activity from the Process Activities list of the Component
Palette into your BPEL flow.
The while activity has icons to allow you to build condition expressions and to
validate the while definition. It also provides an area for you to drop an activity to
define the while loop.
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.
7-4 Oracle BPEL Process Manager Developer’s Guide
Summary
See Also: The following documentation for examples of defining a
while activity in Oracle JDeveloper:
■
"While Activity" on page B-32
■
Oracle BPEL Process Manager Order Booking Tutorial
■
SOA_Oracle_Home\bpel\samples\references\While
Summary
This chapter discusses the concepts and procedures for creating a switch activity
conditional flow that selects different behavior based on comparing two pieces of
information. The BPEL process in this example considers two loan offers, and selects
the offer with the lower APR. This chapter also discusses the while looping conditional
activity.
Conditional Branching 7-5
Summary
7-6 Oracle BPEL Process Manager Developer’s Guide
8
Fault Handling
Fault handling allows a BPEL process 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:
■
Use Case for Fault Handling
■
Overview of Fault Handling Concepts
■
Defining a Fault Handler
■
Types of BPEL Faults
■
Using the Scope Activity to Manage a Group of Activities
■
Throwing Internal Faults
■
Returning External Faults
■
Using a Fault Handler within a Scope
■
Using Compensation After Undoing a Series of Operations
■
Using the Terminate Activity to Stop a Business Process Instance
■
Catching Run-Time Faults Example
■
Fault Handling Example
■
Summary
Use Case for Fault Handling
This chapter uses an example of a credit rating service returning a negative credit
message instead of a credit rating number. You also learn how to add a fault handler to
a BPEL process to handle the message.
See Also:
The following samples:
■
SOA_Oracle_
Home\bpel\samples\tutorials\107.Exceptions
■
SOA_Oracle_Home\bpel\samples\demos\ResilientDemo
Overview of Fault Handling Concepts
Web services occasionally return errors or faults instead of the data normally expected.
There are two kinds of faults in BPEL: business faults and run-time faults. Business
Fault Handling 8-1
faults are the result of a problem with the information, for example when a social
security number is not found in the database. Run-time faults are the result of
problems within the BPEL process or the Web service themselves, as when data cannot
be copied properly because the variable name is incorrect.
Defining a Fault Handler
Fault handlers define how the BPEL process responds when the Web services return
data other than what is normally expected (for example, returning an error message
instead of a number). An example of a fault handler is where the Web service normally
returns a credit rating number, but instead returns a negative credit message.
Figure 8–1 shows how a fault handler sets the credit rating variable at -1000.
Figure 8–1 Fault Handling
WSDL
BPEL
Process
<receive>
d1
WSDL
Negative
Credit
<scope>
prepare
crin
<assign>
call
service
<invoke>
d3
f1
Credit
Rating
Service
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>
8-2 Oracle BPEL Process Manager Developer’s Guide
Using the Scope Activity to Manage a Group of Activities
</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, determine the possible faults that
may be returned and set up a fault handler for each one.
Types of BPEL Faults
A BPEL fault has a fault name called a Qname and a possible messageType. There are
two categories of faults in BPEL:
■
■
Business faults: These are application-specific faults that are generated when
there is a problem with the information being processed. A business fault occurs
when an application executes a throw activity or when an invoke activity receives
a fault as a response. The fault name of a business fault is specified by the BPEL
process. The messageType, if applicable, is defined in the WSDL.
Run-time faults: These occur while the BPEL process is running. They are
generated if the process tries to use a value incorrectly, or if there is a logic error,
such as an endless loop.
See Also: BPEL Technical Note #007, Managing BPEL Run-time
Exceptions, at:
http://www.oracle.com/technology/products/ias/bpel/h
tdocs/orabpel_technotes.tn007.html for more detailed
information on BPEL fault codes
Using the Scope Activity to Manage a Group of Activities
The scope activity provides a container and a context for other activities. A scope
provides handlers for faults, events, and compensation, as well as data variables and
correlation sets. Using a scope activity simplifies a BPEL flow by grouping functional
structures together. This allows you to collapse them into what appears to be a single
element in Oracle JDeveloper.
The following code example shows a scope activity. In this case, the process for getting
a credit rating based on a customer’s social security number has been placed inside a
scope named getCreditRating. This identifies functional blocks of code and sets
them apart visually. In Oracle JDeveloper, you can collapse the activities contained
inside the scope into a single visual element, or expand them when necessary.
<scope name="getCreditRating">
<variables>
<variable name="crError"
messageType="services:CreditRatingServiceFaultMessage"/>
</variables>
<assign name="assign-2">
<copy>
<to variable="input" part="payload"
query="/autoloan:loanApplication/autoloan:creditRating"/>
</copy>
</assign>
</sequence>
</scope>
Fault Handling 8-3
To add a scope activity:
1.
Click and drag a scope activity into the BPEL process diagram.
2.
Open the scope by double-clicking it or by single-clicking the + sign.
3.
Drag activities from the Component Palette to build the function within the scope.
See Also: The following documentation for examples of creating
scope activities in Oracle JDeveloper:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Scope Activity" on page B-22
Throwing Internal Faults
A BPEL application can generate and receive fault messages. The throw activity has
three elements: its name, the name of the faultName, and the faultVariable. If
you add a throw activity to your BPEL process, it automatically includes a copy rule
that copies the fault name and type into the output payload. The fault thrown by a
throw activity is internal to BPEL. You cannot use a throw activity on an
asynchronous process to communicate with a client. Here is a code sample of a throw
activity, which includes the fault elements, name, and partner link of the service to
which the BPEL process sends the fault, and the copy rule that packages the message:
<throw name="delay" faultName="fault-1" faultVariable="fVar"/>
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"/>
<assign>
<copy>
<from variable="response" part="result" query="/result"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
</assign>
See Also: The following documentation for examples of creating
throw activities:
■
"Throw Activity" on page B-28
■
SOA_Oracle_Home\bpel\samples\references\Throw
Returning External Faults
A BPEL process can send a fault to another application to indicate a problem, as
opposed to throwing an internal fault. In a synchronous operation, the reply activity
can return the fault. In an asynchronous operation, the invoke activity performs this
function.
Returning a Fault in a Synchronous Interaction
The syntax of a reply activity that returns a fault in a synchronous interaction is as
follows:
<reply partnerlinke="partner-link-name"
portType="port-type-name"
operation="operation-name"
variable="variable-name" (optional)
8-4 Oracle BPEL Process Manager Developer’s Guide
Using a Fault Handler within a Scope
faultName="fault-name">
</reply>
Always returning a fault in response to a synchronous request is not very useful. It is
better to make the activity part of a conditional branch, where the first branch is
executed if the data requested is available. If the requested data is not available, then
the BPEL process returns a fault with this information.
See Also:
■
■
■
Chapter 7, "Conditional Branching" for more information on
setting up the conditional structure
Chapter 4, "Invoking a Synchronous Web Service" for more
information on synchronous interactions
"Reply Activity" on page B-21
Returning a Fault in an Asynchronous Interaction
In an asynchronous interaction, the client does not wait for a reply. The reply activity is
not used to return a fault. Instead, the BPEL process returns a fault using a callback
operation on the same port type that normally receives the requested information,
with an invoke activity.
See Also:
■
■
Chapter 5, "Invoking an Asynchronous Web Service" for more
information on asynchronous interactions
"Invoke Activity" on page B-14
Using a Fault Handler within a Scope
If a fault is not handled, it creates a faulted state that migrates up through the
application and can throw the entire process into a faulted state. To prevent this,
contain the parts of the process that have the potential to receive faults within a scope.
As described earlier, the scope activity includes fault handling capabilities. The catch
activity works within a scope to catch faults and exceptions before they can throw the
entire process into a faulted state.
You can use specific fault names in the catch activity to respond in a specific way to an
individual fault. To catch any faults that are not already handled by name-specific
catch activities, use the catchAll activity.
See Also: The following documentation for examples of creating
fault handling:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
"Scope Activity" on page B-22
■
SOA_Oracle_Home\bpel\samples\references\Catch
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:
Fault Handling 8-5
<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 "Using the Terminate Activity to Stop a Business Process
Instance" on page 8-7) 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.
See Also:
■
"Scope Activity" on page B-22
■
"Empty Activity" on page B-8
Using Compensation After Undoing a Series of Operations
Compensation occurs when the BPEL process cannot complete a series of operations
after some of them have already completed, and the BPEL process must backtrack and
undo the previously completed transactions. For example, if a BPEL process is
designed to book a rental car, a hotel, and a flight, it may book the car and the hotel
and then be unable to book a 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.
8-6 Oracle BPEL Process Manager Developer’s Guide
Using the Terminate Activity to Stop a Business Process Instance
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 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.
See Also:
■
■
"BankTransferDemo" on page 1-7 for a demonstration that uses
a compensate activity
"Compensate Activity" on page B-4
Using the Terminate Activity to Stop a Business Process Instance
The terminate activity immediately terminates the behavior of a business process
instance within which the terminate activity is performed. All currently running
activities must be terminated as soon as possible without any fault handling or
compensation behavior. The terminate activity does not send any notifications of the
status of a BPEL process. 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>
Fault Handling 8-7
standard-elements
</terminate>
See Also: The following documentation for examples of creating
terminate activities:
■
"Terminate Activity" on page B-27
■
SOA_Oracle_Home\bpel\samples\references\Terminate
Catching Run-Time Faults Example
The following procedure shows how to use the provided examples to generate a fault
and define a fault handler to catch it. In this case, you modify a WSDL file to generate
a fault, and create a catch attribute to catch it.
1.
Import RuntimeFault.wsdl into your process WSDL (located under the SOA_
Oracle_Home\bpel\system\xmllib directory).
2.
Declare a variable with messageType bpelx:RuntimeFaultMessage.
3.
Catch it using
<catch faultName="bpelx:remoteFault"
faultName="varName">
| "bpelx:bindingFault"
See Also: The following sample, which describes how to handle
run-time binding faults:
■
SOA_Oracle_Home\bpel\samples\demos\ResilientDemo
Fault Handling Example
The ResilientDemo sample demonstrates failover fault handling and retry fault
handling. Failover allows multiple service implementations to be configured for a
partner link. If a retryable run-time fault occurs, then the server tries other service
implementations. In retry fault handling, the server retries based on a specified retry
interval and retry count. Another kind of fault, a binding fault, can occur if the Web
service has been upgraded and the interface has changed. In the ResilientDemo
sample, when a binding fault occurs, the document is placed in a dead letter queue
using a JMS service. The diagram of ResilientFlow.bpel is shown in Figure 8–2.
8-8 Oracle BPEL Process Manager Developer’s Guide
Fault Handling Example
Figure 8–2 Diagram Window of ResilientFlow.bpel
The invokeRatingService activity shows the failover feature. The partner link of this
invoke has two possible implementations, which are configured in the deployment
descriptor file as follows:
<properties id="RatingService">
<property name="wsdlLocation">
http://localhost:8080/axis/services/RatingService1?wsdl
</property>
<property name="location">
http://localhost:1234/axis/services/RatingService1
http://localhost:8080/axis/services/RatingService2
</property>
</properties>
The preceding code sample shows that two endpoint locations are configured for the
RatingService partner link. The first endpoint is a bad URL and the second endpoint is
a good URL. Because a remote exception like this is retryable, and there is a second
endpoint, Oracle BPEL Server tries to call the second endpoint, at which point, the call
succeeds.
The invokeFlakyService activity, expanded in Figure 8–3, shows system retry.
Fault Handling 8-9
Figure 8–3 Retry with FlakyService
The partner link of this invoke is configured as follows:
<properties id="FlakyService">
<property name="wsdlLocation">
http://localhost:8080/axis/services/FlakyService?wsdl</property>
<property name="location">
http://localhost:2222/axis/services/FlakyService</property>
<property name="retryCount">2</property>
<property name="retryInterval">60</property>
</properties>
If the service is not listening on port 2222, then the invoke fails with a
ConnectionRefused run-time fault. Because this is a retryable fault, and the
retryCount (set to 2) and retryInterval parameters (set to 60) are defined,
Oracle BPEL Server retries twice, with 60 second intervals between each attempt. The
second retry is successful.
Summary
BPEL supports fault handlers to cope with faults, errors, or exceptions returned by the
called Web services. This chapter demonstrates the application of a fault handler, a
fault handler’s structure, and how to create a fault handler in a BPEL process.
8-10 Oracle BPEL Process Manager Developer’s Guide
9
Incorporating Java and J2EE Code
in BPEL Processes
You can embed sections of Java code into a BPEL process.
This chapter contains the following topics:
■
Overview of Java and J2EE Code in BPEL Concepts
■
Using Java Embedding in a BPEL Process
■
Summary
Overview of Java and J2EE Code in BPEL Concepts
This chapter explains how you can embed sections of Java code into a BPEL process.
This is particularly useful when there is already Java code that can perform the desired
function, and you want to use the existing code rather than start over with BPEL.
You can incorporate Java code using any of the following methods:
■
Using Java Code with WSIF Binding
■
Using Java Code Wrapped as a SOAP Service
■
Directly Embedding Java Code in a BPEL Process
Using Java Code with WSIF Binding
If the Java application has a BPEL-compatible interface, you either use Web Services
Inspection Language (WSIF) binding or wrap the Java code as a SOAP service to use it
in a BPEL process.
WSIF Binding is the most common way of using Java code in a BPEL process. This
method enables a BPEL process to invoke an Enterprise Java Bean through native J2EE
protocol (local or remote method invocation (RMI)). With WSIF binding, a section of
the WSDL file defines the protocol for communicating between Java and XML. This
approach maintains Java’s transactionality and does not sacrifice performance. It is
also quicker for you to add WSIF binding to an existing Java application rather than
starting over in Oracle BPEL Process Manager. However, WSIF binding has the
following drawbacks:
■
Less tool support than SOAP services
■
Less interoperability, because each application server needs a specific binding
Currently, you must write the binding manually.
Incorporating Java and J2EE Code in BPEL Processes
9-1
Overview of Java and J2EE Code in BPEL Concepts
See Also:
■
SOA_Oracle_
Home\bpel\samples\tutorials\702.Bindings for
examples of WSIF bindings for EJB, HTTP, and Java. Bindings
must be written to match the application server.
■
SOA_Oracle_
Home\bpel\samples\demos\BankTransferDemo\BankTran
sferFlow
Using Java Code Wrapped as a SOAP Service
As an alternative to WSIF binding, you can wrap the Java code as a SOAP service. As
with WSIF binding, this method requires that the Java application have a
BPEL-compatible interface. A Java application wrapped as a SOAP service appears as
any other Web service, which can be used by many different kinds of applications.
There are also tools available for writing SOAP wrappers.
However, a Java application wrapped as a SOAP service has the following drawbacks:
■
■
It loses performance, because interactions are constantly being mapped back and
forth between the Java code and the SOAP wrapper.
It loses interoperability, that is, the ability to perform several operations in an
all-or-none mode (such as debiting one bank account while crediting another,
where either both transactions must be completed, or neither of them).
Directly Embedding Java Code in a BPEL Process
Another way to use Java in a BPEL process is to embed the code directly into the BPEL
process using the Java BPEL exec extension bpelx:exec. The benefits of this
approach are speed and transactionality. However, you can incorporate only fairly
small segments of code. If you want to incorporate larger segments of code, or if the
project requires the Java code to have the same look and feel throughout all the BPEL
processes being created, consider using WSIF binding or wrapping it as a SOAP
service.
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 following bpelx:exec tag
to embed the invokeSessionBean Java bean:
<bpelx:exec name="invokeSessionBean" language="java" version="1.4">
<![CDATA[
try {
Object homeObj = lookup("ejb/session/CreditRating");
Class cls = Class.forName(
"com.otn.samples.sessionbean.CreditRatingServiceHome");
CreditRatingServiceHome ratingHome = (CreditRatingServiceHome)
PortableRemoteObject.narrow(homeObj,cls);
9-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Java and J2EE Code in BPEL Concepts
if (ratingHome == null) {
addAuditTrailEntry("Failed to lookup 'ejb.session.CreditRating'"
+ ". Please make sure that the bean has been"
+ " successfully deployed");
return;
}
CreditRatingService ratingService = ratingHome.create();
// Retrieve ssn from scope
Element ssn =
(Element)getVariableData("input","payload","/ssn");
int rating = ratingService.getRating( ssn.getNodeValue() );
addAuditTrailEntry("Rating is: " + rating);
}
}
}
}
setVariableData("output", "payload",
"/tns:rating", new Integer(rating));
catch (NamingException ne) {
addAuditTrailEntry(ne);
catch (ClassNotFoundException cnfe) {
addAuditTrailEntry(cnfe);
catch (CreateException ce) {
addAuditTrailEntry(ce);
catch (RemoteException re) {
addAuditTrailEntry(re);
}
]]>
</bpelx:exec>
Using an XML Facade to Simplify DOM Manipulation
You can use an XML facade to simplify DOM manipulation. Oracle BPEL Process
Manager provides a lightweight Java Architecture for XML Binding (JAXB)-like Java
object model on top of XML (called a facade). An XML facade provides a Java
bean-like front end for an XML document or element that has a schema. Facade classes
can provide easy manipulation of the XML document and element in Java programs.
You add the XML facade by using a createFacade method within the bpelx:exec
statement in the .bpel file. For example:
<bpelx:exec name= ...
<![CDATA
...
Element element = ...
(Element)getVariableData("input","payload","/loanApplication/"):
//Create an XMLFacade for the Loan Application Document
LoanApplication xmlLoanApp=
LoanApplicationFactory.createFacade(element);
...
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
Incorporating Java and J2EE Code in BPEL Processes
9-3
Overview of Java and J2EE Code in BPEL Concepts
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:
<format:typeMapping encoding="Java" style="Java">
<format:typeMap typeName="tns:commentType"
formatType="com.otn.services.CommentType" />
<format:typeMap typeName="tns:commentsType"
formatType="com.otn.services.CommentsType" />
</format:typeMapping>
See Also:
"schemac" on page 19-25
bpelx:exec Built-in Methods
Table 9–1 lists a set of bpelx:exec built-in methods that you can use to read and
update scope variables, instance metadata, and audit trails.
Table 9–1
Built in Methods for bpelx:exec
Method Name
Description
Object lookup( String name )
JNDI access
Locator getLocator( )
BPEL Process Manager Locator
long getInstanceId( )
Unique ID associated with each instance
String setTitle( String title ) /
String getTitle()
Title of this instance
String setStatus( String status ) /
String getStatus()
Status of this instance
void setIndex( int i, String value )
/ String getIndex( int i )
Six indexes can be used for search
void setPriority( int priority ) /
int getPriority()
Priority
void setCreator( String creator ) /
String getCreator()
Who initiated this instance
void setCustomKey( String customKey
) / String getCustomKey()
Second primary key
void setMetadata( String metadata )
/ String getMetadata ()
Metadata for generating lists
9-4 Oracle BPEL Process Manager Developer’s Guide
Using Java Embedding in a BPEL Process
Table 9–1 (Cont.) Built in Methods for bpelx:exec
Method Name
Description
String getPreference( String key )
Access preference defined in bpel.xml
void addAuditTrailEntry(String
message, Object detail)
Add an entry to the audit trail
void addAuditTrailEntry(Throwable t) Access file stored in the suitcase
Object getVariableData(String name)
throws BPELFault
Access and update variables stored in the
scope
Object getVariableData(String name,
String partOrQuery) throws BPELFault
Object getVariableData(String name,
String part, String query)
void setVariableData(String name,
Object value)
void setVariableData(String name,
String part, Object value)
void setVariableData(String name,
String part, String query, Object
value)
Using Java Embedding in a BPEL Process
In Oracle JDeveloper, you can add the bpelx:exec activity, and copy the code
snippet into a dialog box, as follows:
1.
Drag and drop the Java Embedding activity (with the coffee cup icon) from the
Component Palette.
2.
Double-click the Java Embedding activity to display the Java Embedding window.
3.
Name the Java Embedding activity.
4.
In the Code Snippet field, enter (or cut and paste) the Java code.
For example, the bpel:exec code example described under "Using the bpelx:exec
Tag to Embed Java Code Snippets into a BPEL Process" on page 9-2 appears as
follows:
Incorporating Java and J2EE Code in BPEL Processes
9-5
Summary
See Also: "Java Embedding Activity" on page B-16 for additional
details about this activity, including adding JAR files to classpaths.
Summary
This chapter demonstrates how you can embed sections of Java code into a BPEL
process using one of the following techniques:
■
■
If the Java application has a BPEL-compatible interface, you can use WSIF binding
or wrap the Java code in a SOAP service.
You can directly embed the Java code by including an inline code snippet using
bpelx:exec. This snippet is executed within the transaction context of Oracle
BPEL Server. This method allows you to propagate that transaction to your own
session and entity beans. You can use a set of built-in methods to enable the
bpelx:exec snippet to read and update variables, change instance meta data,
and throw faults. To simplify DOM manipulation, use an XML facade.
9-6 Oracle BPEL Process Manager Developer’s Guide
10
Events and Timeouts
This chapter describes how to use events and timeouts. Because Web services can take
a long time to return a response, a BPEL process must be able to time out and continue
with the rest of the flow after a period of time.
This chapter contains the following topics:
■
Use Case for Events and Timeouts
■
Overview of Event and Timeout Concepts
■
Using the Pick Activity to Select Between Continuing a Process or Waiting
■
Using the Wait Activity to Set an Expiration Time
■
Setting Timeouts for Synchronous Processes
■
Defining a Timeout
■
Summary
Use Case for Events and Timeouts
In this use case, you program a BPEL process to wait one minute for a response from
the Star Loan Web service. If Star Loan does not respond in one minute, then the BPEL
process automatically selects the United Loan offer. In the real world, the time limit is
more like 48 hours. However, for this example, you do not want to wait that long to
see if your BPEL process is working properly.
See Also:
■
The following sample file:
SOA_Oracle_
Home\bpel\samples\tutorials\108.Timeouts
Overview of Event and Timeout Concepts
Because asynchronous Web services can take a long time to return a response, a BPEL
process must be able to time out, or give up waiting, and continue with the rest of the
flow after a certain amount of time. You can use the pick activity to configure a BPEL
flow to either wait a specified amount of time or to continue performing its duties. To
set an expiration period for the time, you can use the wait activity.
If you plan to set timeouts for synchronous processes that connect to a remote
database, you need to set the syncMaxWaitTime timeout property in the
domain.xml file.
Events and Timeouts 10-1
Using the Pick Activity to Select Between Continuing a Process or
Waiting
The pick activity provides two branches, each one with a condition. The branch that
has its condition satisfied first is executed. In the following example, one branch’s
condition is to receive a loan offer, and the other branch’s condition is to wait a
specified amount of time.
Figure 10–1 provides an overview. The following activities take place:
1.
An invoke activity initiates a service, in this case, a request for a loan offer from
Star Loan.
2.
The pick activity begins next. It has the following conditions:
■
■
onMessage: This condition has code for receiving a reply in the form of a loan
offer from the Star Loan Web service. The onMessage code is the same as the
code for receiving a response from the Star Loan Web service before a timeout
was added.
onAlarm: This condition has code for a timeout of one minute. This time is
defined as PT1M, which means to wait one minute before timing out. In this
timeout setting, S 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
executes. The other branch then is not executed.
10-2 Oracle BPEL Process Manager Developer’s Guide
Using the Pick Activity to Select Between Continuing a Process or Waiting
Figure 10–1 Overview of the Pick Activity
BPEL
Process
Initiate
service
<invoke>
WSDL
<pick>
Wait for
callback
<onMessage>
Time out
in 1M
<onAlarm>
Star
Loan
Logic
Post
Callback
Logic
Post
Timeout
The following code segment defines the pick activity for this operation:
<pick>
<!-- receive the result of the remote process -->
<onMessage partnerLink="LoanService"
portType="services:LoanServiceCallback"
operation="onResult" variable="loanOffer">
<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>
Events and Timeouts 10-3
See Also:
■
■
The following samples:
"107.Exceptions" on page 1-10 for a tutorial that uses a pick
activity
"108.Timeouts" on page 1-10 for a tutorial that uses a pick
activity
■
"Pick Activity" on page B-19
■
SOA_Oracle_Home\bpel\samples\references\Pick
Using the Wait Activity to Set an Expiration Time
The wait activity allows a process to wait for a given time period or until a time limit
has been reached. Exactly one of the expiration criteria must be specified.
<wait (for="duration-expr" | until="deadline-expr") standard-attributes>
standard-elements
</wait>
See Also: The following documentation for examples of defining a
wait activity:
■
"SleepBroker" on page 1-8 for a demonstration that uses a wait
activity
■
"Wait Activity" on page B-31
■
Oracle BPEL Process Manager Order Booking Tutorial
■
SOA_Oracle_Home\bpel\samples\references\Wait
Setting Timeouts for Synchronous Processes
For synchronous processes that connect to a remote database, you must increase the
syncMaxWaitTime timeout property in the SOA_Oracle_
Home\bpel\domains\default\config\domain.xml file:
<property id="syncMaxWaitTime">
<name>Delivery result receiver maximum wait time</name>
<value>60000000</value>
<comment>
<![CDATA[The maximum time the process result receiver will wait for a
result before returning. Results from asynchronous BPEL processes are
retrieved synchronously via a receiver that will wait for a result from the
container.
<p/>
The default value is 60 seconds.]]>
</comment>
</property>
Defining a Timeout
To define a timeout, follow these steps:
1.
Drag and drop a Pick activity into a BPEL process.
The Pick activity includes the onMessage (envelope icon) and onAlarm (alarm
clock icon) branches.
10-4 Oracle BPEL Process Manager Developer’s Guide
Defining a Timeout
2.
Double-click the OnAlarm branch of the onAlarm activity and set its time limit to
1 minute instead of 1 hour.
3.
Click OK.
4.
Double-click the onMessage activity, and edit its attributes to receive the response
from the loan service.
Events and Timeouts 10-5
See Also:
"Pick Activity" on page B-19
Summary
Instead of performing multiple operations at the same time as with the flow attribute,
you can use the pick activity to define a number of operations such that only the first
one to complete is executed. The example in this chapter is of a pick activity where one
branch is an asynchronous callback from a loan service, and the other branch is a
timeout set at one minute.
10-6 Oracle BPEL Process Manager Developer’s Guide
11
Invoking a BPEL Process
This chapter shows how a Java or JSP application can call a BPEL process to perform
functions or use services.
This chapter contains the following topics:
■
Use Case for Invoking a BPEL Process
■
Overview of Invoking BPEL Process Concepts
■
Sending Messages to a BPEL Process from a Java or JSP Application
■
Summary
Use Case for Invoking a BPEL Process
In this use case, you learn how to invoke synchronous and asynchronous BPEL
processes through either the simple object access protocol (SOAP) or Java. The BPEL
process accepts a social security number and sends a credit rating in return. The user
Web interface is provided by a JSP file, which takes the input and passes it to a BPEL
process to get back a credit rating.
See Also:
■
The following sample file:
SOA_Oracle_
Home\bpel\samples\tutorials\102.InvokingProcesses
Overview of Invoking BPEL Process Concepts
A Java or a JSP application can call a BPEL process to perform functions or use
services. A BPEL process is itself a Web service, defining and supporting a client
interface through WSDL and SOAP. However, you can make BPEL processes
deployed on Oracle BPEL Process Manager available to clients through a Java API.
See Also: The tutorial at
http://www.oracle.com/technology/products/ias/bpel/p
df/orabpel-Tutorial7-InvokingBPELProcesses.pdf
Sending Messages to a BPEL Process from a Java or JSP Application
You can invoke a BPEL process as a Web service through a WSDL or SOAP interface,
or as a Java component through its client Java interface. The application puts the
request in the form of a payload that then goes to the BPEL process. The BPEL process
receives the payload and responds with a payload containing the information that the
application requested.
Invoking a BPEL Process 11-1
Sending Messages to a BPEL Process from a Java or JSP Application
Figure 11–1 shows how an application interacts with a BPEL process through a client
partner link, using one of a number of possible protocols.
Figure 11–1 Application Interaction with a BPEL Process
BPEL Process
SOAP /
WSDL
WSDL
Client
PartnerLink
<receive>
Java
Business
Delegate
<reply>
Invoking a BPEL Process with the Generic Java API
You can invoke a BPEL process by using a generic Java API. Oracle provides classes
that enable your BPEL process to use a generic Java API to connect to Oracle BPEL
Process Manager and to pass XML messages through a generic Java API. You can use
these classes to perform either two-way or one-way invoke operations.
This section covers the following topics:
■
Connecting to Oracle BPEL Process Manager with the Locator Class
■
Passing XML Messages Through Java
■
Invoking a Two-Way Operation Through the Java API
■
Invoking a One-Way Operation Through the Java API
Connecting to Oracle BPEL Process Manager with the Locator Class
Oracle provides a com.oracle.bpel.client.Locator class that supports a
flexible client interface without being affected by server clustering and other
production details. Use this class to do the following:
■
Connect to Oracle BPEL Process Manager, authenticating if required
■
Obtain handles to services provided by Oracle BPEL Server
For example, the Locator class can connect to the default domain on a local Oracle
BPEL Process Manager and fetch a list of BPEL processes deployed on that server. In
this case, the Locator class returns a handle to a
com.oracle.bpel.client.dispatch.IDeliveryService instance.
The following instance can invoke or initiate BPEL processes on Oracle BPEL Server:
import com.oracle.bpel.client.Locator;
import com.oracle.bpel.client.dispatch.IDeliveryService;
// Connect to domain “default” using password “bpel”
// null IP address means local server
11-2 Oracle BPEL Process Manager Developer’s Guide
Sending Messages to a BPEL Process from a Java or JSP Application
Locator locator = new Locator("default", "welcome1", null);
IDeliveryService deliveryService = (IDeliveryService)locator.lookupService
(IDeliveryService.SERVICE_NAME );
Note: This instance code example uses welcome1 as the domain
password. Update the instance with the correct password for your
environment.
Passing XML Messages Through Java
Because all Web services, including BPEL processes, accept and return XML messages,
any Java API using Web services needs a way to pass XML data through Java. You can
use the Oracle BPEL Process Manager client class
com.oracle.bpel.client.NormalizedMessage to activate an XML message
dynamically.
For example, to activate an input message for the CreditRatingService from static
string XML data, you can use the following code:
import com.oracle.bpel.client.NormalizedMessage;
String xml =
"<ssn xmlns=\"http://services.otn.com\">123456789</ssn>";
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload", xml );
In practice, you activate NormalizedMessages more dynamically. For full
documentation of the NormalizedMessage class, see the Oracle BPEL Process
Manager Javadocs in:
■
SOA_Oracle_Home\bpel\docs\apidocs
Invoking a Two-Way Operation Through the Java API
After a delivery service has been instantiated, it can initiate a BPEL process with a
NormalizedMessage XML message. You can use one of the
IDeliveryService.request() methods to invoke a two-way Web service
operation, which has an input message and returns a result synchronously.
The IDeliveryService.request() method is overloaded. To find out more about
its available versions, refer to the Oracle BPEL Process Manager Javadoc. In this
version, the request() method has the following signature:
public NormalizedMessage request(java.lang.String processId,
java.lang.String operationName,
NormalizedMessage message)
throws java.rmi.RemoteException
The following code example (provided with the Oracle BPEL Process Manager
samples) demonstrates how to use this API to invoke the CreditRatingService
BPEL process.
<%@page import="java.util.Map" %>
<%@page import="com.oracle.bpel.client.Locator" %>
<%@page import="com.oracle.bpel.client.NormalizedMessage" %>
<%@page import="com.oracle.bpel.client.dispatch.IDeliveryService" %>
<html>
Invoking a BPEL Process 11-3
Sending Messages to a BPEL Process from a Java or JSP Application
<head>
<title>Invoke CreditRatingService</title>
</head>
<body>
<%
String ssn = request.getParameter("ssn");
if(ssn == null)
ssn = "123-12-1234";
String xml = "<ssn xmlns=\"http://services.otn.com\">"
+ ssn + "</ssn>";
Locator locator = new Locator("default","bpel",null);
IDeliveryService deliveryService =
(IDeliveryService)locator.lookupService
(IDeliveryService.SERVICE_NAME );
// construct the normalized message and send to oracle bpel process
manager
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload", xml );
NormalizedMessage res =
deliveryService.request("CreditRatingService", "process", nm);
Map payload = res.getPayload();
out.println( "BPELProcess CreditRatingService executed!<br>" );
out.println( "Credit Rating is " + payload.get("payload") );
%>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\tutorials\102.InvokingProcesses
\jsp\invokeCreditRatingService.jsp
Invoking a One-Way Operation Through the Java API
A one-way invoke operation has only an input message and does not return a result.
The procedure for invoking a one-way BPEL operation through the Java API is very
similar to how you invoke two-way operations. The difference is that you use the
IDeliveryService.post() method instead of IDeliveryService.request().
This method is overloaded; its methods invoke a one-way operation on a BPEL
process and thus return void because a response is not expected (at least not a
synchronous response).
From the Javadoc for
com.oracle.bpel.client.dispatch.IDeliveryService:
public void post(java.lang.String processId,
java.lang.String operationName,
NormalizedMessage message)
throws java.rmi.RemoteException
In the following example, the post() method is very similar to the request()
method shown in the two-way example discussed earlier, except that it returns void.
<%@page import="com.oracle.bpel.client.Locator" %>
<%@page import="com.oracle.bpel.client.NormalizedMessage" %>
<%@page import="com.oracle.bpel.client.dispatch.IDeliveryService" %>
...
Locator locator = new Locator("default", "bpel", null);
...
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload" , xml );
deliveryService.post("HelloWorld", "initiate", nm);
11-4 Oracle BPEL Process Manager Developer’s Guide
Sending Messages to a BPEL Process from a Java or JSP Application
out.println( "BPELProcess HelloWorld initiated!" );
%>
See Also:
■
The following sample:
SOA_Oracle_
Home\bpel\samples\tutorials\102.InvokingProcesses
\jsp\invokeHelloWorld.jsp
Retrieving Status or Results from Asynchronous BPEL Processes
If you use the Java API to initiate an asynchronous BPEL process, you must often
consider how to receive the result of the process, because a typical Java client cannot
be called back the same way as a Web service. You can handle this problem by using
the following strategies:
■
■
Have your code inform users of the progress of the process. For example, the
LoanFlowPlus BPEL demonstration application (located in SOA_Oracle_
Home\bpel\samples\demos\LoanDemoPlus) informs users of the progress
through a user task, such as manually approving the final loan offer. You also can
have the process send some sort of notification, such as an e-mail message or a
JMS message, when it completes.
For asynchronous BPEL processes, have the Java client poll the result. In this
case, the client needs a handle to fetch status information for a particular instance.
The post() method does not automatically return such a handle, but it does
allow the client to specify a conversation ID. This ID can be any unique identifier
that the client can later use to identify a specific instance and retrieve status
information for it. See the Oracle BPEL Javadocs for the
com.oracle.bpel.client.NormalizedMessage class to find the specific
field name for the conversation ID and other properties, which you can set at the
time a BPEL process is instantiated through the Java API. You can also use the
com.oracle.bpel.client.Locator.lookupInstance(String key)
method to locate a specific instance based on a conversation ID.
You also can use the NormalizedMessage properties to specify the address of a
Web service for the callback. This initiates an asynchronous BPEL process from
Java, but receives a SOAP/XML callback to a Web service listener.
It is also possible using the supported NormalizedMessage properties to specify the
address of a Web service for the callback and therefore initiate an asynchronous BPEL
process from Java, but receive a SOAP/XML callback to a Web service listener.
Contact Oracle Support Services for more information on how to retrieve status or
results from an asynchronous BPEL process in your specific environment.
Using the Java API from a Remote Client
The code examples described in previous sections are executed within the same
application server container in which the Oracle BPEL Process Manager is running.
You can run these APIs from a remote client, however, and use them through a remote
method invocation (RMI) from a remote application server. The RMI client code you
use depends on the application server in which the client is running. Work with Oracle
Support Services regarding how to use the Oracle BPEL Process Manager Java API
over RMI for your specific client configuration and environment.
Invoking a BPEL Process 11-5
Summary
Invoking a BPEL Process with the Web Service/SOAP Interface
After you deploy a BPEL process 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 through its Web service interface in the standard way you
access any Web service: by writing a client that uses the BPEL process WSDL interface
definition and SOAP as a protocol.
Summary
Once deployed, a BPEL process is exposed through both a WSDL or SOAP interface
and a business delegate Java interface. The Java business delegate interface allows Java
and JSP applications to initiate new instances of a BPEL process.
The Java business delegate can be used locally or remotely using RMI. The Java
business delegate is JTA-aware, allowing the initiation of a process to be part of a
broader transaction.
11-6 Oracle BPEL Process Manager Developer’s Guide
12
Interaction Patterns
This chapter identifies common interaction patterns between a BPEL process and
another application, and shows the best use practices for each.
This chapter contains the following topics:
■
One-Way Message
■
Synchronous Interaction
■
Asynchronous Interaction
■
Asynchronous Interaction with Timeout
■
Asynchronous Interaction with a Notification Timer
■
One Request, Multiple Responses
■
One Request, One of Two Possible Responses
■
One Request, a Mandatory Response, and an Optional Response
■
Partial Processing
■
Multiple Application Interactions
■
Summary
One-Way Message
In a one-way message, or fire and forget, the client sends a message to the service, and
the service does not need to reply. Figure 12–1 provides an overview.
Interaction Patterns 12-1
Synchronous Interaction
Figure 12–1 One-Way Message
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Client BPEL Process
Service BPEL Process
WSDL
PartnerLink
<invoke>
d1
<receive>
BPEL Process as the Client
As the client, the BPEL process needs a valid partner link and an invoke activity with
the target service and the message. As with all partner activities, the WSDL file defines
the interaction.
BPEL Process as the Service
To accept a message from the client, the BPEL process needs a receive activity.
Synchronous Interaction
In a synchronous interaction, a client sends a request to a service, and receives an
immediate reply. The BPEL process can be at either end of this interaction, and must
be coded based on its role as either the client or the service. Figure 12–2 provides an
overview.
12-2 Oracle BPEL Process Manager Developer’s Guide
Asynchronous Interaction
Figure 12–2 Synchronous Interaction
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
BPEL Process
BPEL Process
Call
service
<invoke>
WSDL
Client
PartnerLink
d1
<receive>
d2
f1
OR
<reply>
BPEL Process as the Client
When the BPEL process is on the client side of a synchronous transaction, it needs an
invoke activity. The port on the client side both sends the request and receives the
reply. As with all partner activities, the WSDL file defines the interaction.
BPEL Process as the Service
When the BPEL process is on the service side of a synchronous transaction, it needs a
receive activity to accept the incoming request, and a reply activity to return either the
requested information or an error message (a fault).
See Also:
Chapter 4, "Invoking a Synchronous Web Service"
Asynchronous Interaction
In an asynchronous interaction, a client sends a request to a service and waits until the
service replies. Figure 12–3 provides an overview.
Interaction Patterns 12-3
Asynchronous Interaction with Timeout
Figure 12–3 Asynchronous Interaction
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Client BPEL Process
Service BPEL Process
WSDL
PartnerLink
Call
service
<invoke>
Get
response
<receive>
<receive>
d1
<invoke>
d2
BPEL Process as the Client
When the BPEL process is on the client side of an asynchronous transaction, it needs
an invoke activity to send the request and a receive activity to receive the reply. As
with all partner activities, the WSDL file defines the interaction.
BPEL Process as the Service
As with a synchronous transaction, when the BPEL process is on the service side of an
asynchronous transaction, it needs a receive activity to accept the incoming request
and an invoke activity to return either the requested information or a fault.
See Also:
Chapter 5, "Invoking an Asynchronous Web Service"
Asynchronous Interaction with Timeout
In an asynchronous interaction with a timeout, a client sends a request to a service and
waits until it receives a reply, or until a certain time limit is reached, whichever comes
first. Figure 12–4 provides an overview.
12-4 Oracle BPEL Process Manager Developer’s Guide
Asynchronous Interaction with a Notification Timer
Figure 12–4 Asynchronous Interaction with Timeout
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Client BPEL Process
Service BPEL Process
WSDL
PartnerLink
Call
service
<invoke>
<receive>
d1
<pick>
d2
Wait for
callback
<onMessage>
Time out
in 1M
<onAlarm>
Logic
Post
Callback
Logic
Post
Timeout
<invoke>
BPEL Process as the Client
When the BPEL process is on the client side of an asynchronous transaction with a
timeout, it needs an invoke activity to send the request and a pick activity with two
branches: an onMessage branch and an onAlarm branch. If the reply comes after the
time limit has expired, the message goes to the dead letter queue. As with all partner
activities, the WSDL file defines the interaction.
See Also: "Using the Pick Activity to Select Between Continuing a
Process or Waiting" on page 10-2
BPEL Process as the Service
The behavior of the service BPEL process is the same as with the asynchronous
interaction with the BPEL process as the service, as described in "BPEL Process as the
Service" on page 12-4.
Asynchronous Interaction with a Notification Timer
In an asynchronous interaction with a notification time, a client sends a request to a
service and waits for a reply, although a notification is sent after a timer expires. The
client continues to wait for the reply from the service even after the timer has expired.
Figure 12–5 provides an overview.
Interaction Patterns 12-5
One Request, Multiple Responses
Figure 12–5 Asynchronous Interaction with a Notification Time
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
BPEL Process
Service BPEL Process
WSDL
PartnerLink
<scope>
Call
service
<invoke>
Wait for
Callback
<receive>
<receive>
d1
d2
<invoke>
<onAlarm>
Notify
Someone
BPEL Process as the Client
When the BPEL process is on the client side of this transaction, it needs a scope activity
containing an invoke activity to send the request, and a receive activity to accept the
reply. The onAlarm handler of the scope activity has a time limit and instructions on
what to do when the timer expires. For example, wait 30 minutes, then send a warning
indicating that the process is taking longer than expected. As with all partner
activities, the WSDL file defines the interaction.
BPEL Process as the Service
The behavior for the service BPEL process is the same as with the asynchronous
interaction with the BPEL process as the service, as described in "BPEL Process as the
Service" on page 12-4.
One Request, Multiple Responses
In this interaction type, the client sends a single request to a service and receives
multiple responses in return. For example, the request can be to order a product
online, and the first response can be the estimated delivery time, the second response a
payment confirmation, and the third response a notification that the product has
shipped. In this example, the number and types of responses are expected. Figure 12–6
provides an overview.
12-6 Oracle BPEL Process Manager Developer’s Guide
One Request, One of Two Possible Responses
Figure 12–6 One Request, Multiple Responses
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
WSDL
Client
PartnerLink
Client BPEL Process
Call
service
<invoke>
Service BPEL Process
d1
<receive>
<sequence>
<sequence>
<receive>
d2
<invoke>
<receive>
d3
<invoke>
<receive>
d4
<invoke>
</sequence>
</sequence>
BPEL Process as the Client
When the BPEL process is on the client side of this transaction, it needs an invoke
activity to send the request, and a sequence activity with three receive activities, one
for each reply. As with all partner activities, the WSDL file defines the interaction.
BPEL Process as the Service
The BPEL service needs a receive activity to accept the message from the client, and a
sequence attribute with three invoke activities, one for each reply.
One Request, One of Two Possible Responses
In an interaction using one request and one of two possible responses, the client sends
a single request to a service and receives one of two possible responses. For example,
the request can be to order a product online, and the first response can be either an
in-stock message, or an out-of-stock message. Figure 12–7 provides an overview.
Interaction Patterns 12-7
One Request, a Mandatory Response, and an Optional Response
Figure 12–7 One Request, One of Two Possible Responses
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Service BPEL Process
Client BPEL Process
WSDL
PartnerLink
Call
service
<invoke>
<receive>
d1
<switch>
<pick>
<onMessage A>
<onMessage B>
Logic A
Logic B
Msg A
or
Msg B
Item in stock?
<otherwise>
<invoke>
Msg A
<invoke>
Msg B
BPEL Process as the Client
When the BPEL process is on the client side of this transaction, it needs the following:
■
■
■
An invoke activity to send the request
A pick activity with two branches: one onMessage for the in-stock response and
instructions on what to do if an in-stock message is received
A second onMessage for the out-of-stock response and instructions on what to do
if an out-of-stock message is received
As with all partner activities, the WSDL file defines the interaction.
See Also: "Using the Pick Activity to Select Between Continuing a
Process or Waiting" on page 10-2
BPEL Process as the Service
The BPEL service needs a receive activity to accept the message from the client, and a
switch activity with two branches, one with an invoke activity sending the in-stock
message if the item is available, and a second branch with an invoke activity sending
the out-of-stock message if the item is not available.
One Request, a Mandatory Response, and an Optional Response
In this type of interaction, the client sends a single request to a service and receives one
or two responses. Here, the request is to order a product online. If the product is
delayed, the service sends a message letting the customer know. In any case, the
service always sends a notification when the item ships. Figure 12–8 provides an
overview.
12-8 Oracle BPEL Process Manager Developer’s Guide
Partial Processing
Figure 12–8 One Request, a Mandatory Response, and an Optional Response
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Client BPEL Process
Service BPEL Process
WSDL
PartnerLink
<scope>
Call
service
<invoke>
Wait for
Callback
<receive Msg B>
<receive>
d1
<switch>
Msg A
(maybe)
Delay?
<otherwise>
<onMessage A>
Notify User
of Delay
<invoke>
Msg A
When
product
ships...
Msg B
<invokes>
Msg B
BPEL Process as the Client
When the BPEL process is on the client side of this transaction, it needs a scope activity
containing the invoke activity to send the request, and a receive activity to accept the
mandatory reply. The onMessage handler of the scope activity is set to accept the
optional message and instructions on what to do if the optional message is received
(for example, notify you that the product has been delayed). The client BPEL process
waits to receive the mandatory reply. If the mandatory reply is received first, the BPEL
process continues without waiting for the optional reply. As with all partner activities,
the WSDL file defines the interaction.
BPEL Process as the Service
The BPEL service needs a scope activity containing the receive activity and an invoke
activity to send the mandatory shipping message, and the scope’s onAlarm handler to
send the optional delayed message if a timer expires (for example, send the delayed
message if the item is not shipped in 24 hours).
Partial Processing
In partial processing, the client sends a request to a service and receives an immediate
response, but processing continues on the service side. For example, the client sends a
request to purchase a vacation package, and the service sends an immediate reply
Interaction Patterns 12-9
Multiple Application Interactions
confirming the purchase, then continues on to book the hotel, the flight, the rental car,
and so on. This pattern can also include multiple shot callbacks, followed by
longer-term processing. Figure 12–9 provides an overview.
Figure 12–9 Partial Processing
Deployment Descriptor
(bpel.xml)
Deployment Descriptor
(bpel.xml)
Client BPEL Process
Service BPEL Process
WSDL
PartnerLink
Call
service
<invoke>
<receive>
d1
<receive>
d2
<receive>
<invoke>
d3
<invoke>
<receive>
d4
<receive>
<receive>
<receive>
<receive>
<receive>
<receive>
BPEL Process as the Client
In this case, the BPEL client is simple; it needs an invoke activity for each request and a
receive activity for each reply for asynchronous transactions, or just an invoke activity
for each synchronous transaction. Once those transactions are complete, the remaining
work is handled by the service. As with all partner activities, the WSDL file defines the
interaction.
BPEL Process as the Service
The BPEL service needs a receive activity for each request from the client, and a reply
activity for each response. Once the responses are finished, the service BPEL process
can continue with its processing, using the information gathered in the interaction to
perform the necessary tasks without any further input from the client.
Multiple Application Interactions
In some cases, there are more than two applications involved in a transaction, for
example, a buyer, seller, and shipper. In this case, the buyer sends a request to the
seller, the seller sends a request to the shipper, and the shipper sends a notification to
the buyer. This A-to-B-to-C-to-A transaction pattern can handle many transactions at
once. Therefore, a mechanism is required for keeping track of which message goes
where. Figure 12–10 provides an overview.
As with all partner activities, the WSDL file defines the interaction.
12-10 Oracle BPEL Process Manager Developer’s Guide
Summary
Figure 12–10
Multiple Party Interactions
BPEL Process A
Buyer
BPEL Process B
Seller
WSDL
PartnerLink
<invoke>
B
<receive>
A
d1
<invoke>
C
<receive>
C
d3
d2
WSDL
PartnerLink
WSDL
PartnerLink
BPEL Process C
Shipper
<receive>
BC
<invoke>
A
See Also: "Managing Multiple Active BPEL Process Instances Using
Correlation Methods" on page 5-7 for more information about
WS-addressing and correlation sets
Summary
BPEL processes can serve as both clients or services, and this chapter lists several
common interaction patterns and describes best practices for implementing these
interactions.
Interaction Patterns
12-11
Summary
12-12 Oracle BPEL Process Manager Developer’s Guide
Part III
Oracle BPEL Process Manager Services
This part describes how Oracle BPEL Process Manager adds value and ease of use to
key BPEL development concepts to support the following services.
This part contains the following chapters:
■
Chapter 13, "XSLT Mapper and Transformations"
■
Chapter 14, "Oracle BPEL Process Manager Notification Service"
■
Chapter 15, "Oracle BPEL Process Manager Workflow Services"
■
Chapter 16, "Worklist Application"
■
Chapter 17, "Sensors"
■
Chapter 18, "BPEL Process Integration with Business Rules"
13
XSLT Mapper and Transformations
This chapter describes features of the XSLT Mapper and provides step-by-step
instructions for mapping a sample purchase order schema to an invoice schema.
This chapter contains the following topics:
■
Use Case for Transformation
■
Creating an XSL Map File
■
Overview of the XSLT Mapper
■
Using the XSLT Mapper
■
Testing the Map
■
Summary
Use Case for Transformation
Transformation use is demonstrated in several Oracle BPEL Process Manager use
cases.
See:
■
SOA_Oracle_home\bpel\samples\demos\XSLMapper
■
SOA_Oracle_
home\bpel\samples\tutorials\114.XSLTTransformatio
ns
■
Oracle BPEL Process Manager Order Booking Tutorial
Creating an XSL Map File
Transformations are performed in an XSL map file in which you map source schema
elements to target schema elements. This section describes two methods for creating
the XSL map file:
■
Creating a New XSL Map File
■
Creating an XSL Map File from Imported Source and Target Schema Files
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.
Note:
XSLT Mapper and Transformations 13-1
Creating an XSL Map File
Creating a New XSL Map File
A transform activity enables you to create a transformation using the XSLT Mapper
tool. This tool enables you to map 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.
2.
Double-click the transform activity.
The Transform window appears.
3.
Specify the following information:
■
■
■
Source variable from which to map elements
Source part of the variable (for example, a payload schema consisting of a
purchase order request) from which to map
Target variable to which to map elements
13-2 Oracle BPEL Process Manager Developer’s Guide
Creating an XSL Map File
■
Target part of the variable (for example, a payload schema consisting of an
invoice) to which to map
4.
Specify a map file name or accept the default name in the Mapper File field. The
map file is the file in which you create your mappings using the XSLT Mapper
transformation tool.
5.
Click the magic wand icon (second icon) to create a new mapping. If the file
already exists, click the note pad icon (third icon) to edit the mapping.
The XSLT Mapper appears.
6.
Go to "Overview of the XSLT Mapper" on page 13-5 for an overview of using the
XSLT Mapper.
Creating an XSL Map File from Imported Source and Target Schema Files
Note: If you select a file with a.xslt extension such as
xform.xslt, it opens the mapper pane to create a new XSL file
named xform.xslt.xsl, even though your intension was to use the
existing xform.xslt file. A .xsl extension is appended to any file
that does not already have a .xsl extension, and you must create the
mappings in the new file. As a workaround, ensure that your files first
have an extension of .xsl. If the XSL file has an extension of .xslt,
then rename it to .xsl.
The following steps provide a high level overview of how to create an XSL map using
the existing po.xsd and invoice.xsd files in the SOA_Oracle_
home\bpel\samples\demos\XSLMapper directory.
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).
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.
XSLT Mapper and Transformations 13-3
Creating an XSL Map File
8.
Under Target, expand Project Schema files > invoice.xsd > Invoice as the root
element for the target.
9.
Click OK.
A new XSL map is created.
10. Save and close the file now or begin to design your transformation. Information on
using the XSLT Mapper tool is provided in "Overview of the XSLT Mapper" on
page 13-5.
11. Drag and drop a transform activity from the Component Palette into your BPEL
process.
12. Double-click the transform activity.
13. Specify the following information:
■
Source variable from which to map elements
13-4 Oracle BPEL Process Manager Developer’s Guide
Overview of the XSLT Mapper
■
■
■
Source part of the variable (for example, a payload schema consisting of a
purchase order request) from which to map
Target variable to which to map elements
Target part of the variable (for example, a payload schema consisting of an
invoice) to which to map
14. Click the flashlight icon (first icon) to the right of the Mapper File field to browse
for the map file name you specified in Step 6.
15. Click Open.
16. Click OK.
The XSLT Mapper displays your XSL map file.
17. Go to "Overview of the XSLT Mapper" on page 13-5 for an overview of using the
XSLT Mapper.
Overview of the XSLT Mapper
You use the XSLT Mapper transformation tool to create the contents of a map file.
Figure 13–1 shows the layout of the XSLT Mapper.
Figure 13–1 Layout of the XSLT Mapper
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
XSLT Mapper and Transformations 13-5
Using the XSLT Mapper
■
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 13–1 (for example, type, cardinality, and so on).
The Functions Palette in the upper right of Figure 13–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.
The XSLT Mapper provides three separate context sensitive menus:
■
One in the source panel
■
One in the target panel
■
One in the mapper pane or canvas in the middle
Right-click each of the three separate panels to see what the context menus look like. A
full set of Undo Auto Map, Redo, Delete, and Delete All functions are also available.
Notes on the Mapper
■
■
■
A node in the target tree can be linked only once (that is, you cannot have two
links connecting a node in the target tree).
An incomplete function and expression does not result in an XPath expression in
the source view. If you switch from the design view to the source view with one or
more incomplete expressions, the Mapper Messages window displays warning
messages.
When you map duplicate elements in the XSLT Mapper, the style sheet becomes
invalid and you cannot work in the Design view. The Log Window shows the
following error messages when you map an element with a duplicate name:
Error: This Node is Already Mapped :
"/ns0:rulebase/for-each/ns0:if/ns0:atom/ns0:rel"
Error: This Node is Already Mapped :
"/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:ind"
Error: This Node is Already Mapped :
"/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:var"
The workaround is to give each element a unique name.
Using the XSLT Mapper
The following sections describe how to use the XSLT Mapper:
■
Simple Copy by Linking Nodes
■
Setting Constant Values
■
Adding Functions
■
Editing XPath Expressions
■
Adding XSLT Constructs
■
Automatically Mapping Nodes
■
Viewing Unmapped Target Nodes
■
Generating Dictionaries
■
Creating Map Parameters and Variables
13-6 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
■
Searching Source and Target Nodes
■
Ignoring Elements in the XSLT Document
■
Replacing a Schema in the XSLT Mapper
Simple Copy by Linking Nodes
To copy an attribute or leaf-element in the source to an attribute or leaf-element in the
target, drag and drop the source to the target. Copy the element PurchaseOrder/ID to
Invoice/ID and the attribute PurchaseOrder/OrderDate to Invoice/InvoiceDate, as
shown in Figure 13–2.
Figure 13–2 Linking Nodes
Setting Constant Values
Perform the following steps to set a constant value.
1.
Select a node in the target tree.
2.
Invoke the context menu by right-clicking the mouse.
3.
Select the Set Text menu option.
4.
Enter text in the Set Text window (for example, Discount Applied, as shown in
Figure 13–3).
5.
Click OK to save the text.
A T icon is displayed next to the node that has text associated with it.
6.
If you want to remove the text associated with the node, right click the node to
invoke the Set Text window again. Delete the contents and click OK.
Figure 13–3 Set Text Window
XSLT Mapper and Transformations 13-7
Using the XSLT Mapper
See Also: The online Help for the Set Text window for detailed
information
Adding Functions
In addition to the standard XPath 1.0 functions, the Mapper provides a number of
prebuilt extension functions and has the ability to support user-defined functions 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 window with a description of the function appears. 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 13–4.
13-8 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 13–4 Using the Concat Function
See Also: The documentation for the XPath extension functions,
which is described in Appendix D, "XPath Extension Functions"
Editing Function Parameters
To edit the parameters of the concat function, double-click the function icon to launch
the Edit Function - concat window. This window enables you to add, remove, and
reorder parameters. If you want to add a new comma parameter so that the output of
the concat function is Last, First, then click Add to add a comma and reorder the
parameters to get this output.
Figure 13–5 Editing Function Parameters
XSLT Mapper and Transformations 13-9
Using the XSLT Mapper
See Also: The online Help for the Edit Function window by clicking
the Help button to see how to add, remove, and reorder function
parameters
Chaining Functions
Complex expressions can be built by chaining functions. To remove all leading and
trailing spaces from the output of the above concat function, use the left-trim and
right-trim functions and chain them as shown in the Figure 13–6.
The chaining function can also be defined by dragging and dropping the function to a
connecting link.
Figure 13–6 Chaining Functions
Named Templates
Some complicated mapping logic cannot be represented or achieved by visual
mappings. For these situations, named templates are useful. Named templates enable
you to share common mapping logic. You can define the common mapping logic as a
named template and then use it as often as you want.
You define named templates in the source view, and they appear in the User Defined
Named Templates list of the Component Palette. You can use named templates in
almost the same way as you use other functions. The only difference is that you cannot
link the output of a named template to a function or another named template; you can
only link its output to a target node in the target tree.
To write named templates, you must be familiar with the XSLT language. See any
XSLT book or visit the following URL for details about writing named templates:
http://www.w3.org/TR/xslt
Importing User-Defined Functions
You can import your own set of Java functions, which appear in the function palette
under the User Defined Extension Functions category. They can be used like any
other function. To add functions, select Preferences > XSL Maps from the Tools main
menu.
See Also: SOA_Oracle_
home\bpel\samples\demos\XSLMapper\ExtensionFunctions
\README.txt for detailed instructions
13-10 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Editing XPath Expressions
To use an XPath expression in a transformation mapping, select Advanced Functions
from the Component Palette and drag and drop xpath-expression from the list into
the transformation window, as shown in Figure 13–7.
Figure 13–7 Editing XPath Expressions
When you double-click the icon, the Edit XPath Expression window appears, as shown
in Figure 13–8. You can press the Ctrl key and then the spacebar to invoke the XPath
Building Assistant.
Figure 13–8 Edit XPath Expression Window
Figure 13–9 shows the XPath Building Assistant.
XSLT Mapper and Transformations
13-11
Using the XSLT Mapper
Figure 13–9 The XPath Building Assistant
See Also: The online Help for the Edit XPath Expression window,
which includes a link to instructions on using the XPath Building
Assistant
Adding XSLT Constructs
While mapping complex schemas, it is sometimes essential to conditionally map a
source node to a target or map an array of elements in the source to an array of
elements in the target. The XSLT Mapper provides various XSLT constructs in the
context sensitive menu of the target tree for the preceding scenarios. To add an XSLT
element like for-each, if, or choose to a schema element, select the element in the
target tree. Right-click and select Add XSL Node to bring up the context menu and
choose the required XSLT element in the menu.
Elements that display in the XSLT Constructs list and
http://www.w3.org/1999/XSL/Transform list of the Component
Palette cannot be dragged and dropped into the designer window.
Note:
See Also: Oracle BPEL Process Manager Order Booking Tutorial for an
example of using a for-each node
Conditional Processing with xsl:if
Note that HQAccount and BranchAccount are part of a choice in the PurchaseOrder
schema; only one of them exists in an actual instance. To illustrate conditional
mapping, copy PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/AccountNumber only if it exists. To do this:
1.
Select Invoice/BilledToAccount/AccountNumber in the target tree and right-click
to bring up the context sensitive menu.
2.
Select Add XSL Node, and then if and connect
PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/if.
3.
Connect PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/if/AccountNumber.
Figure 13–10 shows the results.
13-12 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 13–10 Conditional Processing with xsl:if
Conditional Processing with xsl:choose
You can copy PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/AccountNumber, if it exists. Otherwise, copy
PurchaseOrder/BranchAccount to Invoice/BilledToAccount/AccountNumber as
follows:
1.
Select Invoice/BilledToAccount/AccountNumber in the target tree and right-click
to bring up the context sensitive menu.
2.
Select Add XSL Node, and then choose and connect
PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/choose/when to define the condition.
3.
Connect PurchaseOrder/HQAccount/AccountNumber to
Invoice/BilledToAccount/choose/when/AccountNumber.
4.
Select XSL Add Node and then choose in the target tree and right-click to bring up
the context sensitive menu.
5.
Select Add XSL node and then otherwise from the menu.
6.
Connect PurchaseOrder/BranchAccount/AccountNumber to
Invoice/BilledToAccount/choose/otherwise/AccountNumber.
Figure 13–11 shows the results.
XSLT Mapper and Transformations
13-13
Using the XSLT Mapper
Figure 13–11 Conditional Processing with xsl:choose
Handling Repetition or Arrays
The XSLT Mapper allows repeating elements on the source to be copied to repeating
elements on the target. For example, copy
PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/Item as
follows:
1.
Select Invoice/ShippedItems/Item in the target tree and right-click to bring up the
context sensitive menu.
2.
Select Add XSL Node, and then for-each and connect
PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/for-each
to define the iteration.
3.
Connect PurchaseOrder/Items/HighPriorityItems/Item/ProductName to
Invoice/ShippedItems/for-each/Item/ProductName.
4.
Connect PurchaseOrder/Items/HighPriorityItems/Item/Quantity to
Invoice/ShippedItems/for-each/Item/Quantity.
5.
Connect PurchaseOrder/Items/HighPriorityItems/Item/USPrice to
Invoice/ShippedItems/for-each/Item/PriceCharged.
Figure 13–12 shows the results.
Figure 13–12 Handling Repetition or Arrays
13-14 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Executing an auto map automatically inserts xsl:for-each. To
see the auto map in use, drag and drop
PurchaseOrder/Items/LowPriorityItems to Invoice/UnShippedItems;
for-each is automatically created.
Note:
Automatically Mapping Nodes
Mapping nonleaf nodes starts the auto map feature. The system automatically tries to
link all relevant nodes under the selected source and target. Try the auto map feature
by mapping PurchaseOrder/ShipTo/Address to Invoice/ShippedTo/Address. All
nodes under Address are automatically mapped, as shown in Figure 13–13.
Figure 13–13 Auto Mapping
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 13–14.
Figure 13–14
Auto Map Preferences
This window enables you to customize your auto mapping as follows:
XSLT Mapper and Transformations
13-15
Using the XSLT Mapper
■
■
■
■
■
Invoke the automatic mapping feature, which attempts to automatically link all
relevant nodes under the selected source and target. When disabled, you must
individually map relevant nodes.
Display and review all potential source-to-target mappings detected by the XSLT
Mapper, and then confirm to create them.
Be prompted to customize the auto map preferences before the auto map is
invoked.
Select the Basic or Advanced method for automatically mapping source and target
nodes. This enables you to customize how the XSLT mapper attempts to
automatically link all relevant nodes under the selected source and target.
Manage your dictionaries. The XSLT Mapper uses the rules defined in a dictionary
when attempting to automatically map source and target elements.
See Also: The online Help for the Auto Map Preferences window by
clicking the Help button to see a description of the fields
To see potential source mapping candidates for a target node, right-click the target
node, select Show Matches, and click OK in the Auto Map Preferences window. The
Auto Map window appears, as shown in Figure 13–15.
13-16 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 13–15
Auto Mapping Candidates
See Also: The online Help for the Auto Map window by clicking the
Help button to see a description of the fields
Auto Map with Confirmation
When the Confirm Auto Map Results check box shown in Figure 13–14 is selected, a
confirmation window appears. If matches are found, the potential source-to-target
mappings detected by the XSLT Mapper are displayed, as shown in Figure 13–16. The
window enables you to filter one or more mappings.
XSLT Mapper and Transformations
13-17
Using the XSLT Mapper
Figure 13–16 Auto Map with Confirmation
See Also: The online Help for the Auto Map window by clicking the
Help button to see a description of the fields
Viewing Unmapped Target Nodes
You can view a list of target nodes that are currently unmapped to source nodes. Right
click in the mapper pane and select Completion Status. This window provides
statistics at the bottom about the number of unmapped target nodes. This window
enables you to identify and correct any unmapped nodes before you test your
transformation mapping logic on the Test XSL Map window. Select a target node in the
list. The node is highlighted. A check mark indicates that the target node is required to
be mapped. If not required, the check box is empty.
Figure 13–17 provides an example of the Completion Status window.
13-18 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 13–17
Completion Status
Generating Dictionaries
A dictionary is an XML file that captures the synonyms for mappings. Right-click the
mapper pane and select Generate Dictionary. This prompts you for the dictionary
name and the directory in which to place the dictionary. The XSLT Mapper uses the
rules defined in the dictionary when attempting to automatically map source and
target elements. For example, you may want to map a purchase order to a purchase
order acknowledgment, then reuse most of the map definitions later:
1.
Build all the mapping logic for the purchase order and purchase order
acknowledgment.
2.
Generate a dictionary for the created map.
3.
Create a new map using a different purchase order and purchase order
acknowledgment.
4.
Load the previously created dictionary by selecting Preferences > XSL Maps >
Auto Map in the Tools main menu of Oracle JDeveloper.
5.
Perform an automatic mapping from the purchase order to the purchase order
acknowledgment.
Creating Map Parameters and Variables
You can create map parameters and variables. You create map parameters in the
source tree and map variables in the target tree.
Note the following issues:
■
Parameters are created in the source tree, are global, and can be used anywhere in
the mappings.
XSLT Mapper and Transformations
13-19
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 as long as they are in different scopes. Local variables
can only be used in their scopes, while global variables can be used anywhere
in the mappings.
Creating a Map Parameter
1.
Right-click the source tree root and select Add Parameter.
The Create Parameter window appears.
2.
Specify details:
3.
Click OK.
Creating a Map Variable
1.
Right-click the target tree root and select Add Variable. If you right-click a node
below the target tree root, select Insert Variable.
The Create Variable window appears.
2.
Specify details:
13-20 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
3.
Click OK.
Searching Source and Target Nodes
You can search source and target nodes. For example, you can search in a source node
named invoice for all occurrences of the subnode named price.
1.
Right-click a source or target node.
2.
Enter a keyword for which to search.
3.
Specify additional details, as necessary. For example:
■
■
Select Search Annotations if you want annotations text to also be searched.
Specify the scope of the search. You can search the entire source or target tree,
search starting from a selected position, or search within a selected subtree.
XSLT Mapper and Transformations
13-21
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.
Ignoring Elements in the XSLT Document
When the XSLT Mapper encounters any elements in the XSLT document that cannot be
found in the source or target schema, it is unable to process them and displays an
Invalid Source Node Path error. XSL map generation fails. You can create and
import a file that directs the XSLT Mapper to ignore and preserve these specific
elements during XSLT parsing by selecting Preferences > XSL Maps in the Tools main
menu of Oracle JDeveloper.
For example, preprocessing may create elements named myElement and
myOtherElementWithNS that you want the XSLT Mapper to ignore when it creates
the graphical representation of the XSLT document. You create and import a file with
these elements to ignore that includes the following syntax:
<elements-to-ignore>
<element name="myElement"/>
<element name="myOtherElementWithNS" namespace="NS"/>
</elements-to-ignore>
You must restart Oracle JDeveloper after importing the file.
13-22 Oracle BPEL Process Manager Developer’s Guide
Testing the Map
Replacing a Schema in the XSLT Mapper
You can replace the map source schema and map target schema that currently display
in the XSLT Mapper. Right click in either the source or target panel and select Replace
Schema. This opens the Select Source and Target Schema window shown in
Figure 13–18, which enables you to select the new source or target schema to use.
Figure 13–18
Replacing a Schema
Testing the Map
The XSLT Mapper provides a test utility to test the style sheet or map. The test tool can
be invoked by selecting the Test menu item from the mapper, as shown in
Figure 13–19.
XSLT Mapper and Transformations
13-23
Testing the Map
Figure 13–19 Invoking the Test Window
Test XSL Map Window
The Test XSL Map window shown in Figure 13–20 enables you to test the
transformation mapping logic you designed with the XSLT Mapper. The test settings
you specify are stored and do not need to be entered again the next time you test. Test
settings must be entered again if you close and reopen Oracle JDeveloper.
13-24 Oracle BPEL Process Manager Developer’s Guide
Testing the Map
Figure 13–20 Test XSL Map Window
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 file for the
test. The source XML file displays in an Oracle JDeveloper XML editor.
If the map has defined parameters, the Parameters table appears. If you want to
specify a value, click Specify Value and make 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.
7.
Click OK.
The test results appear.
For this example, the source XML and target XML display side-by-side, with the
XSL map underneath (the default setting). 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.
XSLT Mapper and Transformations
13-25
Testing the Map
Generating Reports
You can generate an HTML report with the following information:
■
XSL map file name, source and target schema file names, their root element names,
and their root element namespaces
■
Target document mappings
■
Target fields not mapped (including mandatory fields)
■
Sample transformation map execution
To generate a report, right-click the transformation window and select Generate
Report. The Generate Report window appears in the transformation window, as
shown in Figure 13–21. Note that if the map has defined parameters, the Parameters
table appears.
13-26 Oracle BPEL Process Manager Developer’s Guide
Testing the Map
Figure 13–21
The Generate Report Window
See Also: The online Help for the Generate Report window by
clicking the Help button to see detailed information
Correcting Memory Errors When Generating Reports
If you attempt to generate a report and receive an out-of-memory error, increase the
heap size of the JVM as follows:
1.
Open the JDev_Oracle_Home\jdev\bin\jdev.conf file.
2.
Go to the following section:
# Set the maximum heap to 512M
#
AddVMOption
-Xmx512M
3.
Increase the size of the heap as follows (for example, to 1024)
AddVMOption
-Xmx1024M
In addition, you can also uncheck the Open Report option on the Generate Report
window before generating the report.
Sample XML Generation
You can customize sample XML generation by specifying the following parameters.
Select Preferences > XSL Maps in the Tools main menu of Oracle JDeveloper to
display the Preferences window.
■
Number of repeating elements
Specifies how many occurrences of an element are created if the element has the
attribute maxOccurs set to a value greater than 1. If the specified value is greater
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.
XSLT Mapper and Transformations
13-27
Summary
■
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.
Summary
This chapter describes features of the XSLT Mapper, such as:
■
Creating an XSL map file
■
Copying by linking nodes
■
Creating functions
■
Chaining functions
■
Editing XPath expressions
■
Adding XSLT constructs such as if, choose, otherwise, and for-each
■
Automatically mapping target and source nodes
■
Viewing unmapped target nodes
■
Generating dictionaries
■
Creating map parameters and variables
■
Searching source and target nodes
■
Ignoring elements in an XSLT document
■
Replacing schemas in the XSLT Mapper
■
Testing mappings
■
Generating mapping reports
This chapter shows these features by providing step-by-step instructions for mapping
a sample purchase order schema to an invoice schema.
13-28 Oracle BPEL Process Manager Developer’s Guide
14
Oracle BPEL Process Manager
Notification Service
The notification service in Oracle BPEL Process Manager enables you to send
notifications from a BPEL process using a variety of channels. Oracle BPEL Process
Manager can deliver these notifications by e-mail, voice message, fax, pager, or short
message service (SMS).
This chapter contains the following topics:
■
Use Cases for Notification Service
■
Overview of Notification Service Concepts
■
Configuring the Notification Service in Oracle JDeveloper
■
Summary
Use Cases for Notification Service
Various scenarios may require sending e-mail messages or other types of notifications
to users as part of the process flow. For example, certain types of exceptions that
cannot be handled automatically may require manual intervention. In this case, Oracle
JDeveloper uses the notification service to alert users by voice, SMS, fax, pager, or
e-mail. In an approval workflow (for example, an expense report approval), you can
send notifications to the task assignee when a specific task requires action, or you can
notify the task creator by e-mail when the approval is complete. In some cases, contact
information (e-mail address or telephone number) is obtained dynamically as part of
the process and in other cases the details are looked up from a user directory.
The tutorial 130.SendEmailWithAttachments demonstrates how to model a
notification in Oracle JDeveloper and send an e-mail with an attachment.
See: SOA_Oracle_
Home\bpel\samples\tutorials\130.SendEmailWithAttachments
The OrderBooking tutorial demonstrates how to add an e-mail notification to the
POAcknowledge process.
See:
Oracle BPEL Process Manager Order Booking Tutorial
Overview of Notification Service Concepts
Terms used for the notification service include:
Oracle BPEL Process Manager Notification Service 14-1
Overview of Notification Service Concepts
■
■
■
Notification—an asynchronous message sent to a user by a specific channel. The
message can be sent as an e-mail message, a voice message, a fax message, a pager
message, or an SMS message.
Actionable notification—a notification to which the user can respond. For
example, workflow sends an e-mail message to a manager to approve or reject a
purchase order. The manager approves or rejects the request by replying to the
e-mail with appropriate content.
Oracle Application Server Wireless—the wireless and voice component of Oracle
Application Server. OracleAS Wireless includes a messaging component that
handles the sending and receiving of messages to and from devices. When you
install OracleAS Wireless, you can specify one of the following notification service
options:
–
Connect to an external server to deliver messages, such as e-mail, SMS, fax,
voice, or pager.
–
Use Oracle's hosted service at
http://messenger.oracle.com/
Oracle BPEL Process Manager is preconfigured to send notifications using Oracle's
hosted wireless service.
–
The notification service supports sending e-mail through the SMTP protocol
and receiving e-mail from IMAP- and POP-based e-mail accounts.
Figure 14–1 shows the notification service interfaces and supported service types.
Figure 14–1 Notification Service Interfaces and Supported Service Types
E-mail
Server
Web Services
Interface
SMTP
IMAP/
POP
Fax
Server
Notification
Service
SMS
Server
Voice
Gateway
Oracle Application Server
Wireless Server
Java
Interface
SOAP
call
Pager
Reliable Notification Service
Oracle BPEL Process Manager provides support for the reliable notification service.
The outbound notification service creates a notification message with a unique
notification ID and stores the message and unique ID in the dehydration store. It then
enqueues this unique ID in the JMS queue and commits the transaction. A message
driven-bean (MDB) listening on this queue dequeues the message and sends a
notification to the user. If there is any notification failure, the notification service retries
three times. If the retries all fail, it marks this notification as errored.
14-2 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
To send an error notification after resolving the problem, you must write a script to
update the BPELNotification table status to SEND. For example:
UPDATE BPELNotification
SET status = 'RETRY',
ATTEMPTEDNUMBER = 0
WHERE ID = <notification id>
By default, the notification service retries three time. If you want to add more retries
(for example, 5), add the following property in SOA_Oracle_
Home/bpel\system\services\config\wf_config.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 wf_config.xml.
For example, to retry every 10 minutes:
<property name="oracle.bpel.services.notification.publisher_interval" value="10"
/>
Configuring the Notification Service in Oracle JDeveloper
The diagram window in Oracle JDeveloper includes the notification channels in the
Component Palette, as shown in Figure 14–2.
Figure 14–2 Diagram Window in Oracle JDeveloper—Notification Activity
To use a notification channel, do the following:
1.
Select Process Activities from the Component Palette list.
2.
Drag and drop a notification channel from the Component Palette list:
■
Email
■
Fax
■
Pager
Oracle BPEL Process Manager Notification Service 14-3
Configuring the Notification Service in Oracle JDeveloper
3.
■
SMS
■
Voice
See the following section based on the notification channel you selected.
If You Selected...
See...
Email
"The E-mail Notification Channel" on page 14-4 to configure e-mail
notification
Fax
"The Fax Notification Channel" on page 14-8 to configure fax notification
Pager
"The Pager Notification Channel" on page 14-10 to configure pager
notification
SMS
"The SMS Notification Channel" on page 14-11 to configure SMS
notification
Voice
"The Voice Notification Channel" on page 14-12 to configure voice message
notification
The E-mail Notification Channel
When you select Email from the Component Palette, the Edit Email window appears.
Figure 14–3 shows the required e-mail notification parameters.
Figure 14–3 Edit Email Window
1.
Enter information for each field as described in Table 14–1.
Table 14–1
E-mail Notification Parameters
Name
Description
From Account
The name of the account used to send this message. The
configuration details for this e-mail account name must exist on
Oracle BPEL Server.
14-4 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
Table 14–1 (Cont.) E-mail Notification Parameters
Name
Description
To
The e-mail address to which the message is to be delivered. This
can be a) a static e-mail address entered at the time the message
is created, or b) an e-mail address looked up using the identity
service, or c) a dynamic address from the payload. The XPath
Expression Builder can be used to get the dynamic e-mail
address from the input. See "Setting E-mail Addresses and
Telephone Numbers Dynamically" on page 14-13.
CC and Bcc
The e-mail addresses to which the message is copied and blind
copied. This can be a static or dynamic address as described for
the To address.
Reply To
The e-mail address to use for replies. This can be a static or
dynamic address as described for the To address.
Subject
Subject of the e-mail message. This can be free text or dynamic
text. The XPath Expression Builder can be used to set dynamic
text based on data from process variables that you specify.
Body
Message body of the e-mail message. This can be plain text,
XML, free text, or dynamic text, as described for the Subject
parameter.
Multipart message with n
attachments
Select to specify e-mail attachments. See "Setting E-mail
Attachments" on page 14-5.
The number of attachments if Multipart message is selected.
The number includes the body. For example, if you have a body
and one attachment, specify 2 here.
2.
Click OK.
The BPEL fragment that invokes the notification service to send the e-mail
message is created.
See Also: Oracle BPEL Process Manager Administrator’s Guide for
details about e-mail configuration instructions to perform outside of
Oracle JDeveloper
Setting E-mail Attachments
When you send e-mail attachments, you mark the e-mail as a multipart message and
set the number of attachments to send. The number of attachments includes the body
plus the attachments. (For example, to send an e-mail message with one file as an
attachment, set the number to 2.) When sending attachments, set the content body to
have a MultiPart element that contains as many BodyPart elements as the number
of attachments. Each BodyPart has three elements: ContentBody, MimeType, and
BodyPartName. All three elements must be set for each attachment.
To add one attachment to an e-mail message, do the following:
1.
Select Email as the notification channel from the Component Palette.
2.
Specify values for To, Subject, and Body.
3.
Select Multipart message and enter 2 for the number of attachments. (Note that
the number of attachments must include the body part.)
The MultiPart element with two body parts is generated. The first body part is
for the message body and the other is used for the attachment. The BPEL fragment
with an assign activity with multiple copy rules is generated. One of the copy
rules copies the attachment, as follows:
Oracle BPEL Process Manager Notification Service 14-5
Configuring the Notification Service in Oracle JDeveloper
<assign name="Assign">
<copy>
<from expression="string('Default')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:FromAccountName"/>
</copy>
...
<!-copy statements relate to body and attachment -->
<copy>
<from>
<Content xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<MimeType
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">multipart/mixed
</MimeType>
<ContentBody
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<MultiPart
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<BodyPart
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<MimeType
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
<ContentBody
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
<BodyPartName
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
</BodyPart>
<BodyPart
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<MimeType
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
<ContentBody
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
<BodyPartName
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
</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:
14-6 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
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:
a.
Search for BodyPart[2] MimeType and change the from expression to
copy ’image/gif’ as the MimeType (instead of the autogenerated
’text/html’).
b.
Search for BodyPart[2] BodyPartName and change the from
expression to copy ’MyImage.gif’ (instead of the autogenerated
’NotificationAttachment2.html’).
c.
Search for BodyPart[2] ContentBody and change the from expression
to copy the content of MyImage.gif (instead of the autogenerated expression
string(’message2’)).
You can use the readFile XPath function to read the contents of the file:
ora:readFile(‘<name of the file in the project | HTTP URL | File URL>’)
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’)
The new BPEL copy statement is as follows:
<copy>
<from expression="string('image/gif')"/>
<to variable="varNotificationReq" part="EmailPayload" query=
"/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:MimeT
ype"/>
</copy>
<copy>
<from expression="string('MyImage.gif')"/>
Oracle BPEL Process Manager Notification Service 14-7
Configuring the Notification Service in Oracle JDeveloper
<to variable="varNotificationReq" part="EmailPayload" query=
"/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:BodyP
artName"/>
</copy>
<copy>
<from expression="ora:readFile(‘file:///c:/MyImage.gif’)"/>
<to variable="varNotificationReq" part="EmailPayload" query=
"/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:Conte
ntBody"/>
</copy>
See: SOA_Oracle_
Home\bpel\samples\tutorials\130.SendEmailWithAttachments
for an example of sending attachments using e-mail
Formatting the Body of an E-mail Message as HTML
You can format the body of an e-mail message as HTML rather than as straight text. To
do this, apply an XSLT transform to generate the e-mail body. Add in the XSLT tag
you want to use. Tools such as XMLSpy can provide assistance in writing and testing
the XSLT. The MIME type should be string(’text/html;charset=UTF-8’).
The e-mail notification assignment should look as follows:
<copy>
<from
expression="ora:processXSLT('TransformPositionSummary7.xslt',bpws:
getVariableData('ClientPositionSummary'))"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns9:Content/ns9:ContentBody"/>
</copy>
The Fax Notification Channel
When you select Fax from the Component Palette, the Edit Fax window appears.
Figure 14–4 shows the required fax notification parameters.
14-8 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
Figure 14–4 Edit Fax Window
1.
Enter information for each field as described in Table 14–2.
Table 14–2
Fax Notification Parameters
Name
Description
Fax Number
The fax number to which the message is to be delivered. This
can be a) a static fax number entered at the time the message is
created, or b) a fax number looked up using the identity service,
or c) a dynamic fax number from the payload. The XPath
Expression Builder can be used to get the dynamic fax number
from the input.
Cover Page
The cover page name. The cover page details must exist on the
server. The cover page can be in PDF, Microsoft Word, HTML, or
plain text format. (This field is optional.) The XPath Expression
Builder can be used to set dynamic text based on data from
process variables that you specify.
Body
Fax message body. This must be plain text or HTML. This can be
free text or dynamic text as described for the Cover page
parameter.
2.
Click OK.
The BPEL fragment that invokes the notification service for fax notification is
created.
See Also: Oracle BPEL Process Manager Administrator’s Guide for
details about fax configuration instructions to perform outside of
Oracle JDeveloper
Oracle BPEL Process Manager Notification Service 14-9
Configuring the Notification Service in Oracle JDeveloper
The Pager Notification Channel
When you select Pager from the Component Palette, the Edit Pager window appears.
Figure 14–5 shows the required pager notification parameters.
Figure 14–5 Edit Pager Window
1.
Enter information for each field as described in Table 14–3.
Table 14–3
Pager Notification Parameters
Name
Description
From Number
The pager number from which the message is to be sent. This
can be a) a static pager number entered at the time the message
is created, or b) a dynamic pager number from the payload. The
XPath Expression Builder can be used to get the dynamic pager
number from the input.
Pager Number
The number of the recipient of this message. This can be a) a
static pager number entered at the time the message is created,
or b) a pager number looked up using the identity service, or c) a
dynamic pager number from the payload. The XPath Expression
Builder can be used to get the dynamic pager number from the
input.
Body
Pager message body. This must be plain text. This can be free
text or dynamic text as described for the From Number
parameter.
2.
Click OK.
The BPEL fragment that invokes the notification service for pager notification is
created.
14-10 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
See Also: Oracle BPEL Process Manager Administrator’s Guide for
details about pager configuration instructions to perform outside of
Oracle JDeveloper
The SMS Notification Channel
When you select SMS from the Component Palette, the Edit SMS window appears.
Figure 14–6 shows the required SMS notification parameters.
Figure 14–6 Edit SMS Window
1.
Enter information for each field as described in Table 14–4.
Table 14–4
SMS Notification Parameters
Name
Description
From number
The telephone number from which to send the SMS notification.
This can be a static telephone number entered at the time the
message is created or a dynamic telephone number from the
payload. The XPath Expression Builder can be used to get the
dynamic telephone number from the input. See "Setting E-mail
Addresses and Telephone Numbers Dynamically" on page 14-13.
Telephone number
The telephone number to which the message is to be delivered.
This can be a) a static telephone number entered at the time the
message is created, or b) a telephone number looked up using
the identity service, or c) a dynamic telephone number from the
payload. The XPath Expression Builder can be used to get the
dynamic telephone number from the input.
Subject
Subject of the SMS message. This can be free text or dynamic
text. The XPath Expression Builder can be used to set dynamic
text based on data from process variables that you specify.
Body
SMS message body. This must be plain text. This can be free text
or dynamic text as described for the Subject parameter.
Oracle BPEL Process Manager Notification Service 14-11
Configuring the Notification Service in Oracle JDeveloper
2.
Click OK.
The BPEL fragment that invokes the notification service for SMS notification is
created.
See Also: Oracle BPEL Process Manager Administrator’s Guide for
details about SMS configuration instructions to perform outside of
Oracle JDeveloper
The Voice Notification Channel
When you select Voice from the Component Palette, the Edit Voice window appears.
Figure 14–7 shows the required voice notification parameters.
Figure 14–7 Edit Voice Window
1.
Enter information for each field as described in Table 14–5.
Table 14–5
Voice Notification Parameters
Name
Description
Telephone number
The telephone number to which the message is to be delivered.
This can be a) a static telephone number entered at the time the
message is created, or b) a telephone number looked up using
the identity service, or c) a dynamic telephone number from the
payload. The XPath Expression Builder can be used to get the
dynamic telephone number from the input.
Body
Message body. This can be plain text or XML. Also, this can be
free text or dynamic text. The XPath Expression Builder can be
used to set dynamic text based on data from process variables
that you specify.
2.
Click OK.
14-12 Oracle BPEL Process Manager Developer’s Guide
Configuring the Notification Service in Oracle JDeveloper
The BPEL fragment that invokes the notification service for voice notification is
created.
See Also: Oracle BPEL Process Manager Administrator’s Guide for
details about voice configuration instructions to perform outside of
Oracle JDeveloper
Setting E-mail Addresses and Telephone Numbers Dynamically
You may need to set e-mail addresses or telephone numbers dynamically based on
certain process variables. You can also look up contact information for a specific user
using the built-in XPath functions for the identity service.
■
To get the e-mail address or telephone number directly from the payload, use the
following XPath:
bpws:getVariableData('<variable name>', '<part>','<input xpath to get an
address>')
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 14–6 lists the property names
that can be used in this XPath function.
Table 14–6
Properties for the Dynamic User XPath Function
Property Name
Description
mail
Look up a user’s e-mail address
telephoneNumber
Look up a user’s telephone number
mobile
Look up a user’s mobile telephone number
homephone
Look up a user’s home telephone number
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');
Oracle BPEL Process Manager Notification Service 14-13
Configuring the Notification 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');
Selecting Notification Recipients by Browsing the User Directory
You can select users or groups to whom you want to send notifications by browsing
the user directory (OID, JAZN/XML, LDAP, and so on) that is configured for use by
Oracle BPEL Process Manager. Click the first icon (the flashlight) to the right of To (or
any recipient field) on any assignee window to start the Identity lookup dialog.
See Also: Chapter 15, "Oracle BPEL Process Manager Workflow
Services" for additional details about using the Identity lookup dialog
Starting Business Processes with the E-mail Activation Agent
You use the e-mail activation agent element activationAgents to start business
processes by e-mail. The following steps are required to design a business process to
start by e-mail.
1.
Create a business process.
2.
Add the e-mail activation agent activationAgents element to bpel.xml.
–
3.
See Table 14–7, " E-mail Activation Element and Respective Attributes in
bpel.xml" and "The activationAgents Element Structure in bpel.xml" on
page 14-14.
Include a corresponding account name configuration file in the project.
–
Name the file the same as the name of the accountName attribute of
activationAgents in bpel.xml. See "The accountName XML File
Structure" on page 14-15.
Table 14–7 describes the activationAgents element and activationAgent
attributes of the activation fragment contained in the bpel.xml file.
Table 14–7
E-mail Activation Element and Respective Attributes in bpel.xml
Element/Attribute Name
Description
Name of the activation agent class. Use the
/activationAgents/activationA com.collaxa.cube.activation.mail.MailActivationAgent
gent[className]
class as the activation agent.
Polling interval of the messages in seconds
/activationAgents/activationA
gent[heartBeatInterval]
/activationAgents/activationA Name of the e-mail configuration file. For example, if the account name
is test_account, then the test_account.xml file is included in all
gent/property
the e-mail-related information.
name=”accountName”
The activationAgents Element Structure in bpel.xml
The following code example shows the structure of the activationAgents element
contained in bpel.xml.
<activationAgents>
<activationAgent
className="com.collaxa.cube.activation.mail.MailActivationAgent"
heartBeatInterval="60">
14-14 Oracle BPEL Process Manager Developer’s Guide
Summary
<property name="accountName">test_account</property>
</activationAgent>
</activationAgents>
The accountName XML File Structure
The following code example shows the structure of the accountName XML file.
<mailAccount xmlns="http://services.oracle.com/bpel/mail/account">
<userInfo>
<displayName>[display name]</displayName>
<organization>[organization name]</organization>
<replyTo>[replyTo email address]</replyTo>
</userInfo>
<outgoingServer>
<protocol>smtp</protocol>
<host>[outgoing smtp server]</host>
<authenticationRequired>false</authenticationRequired>
</outgoingServer>
<incomingServer>
<protocol>pop3</protocol>
<host>[incoming pop3 server]</host>
<email>[pop user name]</email>
<password>[plain text email password]</password>
</incomingServer>
<!-- IMAP server config -->
<!-<incomingServer>
<protocol>imap</protocol>
<host>[incoming imap server]</host>
<email>[imap user name]</email>
<password>[plain text email password]</password>
<folderName>InBox</folderName>
</incomingServer>
-->
</mailAccount>
XML Validation Failure with the Notification Service
If you set the validateXML property to true (the default is false) on the Manage BPEL
Domain window of Oracle BPEL Control, each message exchanged with each of the
Web services is validated against its schema. However, notification services fail during
XML validity checks at run time. This is because the BPEL variables exchanged with
the notification service are not completely initialized in the BPEL process. Part of the
initialization happens in the service itself.
Summary
This chapter describes how you can send an e-mail, voice, fax, pager, or short message
service (SMS) message from Oracle BPEL Process Manager.
Oracle BPEL Process Manager Notification Service 14-15
Summary
14-16 Oracle BPEL Process Manager Developer’s Guide
15
Oracle BPEL Process Manager Workflow
Services
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:
■
Oracle BPEL Process Manager Workflow Services 10.1.2 and 10.1.3.1.0
Compatibility
■
Overview of Workflow Services
■
Use Cases for Workflow Services
■
Participant Types in Workflow Services
■
Overview of the Modeling Process
■
Task 1: Creating the Human Task Definition with the Human Task Editor
■
Task 2: Associating the Human Task with a BPEL Process
■
Task 3: Generating the Task Display Form
■
How Changes to a Workflow Appear in Worklist Application
■
Notifications from Workflow Services
■
End-to-End Workflow Examples
■
Workflow Services
■
Configuring the Assignment Service
■
Workflow Service and Identity Service Related XPath Extension Functions
■
NLS Configuration
■
Summary
Oracle BPEL Process Manager Workflow Services 15-1
Oracle BPEL Process Manager Workflow Services 10.1.2 and 10.1.3.1.0 Compatibility
See Also:
■
■
■
Oracle BPEL Process Manager Administrator’s Guide for the
organizational hierarchy of the demonstration user community
used in examples throughout this chapter
SOA_Oracle_Home\bpel\system\xmllib\workflow for
workflow service WSDL files
Oracle BPEL Process Manager Workflow Services API Reference
available in SOA_Oracle_
Home\bpel\docs\workflow\index.html
Oracle BPEL Process Manager Workflow Services 10.1.2 and 10.1.3.1.0
Compatibility
Workflows that you designed in 10.1.2 with the workflow wizard can be deployed and
run in 10.1.3.1.0. However, you must use the old worklist URL to access these tasks:
http://localhost:9700/integration/oldworklistapp/Login
For release 10.1.3.1.0, the workflow wizard has been replaced by a Human Task editor.
This editor enables you to specify task settings such as task outcome, payload
structure, task participants, assignment and routing policy, expiration and escalation
policy, notification settings, and so on.
You cannot use the Human Task editor to edit 10.1.2-based workflows. To use any new
10.1.3.1.0 functionality, the task scope of the workflow must be manually migrated to
use the new workflow metadata.
Note also that this is the last release in which you can deploy workflows designed
with 10.1.2.
Overview of Workflow Services
Workflow services enable you to interleave human interactions with connectivity to
systems and services within an end-to-end process flow. As shown in Figure 15–1,
workflow services are linked to a BPEL process through a WSDL contract, like any
other Web service. The process assigns a task to a user or role and waits for a response.
The users act on the task using Oracle BPEL Worklist Application.
Figure 15–1 High-Level View of Workflow Services in Oracle BPEL Process Manager
WSDL
Assign Task
BPEL
Process
Task Complete
Workflow
Services
Worklist
Application
Update
Task
Users
Terms used in workflow services include:
■
Task—work that needs to be done by a user, role, or group
15-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Workflow Services
■
■
■
■
■
Notification—an e-mail, voice, fax, pager, or short message service (SMS) message
that is sent when a user is assigned a task or informed that the status of the task
has changed
Worklist—an enumeration of the tasks, or work items, assigned to or of interest to
a user
Human Task editor—A tool that enables you to specify task settings such as task
outcome, payload structure, task participants, assignment and routing policy,
expiration and escalation policy, notification settings, and so on
.task file —The metadata task configuration file that stores the task settings
specified with the Human Task editor
routing slip—Contains information about the flow pattern for the workflow,
assignees, escalation policy, expiration duration, signature policy, sequence in
which the participants interact in the task, and so on.
Features of workflow services include:
■
■
■
Work queues
–
Standard work queues — high priority tasks, tasks due soon, new tasks, and
so on
–
Custom work queues — Users can define new work queues based on specific
search criteria
–
Proxy work queues — can grant access to other users to selected work queues.
Other users can act on your behalf on those tasks
Rules Integration
–
User rules — can define custom delegation, auto-approval, or vacation rules
–
Group rules — can define auto-assignment rules for roles or groups; for
example, round-robin, least-busy, and so on.
Task assignment and routing—includes creating tasks from the business process
and assigning the tasks to users or roles. Other task assignment and routing
features include:
–
Support for task expiration and automatic renewal
–
Support for task delegation, escalation, and reapproval
–
Storage of task history information for auditing, extending workflows to
include other workflows, and the ability to archive and purge task details
based on specified policies
–
Support for creating custom task escalation rule functions
–
Override and restrict default system actions
–
Specify callback classes on task status
–
JSP-based forms for viewing and updating task details
–
Dynamic assignment functions
See Also:
■
"Participant Types in Workflow Services" on page 15-11
■
"Dynamic Assignment Functions" on page 15-111
Oracle BPEL Process Manager Workflow Services 15-3
Overview of Workflow Services
■
■
Built-in reports — Priority reports, productivity reports, cycle time reports, and
unattended tasks report
Participant types—consists of single approver, group vote, management chain,
sequential list of approvers, FYI assignees, and external routing services.
See Also:
■
"Participant Types in Workflow Services" on page 15-11
Identity service—interacts with back-end identity management systems to capture
all user information from Java AuthoriZatioN (JAZN) and LDAP. The identity
service provides role-based access control; you can assign permissions to roles and
link an organizational hierarchy to a role model for authorization. You can also do
the following:
–
Assign worklist privileges to users, roles, or groups
–
Maintain user properties such as name, location, phone, fax, and e-mail.
–
Capture organizational hierarchy (reporting structure) and group information
–
Integrate with standard (for example, LDAP-based) directory services for user
and role provisioning
See Also:
■
■
■
"Identity Service" on page 15-100 for identity service concepts
Oracle BPEL Process Manager Administrator’s Guide for identity
service configuration instructions
Notification service
–
Send notifications to specified users on specified task changes
–
Notifications through different delivery channels (e-mail, phone, fax, voice,
and SMS)
–
Ability to customize content of notifications for different types of tasks
–
Perform actions on tasks through e-mail
See Also:
■
■
■
■
"Notification Service" on page 15-106 for notification service
concepts
Chapter 14, "Oracle BPEL Process Manager Notification Service"
Oracle BPEL Process Manager Administrator’s Guide for notification
service configuration instructions
The Oracle BPEL Worklist Application
–
Out-of-the-box fully customizable worklist
–
Support for various user profiles – end user, supervisor, task owner, group
owner, administrator
–
View tasks based on user or role ability to perform authorized actions on tasks
in the worklist
–
Ability to filter tasks in worklist view based on various criteria
–
Ability to acquire and check out shared tasks
15-4 Oracle BPEL Process Manager Developer’s Guide
Overview of Workflow Services
–
Support for custom work queues
–
Define custom vacation rules and delegation rules
–
Provide access to selected worklist views to other users (proxy support)
–
Complete workflow history and audit trail
–
Out-of-the-box productivity reports
See Also:
Chapter 16, "Worklist Application"
Workflow Functionality: A Procurement Process Example
The functionality of workflow services can be illustrated using a simple order
approval business process to approve or reject an order, as shown in Figure 15–2.
requested items. Approval and rejection is a two-step process involving an initial
approver and the manager of the initial approver. The order is first assigned to the
Supervisor role. Once a user belonging to the Supervisor role approves the order, it is
sent to this user’s manager for final approval.
Figure 15–2 BPEL Workflow
Business Process
<receive>
Purchase List
<invoke>
Vendor Pricing
Service
<scope>
<invoke>
Assign Task via
Task Service
<receive>
Get Outcome via
Task Service
Approved
?
Rejected
<invoke>
Vendor Order
Service
<invoke>
Employee
Notification
Oracle BPEL Process Manager Workflow Services 15-5
Overview of Workflow Services
See Also: Oracle BPEL Process Manager Order Booking Tutorial for
instructions on designing an order approval business process to
approve or reject an order
Workflow Services Components
Figure 15–3 shows the following workflow services components:
■
Task Service
The task service provides task state management and persistence of tasks. In
addition to these services, the task service exposes operations to update a task,
complete a task, escalate and reassign tasks, and so on. The task service is used by
the Oracle BPEL Worklist Application to retrieve tasks assigned to users. This
service also determines if notifications are to be sent to users and groups when the
state of the task changes. The task service consists of the following services.
–
Task Routing Service
The task routing service offers services to route, escalate, and reassign the task.
The service makes these decisions by interpreting a declarative specification in
the form of the routing slip.
–
Task Query Service
The task query service queries tasks for a user based on a variety of search
criterion such as keyword, category, status, business process, attribute values,
history information of a task, and so on.
–
Task Metadata Service
The task metadata service exposes operations to retrieve metadata information
related to a task.
■
Identity Service
The identity service is a thin Web service layer on top of the Oracle Application
Server 10g security infrastructure or any custom user repository. It enables
authentication and authorization of users and the lookup of user properties, roles,
group memberships, and privileges.
■
Notification Service
The notification service delivers notifications with the specified content to the
specified user to any of the following channels: e-mail, telephone voice message,
pager, fax, and SMS. See "Notifications from Workflow Services" on page 15-79 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.
15-6 Oracle BPEL Process Manager Developer’s Guide
Overview of Workflow Services
Figure 15–3 Workflow Services Components
Workflow Services
User
Metadata
Service
Identity
Service
Portal
Users
BPEL
Process
Worklist
Task
Metadata
Service
Task
Query
Service
Task
Assignment
Service
Notification
Service
Task
Service
Identity
Management
· OID
· LDAP
· JAZN
E-mail Client
Database
Notification
Channels
· E-mail
· Application Server Wireless
- Voice
- SMS
- Fax
- Pager
Figure 15–4 shows the interactions between the services and the business process.
Oracle BPEL Process Manager Workflow Services 15-7
Use Cases for Workflow Services
Figure 15–4 Workflow Services and Business Process Interactions
Worklist application
Web application to search
for tasks, view tasks, and
act on tasks
Oracle BPEL Server
Task Service
Provides task persistence
and exposes operations
to update a task, complete
a task, escalate and
reassign tasks,
and so on
Task Query Service
Queries tasks for a user
based on keyword,
category, status,
business process,
attribute values,
task history information,
and so on
Task Assignment Service
Offers services to route,
escalate, and reassign
tasks
User Metadata Service
Manages metadata related
to workflow (user work
queues, preferences,
vacation, and delegation
rules)
Notification Service
Sends notifications to
users by e-mail, voice
message, pager, fax, or
short message service
Task Metadata Service
Exposes operations to
retrieve metadata
information related to
a task
Runtime Config Services
Provides methods for
managing metadata used
in the task service runtime
environment
Identity Service
· user / group / role lookup
· user authentication
· authorization
· organization hierarchy
User Directory
(one of)
Oracle
Internet
Directory
JAZN
XML
LDAP,
Custom
See Also: Oracle BPEL Process Manager Administrator’s Guide for
identity service details
Use Cases for Workflow Services
Using workflow services is demonstrated in the VacationRequest, AutoLoanDemo,
ExpenseRequestApproval, LoanDemoPlus, DocumentReview,
HelpDeskServiceRequest, and OrderApproval demos.
See Also:
■
"End-to-End Workflow Examples" on page 15-84
■
SOA_Oracle_Home\bpel\samples\demos
15-8 Oracle BPEL Process Manager Developer’s Guide
Use Cases for Workflow Services
The following sections describe multiple use cases for workflow services.
Assigning a Task to a User or Role
A vacation request process may start with getting the vacation details from a user and
then routing the request to their manager for approval. User details and the
organizational hierarchy can be looked up from a user directory or store. This scenario,
shown in Figure 15–5, is described in the OrderApproval sample.
Figure 15–5 Assigning Tasks to a User or Role from a Directory
BPEL
Process
Assign Task
Workflow
Services
Task Complete
OID
LDAP
Using the Various Participant Types
A task can be routed through multiple users with a group vote, management chain, or
sequential list of approvers participant type. For example, consider a loan request that
is part of the loan approval flow. The loan request may first be assigned to a loan agent
role. After a specific loan agent acquires and accepts the loan, the loan may be routed
further through multiple levels of management if the loan amount is greater that
$100,000. This scenario, shown in Figure 15–6, is described in the LoanDemoPlus
sample.
Figure 15–6 Flow Patterns and Routing Policies
Workflow Service
Get Approvals
BPEL
Process
Change Routing
All Approvals
Complete
Various
Routing
Patterns
See "Participant Types in Workflow Services" on page 15-11 for the various flow types
supported by workflow services. You can use these types as building blocks to create
complex workflows.
Oracle BPEL Process Manager Workflow Services 15-9
Use Cases for Workflow Services
Escalation, Expiration, and Delegation
A high-priority task can be assigned to a certain user or role based on the task type.
However, if the user does not act on it in a certain time, the task may expire and in
turn be escalated to the manager for further action. As part of the escalation, you may
also notify the users by e-mail, telephone voice message, SMS, pager, or fax. Similarly,
a manager may delegate tasks from one reportee to another to balance the load
between various task assignees. All tasks defined in BPEL have an associated
expiration date. Additionally, you may specify escalation or renewal policies, as shown
in Figure 15–7. For example, consider a support call, which is part of the
HelpDeskServiceRequest 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.
Figure 15–7 Escalation and Notification
Workflow Services
Escalate Task
1 2
BPEL
Process
Notify Manager
7
3
4 5
6
8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
Task Resolved
28 29 30
Calendar
Notification
Automatic Assignment and Delegation
A user may decide to have another user perform tasks on their behalf. Tasks can be
explicitly delegated from the Oracle BPEL Worklist Application or can be
automatically delegated. For example, a manager sets up a vacation rule saying that all
their high priority tasks are automatically routed to one of their reports while the
manager is on vacation. In some cases, tasks can be routed to different individuals
based on the content of the task. Another example of automatic routing is to allocate
tasks among multiple individuals belonging to a group. For example, a help desk
supervisor decides to allocate all tasks for the western region based on a round robin
basis or assign tasks to the individual with the lowest number of outstanding tasks
(the least busy).
Work Queues and Proxy Support
It is often required that one user be provided with access to part of another user’s
worklist. For example, an executive decides to provide access to expense approvals
within a certain limit to their secretary. Work queues allow you to create a custom view
to group a subset of tasks in the worklist (say high priority tasks, tasks due in 24
hours, expense approval tasks, and so on). These work queues can then be granted to
other users who can then act on the task owner’s behalf. For example, in the scenario
described above, the executive can create a delegated expense approvals work queue
for expenses below $5000.
The Oracle BPEL Worklist Application
Users typically access tasks assigned to them by using the Oracle BPEL Worklist
Application, as shown in Figure 15–8. A worklist consists of tasks assigned to the user
15-10 Oracle BPEL Process Manager Developer’s Guide
Participant Types in Workflow Services
as well as the groups to which they belong. A task may also include forms and
attachments in addition to other task details such as history, comments, and approval
sequence. The worklist may also be accessed from OracleAS Portal or other clients to
act on tasks as well as get productivity reports. The Oracle BPEL Worklist Application
can be customized and extended based on the specific needs of an application. See
Chapter 16, "Worklist Application" for details about worklist functionality and the
sample Oracle BPEL Worklist Application.
Figure 15–8 Oracle BPEL Worklist Application—Access Tasks, Forms, Attachments, and
Reports
Workflow Services
List Work Items
Complete Task
Get Weekly
Productivity
Report
Task Details
and History
Participant Types in Workflow Services
Oracle BPEL Process Manager provides a library of participant types (known in
previous releases as workflow patterns). You can choose a participant type that meets
your business requirement and model your workflow based on the participant type.
Oracle BPEL Process Manager supports the following participant types:
■
■
■
■
■
Single Approver — used 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. Based on the user's action, you define what the business process does.
Group Vote — used 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.
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.
Oracle BPEL Process Manager Workflow Services
15-11
Participant Types in Workflow Services
■
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.
Continuing Workflows from Other Workflows
You can have situations where you need to continue a previous workflow task in the
current workflow task. Oracle BPEL Process Manager enables you to include the task
history, comments, and attachments from the previous task. This provides you with a
complete end-to-end audit trail.
See Also: "Including the Task History of Other Human Tasks" on
page 15-58
15-12 Oracle BPEL Process Manager Developer’s Guide
Overview of the Modeling Process
Overview of the Modeling Process
The modeling process consists of creating a human task, associating it with a BPEL
process, and generating the format for displaying the human task during run time in
the Oracle BPEL Worklist Application. This section provides a brief overview of these
modeling tasks and provides references to specific modeling instructions.
■
Create a Human Task Definition with the Human Task Editor
■
Associate the Human Task Definition with a BPEL Process
■
Generate the Task Display Form
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: "Task 1: Creating the Human Task Definition with the
Human Task Editor" on page 15-14 for specific instructions
Associate the Human Task Definition with a BPEL Process
You 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.
See Also: "Task 2: Associating the Human Task with a BPEL
Process" on page 15-52 for specific instructions
Generate the Task Display Form
You generate the layout of the task display form used for displaying the task header,
body (task payload), and footer details at run time in Oracle BPEL Worklist
Application. The task display form defines the display mechanism for the task payload
(data in the task) in the Oracle BPEL Worklist Application. Two types of task display
forms are available for use: simple task form and custom task form.
See Also: "Task 3: Generating the Task Display Form" on page 15-65
for specific instructions
Oracle BPEL Process Manager Workflow Services
15-13
Task 1: Creating the Human Task Definition with the Human Task Editor
Task 1: Creating the 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.
When human task creation is complete, the following folder and file are created:
■
■
A folder with the human task name you specify in the Human Task Name field in
"Accessing the Human Task Editor" on page 15-14 is created under the Integration
Content folder of your BPEL process in the Application Navigator
The human task settings specified in the Human Task editor are saved to a
metadata task configuration file with a .task extension. This file is stored in the
human task name folder. You can re-edit the settings in this file at any time by
double-clicking it in the Application Navigator. This reopens the .task file in the
Human Task editor.
This section contains the following topics:
■
Accessing the Human Task Editor
■
Reviewing the Sections of the Human Task Editor
■
Specifying the Task Title, Priority, Outcome, and Owner
■
Specifying the Task Payload Data Structure
■
Assigning Task Participants
■
Escalating, Renewing, or Ending the Task
■
Specifying Participant Notification Preferences
■
Specifying Advanced Settings
■
Exiting the Human Task Editor and Saving Your Changes
Accessing the Human Task Editor
When you are ready to begin creation of a human task, the Human Task editor can be
accessed in several ways in Oracle JDeveloper:
■
From the Application Navigator
■
From the Component Palette
From the Application Navigator
This method enables you to create a human task that you can later associate with a
BPEL process through use of a human task activity.
1.
Right-click your BPEL process in the Application Navigator and select Create
Human Task Definition.
The Add a Human Task window appears.
2.
Enter a name in the Human Task Name field.
The name you enter is added to the directory path in the Location field.
SOA_Oracle_Home/jdev/mywork/my_application/my_process/bpel/Human_task_
directory/Human_task_name.task
3.
Click OK.
15-14 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
The Human Task editor appears.
4.
Go to section "Reviewing the Sections of the Human Task Editor" on page 15-15.
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 Integration Tier > Human Tasks > Human Task Definition.
Note:
From the Component Palette
This method enables you to create a human task activity with which you immediately
associate a BPEL process through use of a human task activity.
1.
Select Process Activities from the Component Palette.
2.
Drag and drop a Human Task activity into your BPEL process.
The Add a Human Task window appears.
3.
Click the second icon to the right of the Task Definition field.
4.
Enter a name in the Human Task Name field.
The name you enter is added to the directory path in the Location field.
SOA_Oracle_Home/jdev/mywork/my_application/my_process/bpel/Human_task_
directory/Human_task_name.task
5.
Click OK.
The Human Task editor appears.
6.
Go to section "Reviewing the Sections of the Human Task Editor" on page 15-15.
Reviewing the Sections of the Human Task Editor
The Human Task editor consists of the following main sections shown in Figure 15–9.
These sections enable you to create a human task.
Oracle BPEL Process Manager Workflow Services
15-15
Task 1: Creating the Human Task Definition with the Human Task Editor
Figure 15–9 Human Task Editor
Instructions for using these main sections of the Human Task editor to create a
workflow task are listed in Table 15–1.
Table 15–1
Human Task Editor
For This Main Section...
See...
Task Configuration
"Specifying the Task Title, Priority, Outcome, and
Owner" on page 15-16
(title, outcomes, priority, and owner)
Parameters
"Specifying the Task Payload Data Structure" on
page 15-21
Assignment and Routing Policy
"Assigning Task Participants" on page 15-22
Expiration and Escalation Policy
"Escalating, Renewing, or Ending the Task" on
page 15-38
Notification Settings
"Specifying Participant Notification Preferences" on
page 15-42
Advanced Settings
"Specifying Advanced Settings" on page 15-46
(for specifying custom escalation
rules, custom style sheets for
attachments, multilingual settings,
custom task actions, error messages,
and callback classes)
Specifying the Task Title, Priority, Outcome, and Owner
Figure 15–10 shows the Task Configuration section of the Human Task editor.
This section enables you to specify details such as the task title, task priority, task
outcomes, and task owner.
15-16 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
Figure 15–10
Human Task Editor — Task Configuration Section
Instructions for configuring the following subsections of the Task Configuration
section are listed in Table 15–2:
Table 15–2
Human Task Editor — Task Configuration Section
For This Subsection...
See...
Title
"Specifying a Task Title and Priority" on page 15-17
Priority
Outcomes
"Specifying a Task Outcome" on page 15-17
Owner
"Specifying a Task Owner" on page 15-18
Specifying a Task Title and Priority
1.
Enter the following details.
Field
Description
Title
Enter an optional task title. The task title displays in the Oracle BPEL
Worklist Application. If you enter a title in the Task Title field of the
General tab of the Human Task window described in "Specifying the
Task Title" on page 15-54, 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 BPEL Worklist Application. This
priority value is overridden by any priority value you select in the
General tab of the Add a Human Task window.
See Also: "Specifying the Task Initiator and Task Priority" on
page 15-54 for instructions on specifying a priority value in the Add a
Human Task window
Specifying a Task Outcome
Task outcomes capture the possible outcomes of a task. The Oracle BPEL Worklist
Application displays the outcomes you specify here as the possible actions to perform
during run time. You can specify the following types of task outcomes:
■
Select a seeded outcome
■
Enter a custom outcome
The task outcomes can also have run time display values that are different from the
actual outcome value specified here. This permits outcomes to be displayed in a
different language in the Oracle BPEL Worklist Application. See "Specifying
Multilingual Settings" on page 15-47 for more information about internationalization.
1.
Click the flashlight icon to the right of the Outcomes field.
The Outcomes window displays the possible outcomes for tasks. APPROVE and
REJECT are selected by default.
Oracle BPEL Process Manager Workflow Services
15-17
Task 1: Creating the Human Task Definition with the Human Task Editor
2.
Select additional task outcomes or deselect the default outcomes.
3.
Enter any custom outcomes separated by commas in the Custom Outcomes field.
4.
Click OK to return to the Human Task editor.
Your selections display in the Outcomes field.
The seeded and custom outcomes selected here display for selection in the
Majority Voted Outcome section of the group vote participant type.
See Also:
"Specifying Group Voting Details" on page 15-28
Specifying a Task Owner
The task owner can view the tasks belonging to business processes they own and
perform operations on behalf of any of the assigned task participant types.
Additionally, the owner can also reassign, withdraw, or escalate tasks. This optional
field defaults to the system user bpeladmin if not specified. The task owner can also
be specified in the Advanced tab of the Human Task window described in "Specifying
a Task Owner" on page 15-57. The task owner specified in the Advanced tab overrides
any task owner you enter here.
1.
Select a method for specifying the task owner:
■
Specifying a Task Owner By Browsing the User Directory
■
Specifying a Task Owner Dynamically
Specifying a Task Owner By Browsing the User Directory
Task owners can be selected by browsing the user directory (Oracle Internet Directory
(OID), JAZN/XML, LDAP, and so on) that is configured for use with Oracle BPEL
Process Manager.
1.
Click the first icon to the right of the Owner field to display the Identity lookup
dialog.
2.
Search for the owner by entering a search string such as jcooper, j*, *, and
so on. Clicking Lookup fetches all the users that match the search criteria.
15-18 Oracle BPEL Process Manager Developer’s Guide
Task 1: 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.
Oracle BPEL Process Manager Workflow Services
15-19
Task 1: Creating the Human Task Definition with the Human Task Editor
4.
View the details of a user or group by highlighting the user or group and clicking
Detail.
5.
Click OK to return to the Identity lookup dialog.
6.
Click Select to add the user to the Selected user section.
7.
Click OK to return to the Human Task editor.
Your selection displays in the Owner field.
Specifying a Task Owner Dynamically
Task owners can be selected dynamically in the Expression Builder window.
1.
Click the second icon to the right of the Owner field to display the Expression
Builder window:
15-20 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
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.
See Also:
■
■
Click Help for instructions on using the Expression Builder
window and XPath Building Assistant
"Workflow Service and Identity Service Related XPath Extension
Functions" on page 15-119 and Appendix D, "XPath Extension
Functions" for information about workflow service dynamic
assignment functions and identity service functions
Specifying the Task Payload Data Structure
Figure 15–11 shows the Parameters section of the Human Task editor.
This section enables you to define the structure (message attributes) of the task
payload (the data in the task). Task payload data consists of one or more elements or
types. Based on your selections, an XML schema definition is created for the task
payload.
Figure 15–11
Human Task Editor — Parameters Section
1.
Click the + sign to display the Add Task Parameter window.
2.
Enter the following details:
Field
Description
Parameter Type
Select Type or Element and click the flashlight 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.
Oracle BPEL Process Manager Workflow Services
15-21
Task 1: Creating the Human Task Definition with the Human Task Editor
Field
Description
Modifiable via worklist Select this check box to enable users to edit task payload data in the
footer of the Oracle BPEL Worklist Application. For example, the
approver in the application may need to add approver comments.
You can only define payload flex field mappings in the Oracle
BPEL Worklist Application for payload parameters that are simple
XML types.
Note:
3.
Click OK to return to the Human Task editor.
Your selection displays in the Parameters section.
4.
If you want to edit your selection, highlight it and click the first icon in the upper
right part of the Parameters section.
Assigning Task Participants
Figure 15–12 shows the Assignment and Routing Policy section of the Human Task
editor.
This section enables you to select a participant type that meets your business
requirement. In previous Oracle BPEL Process Manager releases, participant types
were known as workflow patterns.
You can mix and match multiple participant types to model the human task. This
enables you to extend the functionality of a previously configured human task to
model more complex workflows.
Each of the participant types has an associated editor that you use for configuration
tasks. The sequence in which the assignees are added indicates the execution
sequence.
Figure 15–12 Human Task Editor — Assignment and Routing Policy Section
1.
Click the + sign to display the Add Participant Type window.
This enables you to select a specific participant type.
2.
Select a participant type from the Type list.
15-22 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
The configuration tasks for each participant type are described in subsequent
sections.
3.
See the following section based on your selection:
For This Subsection... See...
Add Participant Type
■
Single Approver
"Configuring the Single Approver Participant Type" on page 15-23
■
Group vote
"Configuring the Group Vote Participant Type" on page 15-26
■
Management chain "Configuring the Management Chain Participant Type" on page 15-29
■
■
■
4.
Sequential list of
approvers
"Configuring the Sequential List of Approvers Participant Type" on
page 15-31
FYI assignee
"Configuring the FYI Assignee Participant Type" on page 15-34
External routing
service
"Configuring the External Routing Service Participant Type" on
page 15-35
See the following task assignment and routing policy sections shown in
Figure 15–12 after you have configured a participant type. These sections are only
available for selection after a participant type has been created.
For This Subsection... See...
Allow all participants
to invite other
participants
"Allowing All Participants to Invite Other Participants" on page 15-36
Enable abrupt
completion condition
"Abruptly Completing a Condition" on page 15-37
Configuring the Single Approver Participant Type
Figure 15–13 displays the Single Approver window.
This participant type requires 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. Based on the user's action, you define what the business process does.
For example, a vacation request is assigned to a manager. The manager must act on the
request task three days before the vacation starts. If the manager formally approves or
rejects the request, the employee is notified with the decision. If the manager does not
act on the task, the request is treated as rejected. Notification actions similar to the
formal rejection are taken.
Oracle BPEL Process Manager Workflow Services
15-23
Task 1: Creating the Human Task Definition with the Human Task Editor
Figure 15–13 Add Participant Type — Single Approver
1.
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (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 15–3:
Table 15–3
Add Participant Type — Single Approver
For This Subsection...
See...
Requires action from one of the
participants below
"Assigning Participants to the Single Approver Task" on
page 15-24
Specify skip rule
"Bypassing a Task Participant" on page 15-25
Limit allocated duration to
"Specifying a Time Limit for Acting on a Task" on
page 15-25
Allow this participant to invite
other participants
"Inviting Additional Participants to a Task" on
page 15-25
Assigning Participants to the Single Approver Task
1.
Select a method for assigning a user or group to participate in performing actions
on this task.
■
By name
Enter a user or group name or click the first icon (flashlight) 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
15-24 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
lookup of user properties, roles, group memberships, and privileges. User
information is obtained from Java AuthoriZatioN (JAZN) or an LDAP server
such as Oracle Internet Directory. You can use wild cards (*) to search for IDs.
■
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 BPEL Worklist Application during run
time.
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.
Bypassing a Task Participant
1.
Select the Specify skip rule check box if you want the user or group to be
bypassed if a specific condition is satisfied. This action displays an icon for
accessing the Expression Builder window for building a condition. For example, if
a user submits a business trip expense report that is below a specific amount, no
approval is required by their manager.
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.
Specifying a Time Limit for Acting on a Task
1.
Click the + sign to expand the Advanced section shown in Figure 15–13.
2.
Select Limit allocated duration to.
3.
Specify the amount of time a user or group receives to act on a task. If the user or
group does not act in the time specified, the global escalation and renewal policies
that you set in the Expiration and Escalation Policy section (known as the routing
slip level) of the Human Task editor are applied. For example, if the global policy
is set to escalate the task and this participant does not act in the duration provided,
the task is escalated to the manager or another user, as appropriate.
"Escalating, Renewing, or Ending the Task" on page 15-38
for instructions on setting the global escalation and renewal policies in
the Expiration and Escalation Policy section of the Human Task
editor
See Also:
Inviting Additional Participants to a Task
1.
Click the + sign to expand the Advanced section (if not already expanded).
Oracle BPEL Process Manager Workflow Services
15-25
Task 1: Creating the Human Task Definition with the Human Task Editor
2.
Select the Allow this participant to invite other participants check box if you
want this task assignee to invite other participants into the workflow before
routing it to the next assignee in this workflow. For example, assume the approval
workflow goes from James Cooper to John Steinbeck. If this option is checked,
James Cooper can decide to first route it to Irving Stone before it goes to John
Steinbeck.
Configuring the Group Vote Participant Type
Figure 15–14 displays the Group Vote window.
This participant type is used 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.
For example, a business process collects the feedback from all interviewers in the
hiring process, consolidates it, and assigns a hire or reject request to each of the
interviewers. At the end, the candidate is hired if the majority of interviewers vote for
hiring instead of rejecting.
Figure 15–14 Add Participant Type — Group Vote
1.
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (for example, Approval Manager, Primary
Reviewers, and so on).
15-26 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
Instructions for configuring the following subsections of the Add Participant Type
- Group Vote window are listed in Table 15–4:
Table 15–4
Add Participant Type — Group Vote Window
For This Subsection...
See...
Required consensus between the
participants below: 50
"Assigning Participants to the Group Vote Task" on
page 15-27
Specify skip rule
"Bypassing a Task Participant" on page 15-27
Share attachments and comments
"Sharing Attachments and Comments with Task
Participants" on page 15-28
Default Outcome
"Specifying Group Voting Details" on page 15-28
Consensus Percentage
Immediately trigger voted outcome
when minimum percentage is met
Wait until all votes are in before
triggering outcome
Limit allocated duration to
"Specifying a Time Limit for Acting on a Task" on
page 15-28
Assigning Participants to the Group Vote Task
1.
Select a method for assigning a user or group to participate in this task. The
assigned participants must establish a consensus on when a task is considered
complete.
■
By name
Enter a user or group name or click the first icon (flashlight) 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 Java AuthoriZatioN (JAZN) or an LDAP server
such as Oracle Internet Directory. You can use wild cards (*) to search for IDs.
■
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 BPEL Worklist Application during run
time.
"Assigning Participants to the Single Approver Task" on
page 15-24 for rules to follow when specifying assignees with XPath
expressions
See Also:
Bypassing a Task Participant
1.
Select the Specify skip rule check box if you want the user or group to be
bypassed if a specific condition is satisfied. This action displays an icon for
accessing the Expression Builder window for building a condition. For example, if
a user submits a business trip expense report that is below a specific amount, no
approval is required by their manager. The expression must evaluate to a Boolean
value.
Oracle BPEL Process Manager Workflow Services
15-27
Task 1: Creating the Human Task Definition with the Human Task Editor
See Also: "Bypassing a Task Participant" on page 15-25 for an
example of a valid XPath expression for skipping a participant
Sharing Attachments and Comments with Task Participants
1.
Select the Share attachments and comments check box if you want all group
voters or workflow participants to share comments and attachments for this task.
This information typically displays in the footer region of the Oracle BPEL
Worklist Application.
Specifying Group Voting Details
1.
Specify a method for selecting the outcome for the final task. If you select By
Expression from the lists below, you can dynamically specify the details by
clicking the icon to the right of the field to display the Expression Builder window.
■
Default Outcome
Select the default outcome for this task to take effect if the consensus
percentage value is not satisfied. This happens if there is a tie or if all
participants do not respond before the task expires. Seeded and custom
outcomes that you entered in the Outcomes window in "Specifying a Task
Outcome" on page 15-17 display in this list.
■
Consensus Percentage
Select a percentage value required for the outcome of this task to take effect;
for example, a majority vote (51) or a unanimous vote (100). For example,
assume there are two possible outcomes (ACCEPT and REJECT) and five
subtasks. If two subtasks are accepted and three are rejected, and the required
acceptance percentage is 50%, the outcome of the task is rejected.
2.
Specify additional group voting details:
■
Immediately trigger voted outcome when minimum percentage is met
If selected, the outcome of the task can be computed early with the outcomes
of the completed subtasks, enabling the pending subtasks to be withdrawn.
For example, assume four users are assigned to act on a task, the default
outcome is APPROVE, and the consensus 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.
■
Wait until all votes are in before triggering outcome
If selected, the workflow waits for all responses before an outcome is initiated.
Specifying a Time Limit for Acting on a Task
1.
Click the + sign to expand the Advanced section shown in Figure 15–14.
2.
Select Limit allocated duration to.
3.
Specify the amount of time a user or group receives to act on a task. If the user or
group does not act in the time specified, the global escalation and renewal policies
that you set in the Expiration and Escalation Policy section (known as the routing
slip level) of the Human Task editor are applied. For example, if the global policy
is set to escalate the task and this participant does not act in the duration provided,
the task is escalated to the manager or another user, as appropriate.
15-28 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
"Escalating, Renewing, or Ending the Task" on page 15-38
for instructions on setting the global escalation and renewal policies in
the Expiration and Escalation Policy section of the Human Task
editor
See Also:
Configuring the Management Chain Participant Type
Figure 15–15 displays the Management Chain window.
This participant type routes 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.
For example, a purchase order is assigned to a manager. If the manager approves the
order, it is assigned to their manager. If that manager approves it, it is assigned to their
manager, and so on until three managers approve the order. If any of the managers
reject the request or the request expires, the order is rejected.
Figure 15–15
1.
Add Participant Type — Management Chain
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (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 15–5:
Oracle BPEL Process Manager Workflow Services
15-29
Task 1: Creating the Human Task Definition with the Human Task Editor
Table 15–5
Add Participant Type - Management Chain
For This Subsection...
See...
Requires management chain
approval of one of the participants
below
"Assigning Participants to the Management Chain Task"
on page 15-30
Specify skip rule
"Bypassing a Task Participant" on page 15-30
Maximum Number of Chain Levels "Specifying the Number of Approvers" on page 15-30
Up
Highest Title of Approver
Limit allocated duration to
"Specifying a Time Limit for Acting on a Task" on
page 15-31
Allow this participant to invite
other participants
"Inviting Additional Participants to a Task" on
page 15-31
Assigning Participants to the Management Chain Task
1.
Select a method for assigning a user or group to participate in this task.
■
By name
Enter a user or group name or click the first icon (flashlight) 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 Java AuthoriZatioN (JAZN) or an LDAP server
such as Oracle Internet Directory. You can use wild cards (*) to search for IDs.
■
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 BPEL Worklist Application during run
time.
"Assigning Participants to the Single Approver Task" on
page 15-24 for rules to follow when specifying assignees with XPath
expressions
See Also:
Bypassing a Task Participant
1.
Select the Specify skip rule check box if you want the user or group to be
bypassed if a specific condition is satisfied. This action displays an icon for
accessing the Expression Builder window for building a condition. For example, if
a user submits a business trip expense report that is below a specific amount, no
approval is required by their manager. The expression must evaluate to a Boolean
value.
See Also: "Bypassing a Task Participant" on page 15-25 for an
example of a valid XPath expression for skipping a participant
Specifying the Number of Approvers
15-30 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
1.
Specify the following task routing parameters. When both parameters are
specified, task routing is determined by both parameters. The routing continues
until one of these parameters is satisfied. If you select By Expression from the lists
below, you can dynamically specify the details by clicking the icon to the right of
the field to display the Expression Builder window.
■
Maximum Number of Chain Levels Up
Enter a value for the number of levels in the management chain to include in
this task. For example, if set to 2 and the task is initially assigned to user
jcooper, both the user jstein (manager of jcooper) and the user wfaulk
(manager of jstein) are included in the list (apart from jcooper, the initial
assignee). This is a mandatory field.
■
Highest Title of Approver
Select the title of the last (highest) user in the management chain. The title is
retrieved from the identity service.
Specifying a Time Limit for Acting on a Task
1.
Click the + sign to expand the Advanced section shown in Figure 15–15.
2.
Select Limit allocated duration to.
3.
Specify the amount of time a user or group receives to act on a task. If the user or
group does not act in the time specified, the global escalation and renewal policies
that you set in the Expiration and Escalation Policy section (known as the routing
slip level) of the Human Task editor are applied. For example, if the global policy
is set to escalate the task and this participant does not act in the duration provided,
the task is escalated to the manager or another user, as appropriate.
"Escalating, Renewing, or Ending the Task" on page 15-38
for instructions on setting the global escalation and renewal policies in
the Expiration and Escalation Policy section of the Human Task
editor
See Also:
Inviting Additional Participants to a Task
1.
Click the + sign to expand the Advanced section (if not already expanded).
2.
Select Allow this participant to invite other participants if you want this task
assignee to invite other participants into the workflow before routing it to the next
assignee in this workflow. For example, assume the approval workflow goes from
James Cooper to John Steinbeck. If this option is checked, James Cooper can
decide to first route it to Irving Stone before it goes to John Steinbeck.
Note: For the management chain participant type, the additional
participants can be invited only by the last user in the management
chain.
Configuring the Sequential List of Approvers Participant Type
Figure 15–16 displays the Sequential List of Approvers window.
This enables you to create a list of sequential participants for a workflow. For example,
if you want a document to be reviewed by John, Mary, and Scott in sequence, use this
participant type. This is similar to the management chain participant type, except that
Oracle BPEL Process Manager Workflow Services
15-31
Task 1: Creating the Human Task Definition with the Human Task Editor
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.
Figure 15–16 Add Participant Type — Sequential List of Approvers
1.
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (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 15–6.
Table 15–6
Add Participant Type — Sequential List of Approvers
For This Subsection...
See...
Requires sequential approval of all
participants below
"Assigning Participants to the Sequential List of
Approvers Task" on page 15-32
Specify skip rule
"Bypassing a Task Participant" on page 15-33
Limit allocated duration to
"Specifying a Time Limit for Acting on a Task" on
page 15-33
Allow this participant to invite
other participants
"Inviting Additional Participants to a Task" on
page 15-33
Assigning Participants to the Sequential List of Approvers Task
1.
Select a method for assigning a user or group to participate in this task.
■
By name
15-32 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
Enter a user or group name or click the first icon (flashlight) 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 Java AuthoriZatioN (JAZN) or an LDAP server
such as Oracle Internet Directory. You can use wild cards (*) to search for IDs.
■
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 BPEL Worklist Application during run
time.
"Assigning Participants to the Single Approver Task" on
page 15-24 for rules to follow when specifying assignees with XPath
expressions
See Also:
Bypassing a Task Participant
1.
Select the Specify skip rule check box if you want the user or group to be
bypassed if a specific condition is satisfied. This action displays an icon for
accessing the Expression Builder window for building a condition. For example, if
a user submits a business trip expense report that is below a specific amount, no
approval is required by their manager. The expression must evaluate to a Boolean
value.
See Also: "Bypassing a Task Participant" on page 15-25 for an
example of a valid XPath expression for skipping a participant
Specifying a Time Limit for Acting on a Task
1.
Click the + sign to expand the Advanced section shown in Figure 15–16.
2.
Click Limit allocated duration to.
3.
Specify the amount of time a user or group receives to act on a task. If the user or
group does not act in the time specified, the global escalation and renewal policies
that you set in the Expiration and Escalation Policy section (known as the routing
slip level) of the Human Task editor are applied. For example, if the global policy
is set to escalate the task and this participant does not act in the duration provided,
the task is escalated to the manager or another user, as appropriate.
"Escalating, Renewing, or Ending the Task" on page 15-38
for instructions on setting the global escalation and renewal policies in
the Expiration and Escalation Policy section of the Human Task
editor
See Also:
Inviting Additional Participants to a Task
1.
Click the + sign to expand the Advanced section (if not already expanded).
2.
Select Allow this participant to invite other participants if you want this task
assignee to invite other participants into the workflow before routing it to the next
assignee in this workflow. For example, assume the approval workflow goes from
Oracle BPEL Process Manager Workflow Services
15-33
Task 1: Creating the Human Task Definition with the Human Task Editor
James Cooper to John Steinbeck. If this option is checked, James Cooper can
decide to first route it to Irving Stone before it goes to John Steinbeck.
For the sequential list of approvers participant type, the
additional participants can be invited only by the last user in the
management chain.
Note:
Configuring the FYI Assignee Participant Type
Figure 15–17 displays the FYI Assignee window.
This participant type is 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.
For example, a magazine subscription is due for renewal. If the user does not cancel
the current subscription before the expiration date, the subscription is renewed. This
user is reminded weekly until the request expires or the user acts on it.
Figure 15–17 Add Participant Type — FYI Assignee
1.
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (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 15–7:
Table 15–7
Add Participant Type - FYI Assignee
For This Subsection...
See...
Send an FYI copy of this task to all
participants below
"Assigning Participants to the FYI Assignee Task" on
page 15-34
Share attachments and comments
"Sharing Attachments and Comments with Task
Participants" on page 15-35
Assigning Participants to the FYI Assignee Task
15-34 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
1.
Select a method for assigning a user or group to participate in this task.
■
By name
Enter a user or group name or click the first icon (flashlight) 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 Java AuthoriZatioN (JAZN) or an LDAP server
such as Oracle Internet Directory. You can use wild cards (*) to search for IDs.
■
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 BPEL Worklist Application during run
time.
"Assigning Participants to the Single Approver Task" on
page 15-24 for rules to follow when specifying assignees with XPath
expressions
See Also:
Sharing Attachments and Comments with Task Participants
1.
Select the Share attachments and comments check box if you want all group
voters or workflow participants to share comments and attachments for this task.
This information typically displays in the footer region of the Oracle BPEL
Worklist Application.
Configuring the External Routing Service Participant Type
Figure 15–18 displays the External Routing Service window.
This participant type enables you 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.
Oracle BPEL Process Manager Workflow Services
15-35
Task 1: Creating the Human Task Definition with the Human Task Editor
Figure 15–18 Add Participant Type — External Routing Service
1.
Enter a recognizable label for this participant in the Label field. This label must be
unique within this workflow (for example, Approval Manager, Primary
Reviewers, and so on).
Specifying a Class Name
1.
Enter the fully qualified class file name or click the flashlight icon to select the
name (for example, the org.mycompany.tasks.RoutingService class name).
This class must implement the
oracle.bpel.services.workflow.task.IAssignmentService interface.
2.
Click the + sign to add name and pair value parameters that can be passed to the
external service.
See Also: "Dynamically Assigning Task Participants with the
Assignment Service" on page 15-116 for details about using this
interface
Allowing All Participants to Invite Other Participants
After you configure a participant type and are returned to the Human Task editor, the
Allow all participants to invite other participants check box is enabled, as shown in
Figure 15–19.
Figure 15–19 Human Task Editor — Assignment and Routing Policy Section
15-36 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
This check box is the equivalent of the Adhoc workflow pattern of previous BPEL
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.
Abruptly Completing a Condition
After you configure a participant type and are returned to the Human Task editor, the
Enable abrupt completion condition check box is enabled, as shown in Figure 15–19.
1.
If you want to specify conditions under which to complete the task early,
regardless of the other participants in the workflow, select the Enable abrupt
completion condition check box.
The Abrupt Completion Details window appears.
For example, assume an expense report goes to the manager, and then the director.
If the first participant (manager) rejects it, you can end the workflow without
sending it to the next participant (director).
There are two methods for specifying the abrupt completion of a task:
■
Outcomes
■
XPath expression routing condition
If outcomes are specified, any time the selected task outcome occurs, the task
completes. If both outcome and routing condition are specified, the workflow
service performs a logical OR on the two.
2.
Select appropriate outcomes and click the > button. To select all, click the >>
button.
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.
Oracle BPEL Process Manager Workflow Services
15-37
Task 1: Creating the Human Task Definition with 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 Enable abrupt completion condition check box to
edit this information.
Escalating, Renewing, or Ending the Task
Figure 15–20 shows the Expiration and Escalation Policy section of the Human Task
editor.
You can specify expiration duration of a task in this global policy section (also known
as the routing slip level). If expiration duration is specified at the routing slip level
instead of at the participant type level, then this duration is the expiration duration of
the task across all the participants. However, if you specify expiration duration at the
participant type level (through the Limit allocated duration to field), then those
settings take precedence over settings specified in the Expiration and Escalation
Policy section (routing slip level).
Figure 15–20 Human Task Editor — Expiration and Escalation Policy Section
Overview or Escalation and Expiration Policy
This section provides an overview of how specifying the expiration duration at this
level makes this setting the expiration duration of the task across all the participants.
For example, participant LoanAgentGroup and participant Supervisor have 3 days to
act on the task between them, as shown in Figure 15–21:
Figure 15–21 Expire After Policy
If there is no expiration specified at either the participant level or this routing slip
level, then that task has no expiration duration.
15-38 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
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:
*
The expiration duration is the same as the expiration duration of the
parallel participant if it has an expiration duration specified.
*
The expiration duration that is left on the task if it was specified at the
routing slip level.
*
No expiration duration, otherwise.
If parallel participants are specified as routing slips, then the expiration
duration for the parallel participants are determined by the routing slip.
When the parent task expires in a parallel task, the subtasks
are withdrawn if those tasks have not expired or completed.
Note:
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>
<participant name="Loan Agent 1" expirationDuration="PT2D">
<resource isGroup="true" type="STATIC">jcooper</resource>
</participant>
<participant name="Loan Agent 2">
<resource isGroup="true" type="STATIC">jstein</resource>
</participant>
<managementChain name="Loan Approval Chain"
Oracle BPEL Process Manager Workflow Services
15-39
Task 1: Creating the Human Task Definition with the Human Task Editor
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 15–8 demonstrates the expiration policy. Note that the management chain in the
above example evaluates to two users — wfaulk and cdickens (manager of
wfaulk).
Table 15–8
Expiration Policy
Participant
Expiration
Actual Time Taken to
Approve
Loan Agent 1 – jcooper
2 days (participant level)
One day
Loan Agent 2 – jstein
9 days (10 – 1 days) (global
level)
One day
Loan Approval Chain –
wfaulk (first user in chain)
2 days (participant level)
One day
Loan Approval Chain –
cdickens (second user in
chain)
2 days (participant level)
One day
Reviewer - sfitzger
6 days (10 – 4 days) (global
level)
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.
Never Expire Policy
1.
If you never want the task to expire, select Never Expire from the list shown in
Figure 15–20 on page 15-38.
Expire After Policy
1.
If you want the task to expire, select Expire after from the list shown in
Figure 15–20 on page 15-38.
2.
Specify the maximum time period for the task to remain open.
When the task expires, either the escalation policy or the renewal policy at the
routing slip level is applied. If neither is specified, the task expires. The expiration
policy at the routing slip level is common to all the participants.
The expiration policy for parallel participants is interpreted as follows.
■
If parallel participants are specified as resources in parallel elements, there is
no expiration policy for each of those participants.
15-40 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
■
If parallel participants are specified as routing slips, then the expiration policy
for the routing slip applies to the parallel participants.
Figure 15–22 indicates that the task expires in 3 days.
Figure 15–22
Expire After Policy
Renew After Policy
1.
If you want to extend the expiration period when the user does not respond
within the allotted time, select Renew after from the list shown in Figure 15–20 on
page 15-38.
2.
Specify the maximum number of times to continue renewing this task.
The renewal policy specifies the number of times the task can be renewed on
expiration and the renewal duration. In Figure 15–23, when the task expires, it is
renewed at most 3 times. It does not matter if the task expired at the
LoanAgentGroup participant or the Supervisor participant.
Figure 15–23
Renew After Policy
Oracle BPEL Process Manager Workflow Services
15-41
Task 1: Creating the Human Task Definition with the Human Task Editor
Escalate After Policy
1.
If you want to escalate the task (for example, to the user’s manager) if the user
does not respond within the allotted time, select Escalate after from the list shown
in Figure 15–20 on page 15-38.
2.
Specify the following additional values:
■
Maximum Escalation Levels
Number of management levels to which to escalate the task
■
Highest Approver Title
The title of the highest approver (for example, self, manager, director, or CEO).
The escalation policy specifies the number of times the task can be escalated on
expiration and the renewal duration. In Figure 15–24, when the task expires, it is
escalated at most 3 times. It does not matter if the task expired at the
LoanAgentGroup participant or the Supervisor participant.
Figure 15–24 Escalate After Policy
Specifying Participant Notification Preferences
Figure 15–25 shows the Notification Settings section of the Human Task editor (when
fully expanded).
Notifications indicate when a user is assigned a task or informed that the status of the
task has changed. Notifications can be sent through e-mail, voice message, fax, pager,
or SMS. Notifications are sent to different types of participants for different actions.
Notifications are configured by default with default messages. For example, a
notification message is sent to indicate that a task has completed and closed. You can
create your own or modify existing configurations.
15-42 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
Figure 15–25
1.
Human Task Editor — Notification Settings Section
Click the + sign to expand the Notification Settings section (displays as shown in
Figure 15–25).
Instructions for configuring the following subsections of the Notification Settings
section are listed in Table 15–9.
Table 15–9
Human Task Editor — Notification Settings Section
For This Subsection...
See...
Task Status
"Notifying Recipients of Changes to Task Status" on
page 15-43
Recipient
Notification Header
"Editing the Notification Message" on page 15-44
Reminders
"Setting Up Reminders" on page 15-44
Make notifications secure (exclude
details)
"Securing Notifications, Making Messages Actionable,
and Sending Attachments" on page 15-45
Make e-mail messages actionable
Send task attachments with email
notifications
See Also:
"Notifications from Workflow Services" on page 15-79
Notifying Recipients of Changes to Task Status
Three default status types display in the Task Status column: Assign, Complete, and
Error. You can select other status types for which to receive notification messages.
1.
Click a type in the Task Status column to display the complete list of task types:
■
Assign—when the task is assigned to users or a group. This action captures
the following actions:
–
Task is assigned to a user
–
Task is assigned to a new user in a sequential list of approvers workflow
–
Task is renewed
–
Task is delegated
–
Task is reassigned
–
Task is escalated
Oracle BPEL Process Manager Workflow Services
15-43
Task 1: Creating the Human Task Definition with the Human Task Editor
–
2.
Information for a task is submitted
■
Complete
■
Error
■
Expire
■
Request Info
■
Update Outcome
■
Suspend
■
Withdraw
Select a task status type.
Notifications can be sent to users involved in the task in various capacities. This
includes when the task is assigned to a group, each user in the group is sent a
notification if there is no notification endpoint available for the group.
3.
Click an entry in the Recipient column to display a list of possible recipients for
the notification message.
■
Assignees—the users or groups to whom the task is currently assigned
■
Initiator—the user who created the task
■
■
Approvers—the users who have approved the task so far. This applies in a
sequential list of approvers participant type where multiple users have
approved the task and a notification must be sent to all of them.
Owner—the task owner
See Also:
"Configuring the Notification Channel" on page 15-79
Editing the Notification Message
A default notification message is available for delivery to the selected recipient. If you
want, you can modify the default message text.
1.
Click the icon in the Notification Header column to modify the default
notification message.
The Edit Notification Message window appears.
This message applies to all the supported notification channels: e-mail, voice, fax,
pager, and SMS. E-mail and fax messages can also include the worklist task detail
15-44 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
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.
See Also: "Notifications from Workflow Services" on page 15-79 for
notification preference details
Setting Up Reminders
You can send task reminders, which can be based on the time the task was assigned to
a user or the expiration time of a task. The number of reminders and the interval
between the reminders can also be configured.
1.
Select the number of reminders to send from the Remind list.
2.
If you selected to remind the assignee one, two, or three times, select the interval
between reminders, and whether to send the reminder before or after the
assignment.
See Also:
"Sending Reminders" on page 15-83
Securing Notifications, Making Messages Actionable, and Sending Attachments
You can perform additional notification tasks in this section.
1.
Select the corresponding check box for functionality you want to use.
Field
Value
Make notifications secure (exclude
details)
Select to make the notification message secure. If
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: "Sending Secure Notifications" on
page 15-83
Make e-mail messages actionable
Select to make e-mail notifications actionable. This
enables you to perform task actions through e-mail.
See Also: "Sending Actionable E-mails" on
page 15-81 for additional configuration details
Send task attachments with e-mail
notifications
Select to send task attachments with the notification
message.
See Also: "Sending Inbound and Outbound
Attachments" on page 15-82
Oracle BPEL Process Manager Workflow Services
15-45
Task 1: Creating the Human Task Definition with the Human Task Editor
Specifying Advanced Settings
This section enables you to specify advanced human task features, such as specifying
custom escalation rules, custom style sheets for attachments, multilingual settings,
custom task actions and error messages, and callback classes.
Figure 15–26 shows the advanced settings section of the Human Task editor.
Figure 15–26 Human Task Editor — Advanced Settings Section
Table 15–10 describes the sections available.
Table 15–10
Advanced Settings Sections
Section
See...
Specify escalation rule
"Specifying Escalation Rules" on page 15-46
Specify WordML Stylesheet
for attachments
"Specifying WordML Style Sheets for Attachments" on
page 15-47
Specify stylesheet for
attachments
"Specifying Style Sheets for Attachments" on page 15-47
Specify multilingual settings
"Specifying Multilingual Settings" on page 15-47
Override default system
actions
"Overriding Default System Actions" on page 15-48
Override default exception
management
"Overriding Default Exception Management" on page 15-50
Specify callback class on task
status
"Specifying Callback Classes on Task Status" on page 15-50
Allow task and routing
customization in BPEL
callbacks
"Allowing Task and Routing Customization in BPEL
Callbacks" on page 15-50
Specifying Escalation Rules
This option allows a custom escalation rule to be plugged in for a particular workflow.
For example, to assign the task to a current user’s department manager on task
expiration, you can write a custom task escalation function, register it with the
workflow service, and use that function in task definitions.
The default escalation rule is to assign a task to the manager of the current user. To add
a new escalation rule, follow the steps below.
15-46 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
1.
Implement interface
oracle.bpel.services.workflow.assignment.dynamic.IDynamicTask
EscalationFunction. This implementation has to be available in the classpath
for the server.
2.
Change the file SOA_Oracle_
Home\bpel\system\services\config\wf-dynamic-assign-cfg.xml to
add a new function:
<dynamicAssignmentFunctions>
<function name="MANAGERS_MANAGER"
classpath="oracle.bpel.services.workflow.assignment.dynamic.patterns.
TaskEscalationManagersManager">
</function>
</dynamicAssignmentFunctions>
3.
Enter the function name as defined in the wf-dynamic-assign-cfg.xml file
for the escalation rule in the Specify Escalation Rule field.
See Also:
"Custom Escalation Function" on page 15-119
Specifying WordML Style Sheets for Attachments
This option allows dynamic creation of Microsoft Word documents for the purpose of
sending them as e-mail attachments using a WordML XSLT stylesheet. The XSLT
stylesheet is applied on the task document.
1.
Click the flashlight icon to select a WordML style sheet as an attachment.
See Also: Oracle Application Server Developer’s Guide for Microsoft
Office Interoperability for specific details
Specifying Style Sheets for Attachments
This option allows creation of e-mail attachments using an XSLT stylesheet. The XSLT
stylesheet is applied on the task document.
1.
Click the flashlight icon to select a stylesheet as an attachment.
Specifying Multilingual Settings
You can specify resource bundles for displaying task details in different languages in
the Oracle BPEL Worklist Application. Resource bundles are supported for the
following task details.
■
■
■
Displaying the value for task outcomes in plain text or with the message(key)
format
Displaying the XML element and attributes names in the payload display of the
Oracle BPEL Worklist Application. The key name in the resource bundle must be
the same as the name of the XML element and attributes for internationalization of
XML element names in the Oracle BPEL Worklist Application.
Making e-mail notification messages available in different languages. At run time,
specify the XPath extension function
hwf:getTaskResourceBundleString(taskId, key, locale?) to obtain
the internationalized string from the specified resource bundle. The locale of the
notification recipient can be retrieved with the function
hwf:getNotificationProperty(propertyName).
Oracle BPEL Process Manager Workflow Services
15-47
Task 1: Creating the Human Task Definition with the Human Task Editor
1.
Click Configure Resource.
The Resource Details window appears.
2.
Enter the name of the resource used in the resource bundle.
3.
Click the flashlight icon to select the JAR or ZIP resource bundle file to use. The
resource bundle can be part of your BPEL suitcase.
4.
Click OK to return to the Human Task editor.
See Also: "Configuring Messages in Different Languages" on
page 15-81
Overriding Default System Actions
The actions performed from the Oracle BPEL Worklist Application are common to all
business processes. However, you can restrict some actions in a particular business
process.
For example, assume that in a loan approval process, the business requirement is to
never suspend a loan application. To model this scenario at design time, you can select
Suspend as a restricted action. When an action is selected as restricted, the Oracle
BPEL Worklist Application does not display the action for this task.
By default, these actions are available on all tasks based on the user's privileges. The
task owner or bpeladmin administrator can always perform any of these actions on
processes they own.
1.
Click Configure Actions.
2.
Select the system actions allowed on a task. By default, all are selected and
available (unrestricted).
15-48 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
The following system actions can be restricted by unselecting them:
■
■
■
■
■
■
■
■
■
■
Suspend — Enables task owners (or users with the BPMWorkflowSuspend
privilege) to put a workflow temporarily on hold. Task expiration and
escalation do not apply until the workflow is resumed. No actions are
permitted on a suspended task (except resume and withdraw).
Push back — Sends the task one level back in the workflow. For example,
assume the task was routed to the LoanAgentGroup and then to jstein. If
jstein now pushes the task back, it goes back to the LoanAgentGroup.
Renew — If a task is about to expire, a task assignee can renew the task and
request more time to perform the task. This operation is not allowed if the
process designer has restricted task renewal on the workflow.
Skip current assignment — Skips the current assignment and moves to the
next assignment or picks the outcome as set by the previous approver if there
are no more assignees.
Adhoc Route — Enables a user to enter an outcome and then route the task in
an adhoc fashion to the next user who must review the task.
Request Information — Any workflow participant can request information
from the task initiator or any of the prior approvers of the task. When the
requested information is submitted, the task is assigned to the user who
requested the information.
Delegate — Any workflow participant can delegate the task to another user.
In this case, the other user is acting on behalf of the current assignee. When the
task is delegated, it resides on both users’ worklists until the original assignee
or the delegated person acts on it.
Reassign — Enables the current assignee of the task to transfer it to another
user or group. In this case, the task is moved from the worklist of the current
assignee to the new assignee.
Escalate — Escalates a task to their manager for further action.
Withdraw — Enables the task initiator to withdraw any pending task if they
no longer want to send it through the workflow. A task owner can also
withdraw a task on behalf of the initiator. When a task is withdrawn, the
Oracle BPEL Process Manager Workflow Services
15-49
Task 1: Creating the Human Task Definition with the Human Task Editor
business process is called back with the state attribute of the task set to
Withdrawn.
3.
Click OK to return to the Human Task editor.
Overriding Default Exception Management
Tasks can error due to incorrect assignments. Incorrect assignments can occur for any
of the following reasons:
■
■
Invalid assignees — The task assignee user or group is not a valid user in the
system.
Invalid dynamic assignment — When assignees are specified to be dynamic, the
dynamic XPath expression is not evaluated.
In the above cases, the task is marked as errored. By default, the life cycle of the task is
completed with that action.
During modeling of workflow tasks, you can specify error assignees for the workflow.
If error assignees are specified, they are evaluated and the task is assigned to them.
The error assignee can perform one of the following actions:
■
Adhoc route — route the task to the actual users assigned to the task. Adhoc route
allows the task to be routed to users in sequence, parallel, and so on.
■
Reassign — reassign the task to the actual users assigned to this task
■
Error task — indicate that this task cannot be rectified.
If there are any errors in evaluating the error assignees, the task is marked as errored.
This window enables you to specify the users or groups to whom the task is assigned
if an error in assignment has occurred.
1.
Click Configure Assignment.
2.
Select the error assignees.
Specifying Callback Classes on Task Status
You can register callbacks for the workflow service to call during the life cycle of a
task. The callback class has to implement the interface
oracle.bpel.services.workflow.task.IRoutingSlipCallback. Make the
callback class available in the classpath of the server.
15-50 Oracle BPEL Process Manager Developer’s Guide
Task 1: Creating the Human Task Definition with the Human Task Editor
1.
Click Configure Callbacks.
2.
Click the + sign to add a callback to the table. A callback named OnAssigned is
automatically added to the Callback column.
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
includes updates on a task due to request for information, submit information,
escalation, reassign, and so on.
onSubtaskUpdated — This callback is invoked for any update to a subtask.
4.
Click Java in the Type column to display a list of additional values for this column.
5.
Click the empty field in the Value column to enter a value. The value is the
complete class name of the Java class that implements
oracle.bpel.services.workflow.task.IRoutingSlipCallback.
6.
Click OK.
Allowing Task and Routing Customization in BPEL Callbacks
The Allow task and routing customization in BPEL callbacks check box must be
selected if you select the check box of the same name on the Human Task - Advanced
tab shown in Figure 15–28 on page 15-57. Selecting both check boxes updates the
metadata for callbacks.
See Also: "Allowing Task and Routing Customizations in BPEL
Callbacks" on page 15-58 for details on using callbacks
Oracle BPEL Process Manager Workflow Services
15-51
Task 2: Associating the Human Task with a BPEL Process
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.
Task 2: Associating the Human Task with a BPEL Process
You must associate the .task file that consists of the human task settings with a BPEL
process. When association is complete, a Task Service partner link is created. The Task
Service exposes the operations required to act on a task.
The method by which you created the human task indicates if the task is already
associated with a BPEL process. Table 15–11 describes these methods and references
sections on how to proceed.
Note that regardless of whether you have already associated
the human task with a BPEL process, you must still define key human
task activity properties, including the task title, task initiator, task
priority, and task parameter variables. These tasks are described in
"Defining the Human Task Activity Title, Initiator, Priority, and
Parameter Variables" on page 15-54 and "Defining the Human Task
Activity Advanced Features" on page 15-56.
Note:
Table 15–11
Human Task Association with the BPEL Process
Human Task Creation Method
1.
2.
Then...
See...
You must associate the "Associating a Human
human task with your Worklist Task with a
BPEL Process" on
BPEL process.
Selected Create Human Task Definition.
page 15-53
Right-clicked the BPEL process in the
Application Navigator.
1.
Dragged and dropped a human task
activity into the BPEL process.
2.
Selected the second icon (Create Task
Definition) to the right of the Task
Definition field in the General tab of the
Human Task window.
The human task is
"Opening a Human
already associated
Task Activity Already
with the BPEL process Associated with a
BPEL Process" on
page 15-53
See Also: "Task 1: Creating the Human Task Definition with the
Human Task Editor" on page 15-14 for instructions on creating a
human task
15-52 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
Associating a Human Worklist Task with a BPEL Process
1.
Select the BPEL process with which to associate the .task file of the human task
in the Application Navigator.
2.
Select Process Activities from the Component Palette.
3.
Drag and drop a new Human Task activity into your BPEL process.
The Add a Human Task window appears.
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.
Note:
4.
Click the first icon to the right of the Task Definition field.
The Choose Task Definition File appears.
5.
Select the .task file and click Open. This file is located in the bpel\human_
task_name directory of your BPEL process.
The .task file is added to the Task Definition field.
6.
See the following sections to configure the human task activity:
■
■
Defining the Human Task Activity Title, Initiator, Priority, and Parameter
Variables
Defining the Human Task Activity Advanced Features
Opening a Human Task Activity Already Associated with a BPEL Process
1.
Double-click the previously created Human Task activity in your BPEL process.
The Human Task window appears.
2.
Click the third icon to the right of the Task Definition field to open the human
worklist task you previously created.
3.
See the following sections to configure the human task activity:
■
■
Defining the Human Task Activity Title, Initiator, Priority, and Parameter
Variables
Defining the Human Task Activity Advanced Features
Oracle BPEL Process Manager Workflow Services
15-53
Task 2: Associating the Human Task with a BPEL Process
Defining the Human Task Activity Title, Initiator, Priority, and Parameter Variables
Figure 15–27 shows the General tab.
Figure 15–27 Human Task — General Tab
The General tab of the Human Task activity enables you to perform the tasks shown in
Table 15–12:
Table 15–12
Human Task - General Tab
For this Field...
See...
Task Title
"Specifying the Task Title" on page 15-54
Initiator
"Specifying the Task Initiator and Task Priority" on page 15-54
Priority
Task Parameters
"Specifying Task Parameters" on page 15-55
Specifying the Task Title
1.
Enter the task title in the Task Title field through one of the following methods.
This is a mandatory field. Your entry in this field overrides the task title you
entered in the Title field of the Human Task editor described in "Specifying a Task
Title and Priority" on page 15-17. The title displays the task in the Oracle BPEL
Worklist Application during run time.
■
■
Enter the title manually.
Click the icon to the right of the field to display the Expression Builder
window to dynamically create the title.
You can also mix static text and dynamic expressions in the same title. To include
dynamic text, place your cursor at the appropriate point in the text and click the
icon on the right to invoke the Expression Builder window.
See Also: "Assigning Input and Output Parameters for the Human
Task" on page 15-90 for an example of specifying the task title name
Specifying the Task Initiator and Task Priority
1.
Enter the initiator (for example, jcooper) or click the icon to the right of the
Initiator field to display the Expression Builder window for dynamically
specifying an initiator. This field is optional.
15-54 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
The initiator is the user who initiates a task. The initiator can view their created
tasks from the Oracle BPEL Worklist Application and perform specific tasks
defined in the System Action Details window, such as withdrawing or suspending
a task. If not specified, the initiator defaults to the task owner specified on the
Advanced tab of the Human Task window. The initiator defaults to bpeladmin if
a task owner is also not specified.
2.
Select a priority value between 1 (the highest) and 5 from the Priority list. This
field is provided for user reference and does not make this task a higher priority
during run time. The priority can be used to sort tasks in the Oracle BPEL Worklist
Application. This priority value overrides the priority value you select in the
Priority list of the Human Task editor.
See Also: "Specifying a Task Title and Priority" on page 15-17 for
instructions on specifying the priority in the Human Task editor
Specifying Task Parameters
The task parameter table displays a list of task parameters after you complete the Task
Title and Initiator fields.
1.
Click the flashlight 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.
Oracle BPEL Process Manager Workflow Services
15-55
Task 2: Associating the Human Task with a BPEL Process
3.
Click OK.
The Human Task window appears as follows.
4.
Click Apply.
5.
If you want to define advanced features for the human task activity, click the
Advanced tab and go to section "Defining the Human Task Activity Advanced
Features" on page 15-56. Otherwise, click OK to close the Human Task window.
Defining the Human Task Activity Advanced Features
Figure 15–28 shows the Advanced tab.
15-56 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
Figure 15–28
Human Task — Advanced Tab
The Advanced tab of the Human Task activity enables you to perform the tasks shown
in Table 15–13:
Table 15–13
Human Task - Advanced Tab
For this Field...
See...
Scope Name
"Specifying a Scope Name and a Global Task Variable
Name" on page 15-57
Global Task Variable Name
Owner
"Specifying a Task Owner" on page 15-57
Identification Key
"Specifying an Identification Key" on page 15-58
Include task history from
"Including the Task History of Other Human Tasks" on
page 15-58
Allow task and routing
customization in BPEL callbacks
"Allowing Task and Routing Customizations in BPEL
Callbacks" on page 15-58
Specifying a Scope Name and a Global Task Variable Name
You are automatically provided with default scope and global task variable names
during human task activity creation. However, you can specify custom names that are
used to name the scope and global variable during human task activity creation.
1.
Enter the name for the BPEL scope to be generated in the Scope Name field.
This BPEL scope encapsulates the entire interaction with the workflow service and
BPEL variable manipulation.
2.
Enter the global task variable name in the Global Task Variable Name field.
This is the name of the BPEL task variable used for the workflow interaction.
Specifying a Task Owner
1.
Enter the task owner name in the Owner field or click the icon to the right to use
the Expression Builder to dynamically specify the owner of this task.
Oracle BPEL Process Manager Workflow Services
15-57
Task 2: Associating the Human Task with a BPEL Process
The task owner can view tasks belonging to business processes they own and
perform operations on behalf of any of the task assignees. Additionally, the owner
can also reassign, withdraw, or escalate tasks.
If you do not specify a task initiator on the General tab of the Human Task
window, it defaults to the owner specified here. If an owner is not specified, it
defaults to the bpeladmin administrator.
Specifying an Identification Key
1.
Enter an optional identification key value in the Identification Key field.
The identification key can be used as a user-defined ID for the task. For example, if
the task is meant for approving a purchase order, the purchase order ID can be set
as the identification key of the task. Tasks can be searched from the Oracle BPEL
Worklist Application using the identification key. This attribute has no default
value.
Including the Task History of Other Human Tasks
This feature enables one workflow to be continued with another workflow.
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 workflow task is continued with another workflow, 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. Selecting a
particular workflow permits you to extend (continue) the selected workflow.
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.
See Also:
"Including the Task History from Other Workflows" on
page 15-63
Allowing Task and Routing Customizations in BPEL Callbacks
1.
Select the Allow task and routing customizations in BPEL callbacks check box to
notify the BPEL process using OnMessage callbacks every time a task is routed to
a different user or when the task status changes. You must also select the check
15-58 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
box of the same name in the Advanced Settings section of the Human Task editor
shown in Figure 15–26 on page 15-46 in order to update the metadata for callbacks.
In these callbacks, you can call the Task Service to change the routing or update
the current assignees. This option impacts the BPEL code generated to interact
with the Task Service.
If this option is not selected, the client process gets notified only when the task
completes or when it expires or errors out.
2.
Click OK to close the Human Task window.
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:
■
■
"Allowing Task and Routing Customization in BPEL Callbacks" on
page 15-51
"BPEL Callbacks" on page 15-61
Viewing the Generated Human Task Activity
When you have completed modeling the human task activity, the human task is
generated in the designer window.
Figure 15–29 shows how a workflow interaction is modeled in Oracle BPEL Process
Manager. Figure 15–29 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.
Oracle BPEL Process Manager Workflow Services
15-59
Task 2: Associating the Human Task with a BPEL Process
Figure 15–29 Workflow Interaction Modeling
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
Figure 15–30 shows a workflow interaction in Oracle JDeveloper.
15-60 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
Figure 15–30 Workflow Interaction Modeling in Oracle JDeveloper
BPEL Callbacks
If intermediary events need to be propagated to the BPEL process instance, select the
Allow task and routing customization in BPEL callbacks check box in both the
Advanced tab of the Human Task window and the Advanced Settings section of the
Human Task editor. When these options are selected, the workflow service invokes
callbacks in the BPEL instance during each update of the task. The callbacks are listed
in the TaskService.wsdl file and described below:
■
■
■
onTaskCompleted — This callback is invoked when the task is completed,
expired, withdrawn, or errored.
onTaskAssigned — 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
onTaskUpdated — This callback is invoked for any other update to the task that
does not fall in the onTaskComplete or onTaskAssigned callback. This
includes updates on tasks due to request for information, submit information,
escalation, reassign, and so on.
Oracle BPEL Process Manager Workflow Services
15-61
Task 2: Associating the Human Task with a BPEL Process
■
onSubTaskUpdated — This callback is invoked for any update to a subtask.
Figure 15–31 shows how a workflow interaction with callbacks is modeled in Oracle
BPEL Process Manager. Once this task is initiated, a while loop is used to receive
messages until the task is complete. The while loop contains a pick with four
onMessage branches — one for each of the above-mentioned callback operations. The
workflow interaction works fine even if nothing is changed in the onMessage
branches, meaning that customizations in the onMessage branches are not required.
In this scenario, a workflow context is captured in the BPEL instance. This context can
be used for all interaction with the workflow services. For example, if you want to
reassign a task if it is assigned to a group, then you need the workflow context for the
reassignTask operation on the Task Service.
It is recommended that any user customizations be done in the first assign,
AssignTaskAttributes, and that AssignSystemTaskAttributes not be changed.
Figure 15–31 Workflow Interaction Modeling (with Callbacks)
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
While the task is not
completed/expired/errored
Pick
activity
Receive
onTaskCompleted
message
Receive
onTaskAssigned
message
Receive
onTaskUpdated
message
Receive
onSubTaskUpdate
message
User
customizations
User
customizations
User
customizations
User
customizations
15-62 Oracle BPEL Process Manager Developer’s Guide
Task 2: Associating the Human Task with a BPEL Process
Figure 15–32 shows a workflow interaction in Oracle JDeveloper.
Figure 15–32 Workflow Interaction Modeling (with Callbacks) in Oracle JDeveloper
Including the Task History from Other Workflows
When the task history is included in a workflow, the generated BPEL process
described in the previous two sections is similar, with the following differences:
■
■
The BPEL variable from the workflow whose task history is to be included is
reused and no new BPEL variable is created.
The first invoke activity invokes the reinitiate operation instead of the initiate
operation.
See Also: "Including the Task History of Other Human Tasks" on
page 15-58
Outcome-Based Modeling
In many cases, the outcome of a task determines the flow of the business process. To
facilitate modeling of the business logic, when a user task is generated, a BPEL switch
activity is also generated with prebuilt BPEL case activities. By default, one case
branch is created for each outcome selected during creation of the task. An otherwise
branch is also generated in the switch to represent cases when the task is withdrawn,
expired, or errored.
Oracle BPEL Process Manager Workflow Services
15-63
Task 2: Associating the Human Task with a BPEL Process
Payload Updates
The task carries a payload in it. If the payload is set from a business process variable,
then an assign activity with the name copyPayloadFromTask is created in each of
the case and otherwise branches to copy the payload from the task back to its source. If
the payload is expressed as other XPath expressions (such as ora:getNodes(...)),
then this assign is not created because of the lack of a process variable to copy the
payload back. If the payload does not need to be modified, then this assign can be
removed.
Case Statements for Other Task Conclusions
By default, the switch activity contains case statements for the outcomes only. The
other task conclusions are captured in the otherwise branch. These conclusions are as
follows:
■
The task is withdrawn
■
The task is errored
■
The task is expired
If business logic must be added for each of these other conclusions, then case
statements can be added for each of the preceding conditions. The case statements can
be created as shown in the following BPEL segment. The XPath conditions for the
other conclusions in the case activities for each of the preceding cases are shown in
bold.
<switch name="taskSwitch">
<case condition="bpws:getVariableData('SequentialWorkflowVar1',
'/task:task/task:state') = 'COMPLETED' and
bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:conclusion') =
'ACCEPT'">
<bpelx:annotation>
<bpelx:pattern>Task outcome is ACCEPT
</bpelx:pattern>
</bpelx:annotation>
...
</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
15-64 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<otherwise>
<bpelx:annotation>
<bpelx:pattern>Task is EXPIRED, WITHDRAWN or ERRORED
</bpelx:pattern>
</bpelx:annotation>
...
</otherwise>
</switch>
Task 3: Generating the Task Display Form
The task display form defines the display mechanism for the task payload in the
Oracle BPEL Worklist Application. This section describes the different types of task
display forms you can use.
This section contains the following topics:
■
Overview of Task Display Forms
■
Selecting a Task Display Form
■
Automatically Generating a Simple Task Display Form
■
Generating a Custom Task Display Form
■
Deploying Task Display Forms
■
Creating Custom JSP Forms
Overview of Task Display Forms
The task display form for the human task can be automatically generated and then
customized or developed completely from the beginning using the workflow APIs. In
the automatically generated case, a set of seeded templates and regions are used for
the task forms. There are two methods for generating forms associated with the task
definition:
■
■
Automatically generate a simple task form — JSP-based forms that use the
standard header, body, and footer template.
Custom task form — enables you to select one of the existing templates and
regions to create a task form. You can also specify which task parameters to
display in the form.
When task display forms are generated, a .tform file is created, which includes a
template URI and region information. The .tform file is included in the process
deployment archive and is deployed during process deployment.
See Also: "Automatically Generating a Simple Task Display Form"
on page 15-67 for an example of a .tform file
Selecting a Task Display Form
Follow these instructions to generate a task display form for the human task.
1.
Go to the Application Navigator in Oracle JDeveloper.
Oracle BPEL Process Manager Workflow Services
15-65
Task 3: Generating the Task Display Form
2.
Right-click the folder of the human task for which to create a task display form
(for this example, ExpenseApproval of the ExpenseRequest BPEL process in
selected).
The following menu of selections appears.
3.
See the following sections for details about generating the different types of task
forms:
Selection
See...
Auto Generate Simple Task Form
"Automatically Generating a Simple Task
Display Form" on page 15-67
Custom Task Form
"Generating a Custom Task Display Form" on
page 15-73
Preview Release of Task Display Form Support for ADF Data Controls
A preview release of task display form support for application development
framework (ADF) data controls is provided. Very minimal support is provided with
this preview release. Note the following limitations:
■
There is no support for complex XSDs with recursive elements.
■
Task forms generated with ADF data controls cannot be edited.
Follow these procedures to use this preview release:
1.
Open an operating system command prompt.
2.
Open Oracle JDeveloper in preview mode:
JDev_Oracle_Home\jdev\bin\jdev.exe -J"-Dpreview_mode=true"
Note that Auto Generate Task Form With ADF Datacontrols now appears as a
menu option when you right-click the folder of the human task, as shown in Step 2
of "Selecting a Task Display Form" on page 15-66.
3.
Open the SOA_Oracle_Home\j2ee\OC4J_Home\config\server.xml file.
where OC4J_Home is the name of the OC4J container for your install type:
4.
–
home — for the Oracle Application Server SOA Basic install type
–
OC4J_SOA — if you accepted the default value for the Oracle Application
Server SOA Advanced install types
Add the following line under the <shared-library
name="oracle.bpel.common" version="10.1.3"> section:
<import-shared-library name="adf.oracle.domain"/>
5.
Restart Oracle Application Server SOA Suite for the changes to take effect.
15-66 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
Automatically Generating a Simple Task Display Form
This option enables you to automatically generate a task form based on the default
task parameters and three regions.
1.
Select Auto Generate Simple Task Form from the list shown in Step 2 on
page 15-66.
The default layout is based on the following three region template:
■
■
■
Header region — this region has standard task attributes such as title, priority,
created date, assignee, and expiration date. This information is contained in
the Header1.jsp file.
Body region — this region is generated based on the task parameters.
Depending on the XSD used in the task, it is either generated as a list of values
or as a table (for repeating items). If you specified the parameter to be
modifiable through the worklist on the Add Task Parameter window in Step 2
on page 15-21, it displays as an editable field in the form. Otherwise, the field
displays as read-only. The information for this region is contained in the
payload-body.jsp file and the payload-body.xml mapping file. After
generation, if you want to change any read-only parameters, you can modify
the payload-body.xml file.
Footer region — this region has an area for comments, attachments, and a
short history of the task routing. This information is contained in the
Footer1.jsp file.
A .tform file is generated. The contents of this file are as follows:
<?xml version = '1.0' encoding = 'UTF-8'?>
<taskDisplay
targetNamespace="http://xmlns.companyABC.com/workflow/orderTaskDisplay"
generateInternationlizedJSP="false"
xmlns:task="http://xmlns.oracle.com/bpel/workflow/task"
xmlns="http://xmlns.oracle.com/bpel/workflow/taskDisplay">
<taskDefinitionId>${domain_id}_${process_id}_${process_revision}_
Workflow_Name</taskDefinitionId>
<applicationName>worklist</applicationName>
<template>${http_url}/${domain_id}/${process_id}/${process_
revision}/Workflow_Name/Template_Name.jsp</template>
<regions>
<defaultJSP regionName="Header">
<jspURI>Header1.jsp</jspURI>
</defaultJSP>
<autoGeneratedJSP regionName="Body" editable="true">
<jspURI>payload-body.jsp</jspURI>
<messageAttribute
editable="false">Workflow_NameProcessRequest</messageAttribute>
</autoGeneratedJSP>
<defaultJSP regionName="Footer">
<jspURI>Footer1.jsp</jspURI>
</defaultJSP>
</regions>
</taskDisplay>
Payload File for the Autogenerated JSP
Two files are automatically generated to display the payload for the autogenerated
JSP:
Oracle BPEL Process Manager Workflow Services
15-67
Task 3: Generating the Task Display Form
■
■
A default JSP file named payload-body.jsp. This file is added to the HTML
root directory of your project, which is by default the public_html directory.
A mapping XML file named payload-body.xml. This file is added to the same
directory of your project as payload-body.jsp.
If you select Custom Task Form in Step 2 on page 15-66, you
can specify a unique file name for the autogenerated JSP. The mapping
XML file is created based on the JSP file name. You can also select the
payload elements to include in the autogenerated JSP. For example, if
the JSP file is named autogenerate-body.jsp, then the mapping
XML file is named autogenerate-body.xml.
Note:
See "Generating a Custom Task Display Form" on page 15-73 for
details.
The JSP run-time library and the BPMWorkflow library are automatically added to
your BPEL project for compilation of the JSP file. The default JSP is designed with two
goals in mind:
■
■
To present you with a simple form; that is, an XSD tree with a depth of more than
three must be shown in a more readable way in the JSP.
The default JSP must require minimum modification. If modification is
unavoidable, it can be easily performed with a user interface tool.
To attain these goals, instead of presenting a tree structure that mimics the payload
XSD structure, the default JSP groups the entire payload structure in sections. It
groups simple types that belong to the same parents and makes them sections.
For example, assume you provide the following payload XSD:
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.mycompany.com/mycompany"
xmlns:mp="http://www.mycompany.com/mycompany">
<element name="myCompany" type="mp:myCompanyType"/>
<complexType name="myCompanyType" >
<sequence>
<element name="board" type="mp:boardType" />
<element name="CEO" type="string"/>
<element name="department" type="mp:departmentType" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="boardType">
<sequence>
<element name="size" type="int" />
<element name="head" type="string" />
</sequence>
</complexType>
<complexType name="departmentType">
<sequence>
<element name="size" type="int" />
<element name="head" type="string" />
<element name="function" type="string" />
</sequence>
</complexType>
15-68 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
</schema>
This XSD has the structure shown in Figure 15–33.
Figure 15–33
Structure of the XSD for myCompanyType
In the default JSP, based on the structure of the leaf nodes, there are three sections:
{size, head}, {CEO}, and {size, head, function}. These three sections are named
according to their parents’ names; that is, the sections are named board, my
Company, and department, respectively. In the board section, there are two fields,
size and head. Each of these fields are in an editable HTML input type.
The section department is different from other sections and can have multiple
occurrences (maxOccurs > 1). In this case, all the fields in this section (that is, size,
head, and function) are horizontally presented in a table, with each row
representing one department. This is called a table section. There is a plus (+) button
for adding a row (department) and a minus (-) button for subtracting a row
(department) for the department table section.
Unlike a regular section, it is not necessarily true that all the fields belong to the same
XSD parent in a table section. For example, suppose the head element has two
elements: employeeNumber and dateOfBirth. Since these two elements have
maxOccurs set to less than or equal to 1, they are shown in the same department
table section. This is a desired behavior, because adding a row in the department
table not only adds a size and a function field, but also adds the head information
fields in the same department row. This makes it easy to move through complicated
payload instances.
Nested multiple (maxOccurs > 1) elements are supported. Assume the department
element has a groupMember child element whose maxOccurs is unbounded. In that
case, the parent element department is presented in a table section while the child
groupMember elements are presented in different child table sections. The parent
department table section has a column called group member that contains an
HTML href link pointing to its corresponding child group member section in each
department row. Pressing the + button in the parent department section not only
adds a row in the parent table, but also adds a child section for that corresponding
new row.
Oracle BPEL Process Manager Workflow Services
15-69
Task 3: Generating the Task Display Form
The default JSP in the current release has the following limitations:
■
■
■
■
■
XSDs that contain recursive elements are not supported.
The default JSP shows all the simple types defined in the payload XSD. If multiple
simple types belong to the same XSD choice block, all these simple types are
shown in the default JSP. Although simple types are preserved in the JSP, XSD
restrictions are not relevant.
Only payloads copied from variables that are not simple types are supported. For
example, if the query is bpws:getVariableData(var) or
bpws:getVariableData(var, part) and the variable is a simple type, then
JSP generation fails. Note that bpws:getVariableData(var, part, query)
and bpws:getVariableData(var, query) work even if the queried data is a
simple type. You only need to make sure the variable itself is not a simple type.
XSI extensions are not supported
No special handling of XSD order indicators occurs (that is, choice, all, and
sequence). For example, the default JSP does not check if you entered both
firstname and lastname:
<xs:element name="person">
<xs:complexType>
<xs:all>
<xs:element name="firstname" type="xs:string"/>
<xs:element name="lastname" type="xs:string"/>
</xs:all>
</xs:complexType>
</xs:element>
Customizing the Autogenerated JSP The autogenerated default JSP is generic, and so may
require changes to improve its look and feel. The JSP works in conjunction with the
mapping file to determine which elements in the payload are displayed in the form.
Customizing the Mapping File The mapping file gives you control of the presentation. The
mapping file is an XML file that contains a list of viewable fields. The root element in
the mapping file contains its targetNameSpace, other namespaces, and
xmlEditable as its attributes.
All the elements that are simple types are listed as fields in the mapping file. Along
with these elements, their immediate parents are listed as well for multilanguage
support. Each field has three properties defined in the mapping file. They are xpath,
editable, and resource_key.
The xpath property defines the XPath of this field. It is always prefixed by
/ns0:task/ns0:payload. This is the XPath to the root of the payload object. When
maxOccurs is greater than 1, it is denoted by [*]. For example,
/ns0:task/ns0:payload/company[*]/ceo shows that maxOccurs is greater
than 1 for the company field.
Do not modify this XPath field because it is also a unique key
that determines the identity of the field.
Note:
The editable property defines if this field is editable. It defaults to true. If the value
of this field is changed to false, the default JSP shows a disabled text field that
disallows value changes.
15-70 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
The resource_key property is for multilanguage support. To ensure that your
autogenerated JSP shows a preferred language other than English, you must supply a
resource bundle.
Follow these steps to add a resource bundle:
1.
Create a bundle file (for example, MyBundle). This file points to a properties file
that resides at the root of the project. The following code shows an example of
MyBundle_en-US.properties:
ACCEPT_MSG = Accept0
REJECT_MSG = Reject0
FLEX_STRING1_MSG = Flex String1
FLEX_LONG1_MSG = Flex Long1
FLEX_DATE1_MSG = Flex Date1
TASK_TITLE = i18n Task
In this case, if a field is defined in your mapping file as follows
<field>
<xpath>/ns0:task/ns0:payload/taskTitle</xpath>
<editable>true</editable>
<resourceKey>TASK_TITLE</resourceKey>
</field>
then calling
FormUtil.getElementDisplayName("/ns0:task/ns0:payload/taskTitle", ,
form, context.getLocale(), task)
in the default JSP returns the string i18n Task if your locale is set to en-US.
Similarly, if your locale is set to French, the proper properties file (MyBundle_
fr.properties) is picked up.
2.
Specify the resource bundle name and location in the Resource Details window of
the Human Task editor, as shown in "Specifying Multilingual Settings" on
page 15-47.
Customizing the Default JSP
If the mapping file does not provide enough control, you can modify the default JSP
file. Only modify the section after the label:
/* Modify the code below when necessary */
Most JSP modifications can be made in the JSP design view of Oracle JDeveloper.
By default, all the fields are set to text field. If you want to change a text field to a text
area, you can do the following.
1.
Select Text Area in the Component Palette, as shown in Figure 15–34.
Oracle BPEL Process Manager Workflow Services
15-71
Task 3: Generating the Task Display Form
Figure 15–34 Oracle JDeveloper JSP Design View
2.
Drop it into the position of the text field you want to replace.
3.
Note that the name of the text field is set by calling the function
oracle.bpel.services.workflow.worklist.payload.PayloadFormGen
erator.constructName(String xpath), and the value of the field is set by
PayloadFormGenerator.selectNodeValue(Element payload, String
xpath, Map namespace). These functions must be used to construct form field
names and to retrieve form field values.
4.
Set the text area’s name and value to the same name and value as the text field.
5.
Delete the text field.
6.
In the place you want to insert text or other HTML elements that are not in a table,
add text by typing it or add an HTML element by dragging and dropping the
HTML component from the Component Pallet.
7.
If the place you want to insert HTML elements is in an HTML table, to insert text
or a horizontal rule, first add a table row by clicking a row, right-clicking, and
selecting Insert Row. After a row is inserted, you may need to merge all the cells
in the row by selecting all the cells in the row and right-clicking to select Merge
Cells. Then you can either type your text or drag and drop your HTML
component.
8.
If you want to change the layout of the table or form, highlight the section you
want to modify, right-click, and select table or form.
9.
If you want to format the text, use the toolbar’s color and style buttons.
It is recommended that you modify the default JSP’s look and feel only. You
should preserve the functions being used in the JSP. You must not alter the hidden
parameters being submitted in the HTML form, because the Update button
invokes form submission to the WFTaskUpdate that expects certain values. If
15-72 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
your change is complicated and has programming logic in it, you must switch to
the source view and modify the JSP code directly.
By putting the statement <%@ page pageEncoding="UTF-8" %> in the default
JSP, UTF-8 is set as the default encoding.
See Also: The HelpDeskServiceRequest demo in SOA_Oracle_
Home\bpel\samples\demos for an example of an autogenerated
JSP and how to change the payload presentation
Generating a Custom Task Display Form
For this release, task display forms are generated by using templates consisting of
different regions. Oracle JDeveloper automatically includes three templates and two
default JSPs:
The three templates are as follows:
■
Three Region JSP — Consists of the header, body and footer regions. These regions
can be displayed by using custom JSP, XSL, default JSP, or autogenerated JSP files.
The automatically generated JSP displays the body region.
■
Two Region JSP — Consists of the header and footer regions
■
One Region JSP — Consists of the body region
The two default JSPs are as follows:
■
■
The header JSP displays task attributes such as task number, priority, title, and so
on.
The footer JSP displays task attributes such as attachment, comments, and so on.
The custom task display form enables you to select the template and rendering type
for displaying task details.
1.
Select Custom Task Form from the list shown in Step 2 on page 15-66.
The Task Form Display window appears.
2.
Select a template from the Current Template list. Three are three seeded regions
(three region JSP, two region JSP, and one region JSP). After selecting a region, you
can specify how to render it.
3.
See the following sections for details about generating the different types of
custom task display forms:
Oracle BPEL Process Manager Workflow Services
15-73
Task 3: Generating the Task Display Form
Type
See...
Auto JSP
"Autogenerated JSP" on page 15-74
Custom JSP
"Custom JSP" on page 15-75
Default JSP
"Default JSP" on page 15-76
XSL
"XSL" on page 15-76
Autogenerated JSP
This option enables you to automatically generate a form for the payload of the task.
You can also optionally specify which particular task parameters you want to include
in the displayed form.
1.
Select Auto JSP from the Body list in the Rendering section.
An icon displays to the right of Body.jsp in the Source section.
2.
Click the icon.
The Payload Mapping window appears.
This window enables you to select message attributes.
3.
Select message attributes to include in the autogenerated JSP.
4.
Click OK to return to the Task Form Display window.
15-74 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
Custom JSP
This option enables you to invoke an external custom JSP to display the task details.
You can also specify URL parameters to pass to this JSP at run time. Three parameters
are passed in by default — taskID, version, and workflowContext. Additional
parameters must be explicitly specified.
1.
Select Custom JSP from the Header list in the Rendering section.
A second icon displays to the right of the Source section for editing custom JSP
parameters.
2.
Enter the custom JSP file name in the Source field or click the first icon to select the
JSP file to use. This JSP is used in the project and deployed with the other JSP files.
3.
Click the second icon to specify run time JSP parameters.
The Payload Mapping window appears. This window enables you to add input
JSP parameters.
4.
Add a parameter by clicking the + sign.
5.
Add a name in the Name column.
6.
Click the icon to the right of the row to display the Expression Builder window to
dynamically enter a value for the XPath column.
For this example, the custom JSP is using a parameter named PRIORITY to
receive the task ID from the request. Therefore, PRIORITY is specified as the
name and /tns:task/tns:systemAttributes/tns:PRIORITY is specified as the XPath
expression.
"Creating Custom JSP Forms" on page 15-76 for details
about explicitly passing parameters
See Also:
Oracle BPEL Process Manager Workflow Services
15-75
Task 3: Generating the Task Display Form
Default JSP
This option provides the default Header1.jsp and Footer1.jsp files to display the
header and footer regions, respectively.
XSL
This option enables you to specify an XSL to convert the task XML document into an
HTML document for the form. Note that this is useful only to create read-only forms.
1.
Enter the HTTP location in the Source field or click the first icon to select the input
XSL file to use.
Deploying Task Display Forms
Workflow task display forms are deployed by using the deployTaskForm ant target.
This target is executed when you deploy the BPEL process from Oracle JDeveloper or
from the command prompt. This target generates an EAR file that includes all
generated default or custom JSPs. This generated EAR file is deployed as a child of the
Oracle BPEL Process Manager application.
The following directory structure is generated.
JDev_Oracle_Home\jdev\mywork\application_name\project_name\public_html\human_task_
name\form
The following subdirectories and files are created:
■
■
A J2EE enterprise archive directory named ear is created. EAR deployment
descriptors are generated and stored in the META-INF subdirectory.
A Web archive (WAR) directory named war is created. This directory contains the
following files and subdirectories:
–
Style sheets and Java server page files for the header (Header1.jsp), footer
(Footer1.jsp), and body (payload-body.jsp and payload-body.xml)
are generated and stored in the war directory.
–
Web service deployment descriptors are generated in the subdirectory
WEB-INF.
You can delete all form-related files by right-clicking the human task folder in the
Application Navigator and selecting Delete Task Form files.
Creating Custom JSP Forms
As described earlier, you can register a custom JSP for rendering the task details in the
worklist. The BPEL worklist invokes any custom JSP that has been registered.
Follow these instructions to create a custom JSP form.
1.
Get the task ID, version, and context ID from the request.
2.
Get the workflow context object based on the context ID.
3.
Get the task object based on the task ID and version. Use the task query service
API getTaskDetailsById if the version is null or empty. Otherwise, use the
getTaskVersionDetails API.
4.
Use the task object methods to get the values you want to display in the JSP.
5.
In the case of update support, generate the hidden HTML type for the following
parameters, so that the update servlet can read these parameter values:
15-76 Oracle BPEL Process Manager Developer’s Guide
Task 3: Generating the Task Display Form
■
oracle.bpel.service.workflow.worklist.api.payload.PayloadCon
stants.WORKLIST_NEXT_PAGE_PARAMETER_NAME
■
oracle.bpel.service.workflow.worklist.api.payload.PayloadCon
stants.WORKLIST_LOGIN_PAGE_PARAMETER_NAME
■
oracle.bpel.service.workflow.worklist.api.payload.PayloadCon
stants.WORKLIST_ERROR_PAGE_PARAMETER_NAME
You can get the values for these parameters in the custom JSP servlet request
object. Run time invokes the custom JSP by passing these parameters.
The following custom JSP code shows how to use these steps to write a custom JSP
that uses the local query service and verification APIs. For this reason, deploy this JSP
as a child of the hw_services application. If you do not want to deploy to the same
application server, replace local APIs with remote APIs.
<%@ page contentType="text/html;charset=UTF-8"%>
<%@ page import="java.util.*,
java.net.URLEncoder,
java.io.UnsupportedEncodingException,
java.text.*,
oracle.bpel.services.workflow.query.impl.TaskQueryService,
oracle.bpel.services.workflow.query.ITaskQueryService,
oracle.bpel.services.workflow.verification.IWorkflowContext,
oracle.bpel.services.workflow.verification.IVerificationService,
oracle.bpel.services.workflow.verification.impl.VerificationService,
oracle.bpel.services.workflow.task.model.Task,
oracle.bpel.services.workflow.task.model.IdentityType,
oracle.bpel.services.workflow.task.model.CommentType,
oracle.bpel.services.workflow.task.model.AttachmentType,
oracle.bpel.services.workflow.task.model.IdentityType,
oracle.bpel.services.workflow.worklist.display.Resource,
oracle.bpel.services.workflow.worklist.display.ResourceKeyConstants,
oracle.bpel.services.workflow.worklist.servlet.Constants,
oracle.bpel.services.workflow.worklist.api.util.WorklistUtil,
oracle.bpel.services.workflow.worklist.api.payload.PayloadConstant;"%>
<%
String taskId = request.getParameter(Constants.WORKLIST_TASKID_PARAMETER_
NAME);
String strTaskVersion = request.getParameter(Constants.WORKLIST_TASK_
VERSION_PARAMETER_NAME);
String contextId = request.getParameter(Constants.WORKLIST_CONTEXT_
PARAMETER_NAME);
int taskVersion = 0;
// incase strTaskVersion is null means user wants latest version
// from WFTask table
// else it wants from the WFTaskHistory table
if(strTaskVersion != null && !strTaskVersion.trim().equals(""))
{
try
{
taskVersion = Integer.parseInt(strTaskVersion);
}
catch(NumberFormatException exc)
{
//TO DO throw the exception
taskVersion = 1;
Oracle BPEL Process Manager Workflow Services
15-77
How Changes to a Workflow Appear in Worklist Application
}
}
//no need to use Notm to get the task
Task task = (Task)session.getAttribute(Constants.SESSION_CURRENT_TASK_
OBJECT);
IVerificationService verificationService =
VerificationService.getVerificationService();
IWorkflowContext context = verificationService.getContext(contextId);
if(task == null)
{
ITaskQueryService queryService = TaskQueryService.getInstance();
if(taskVersion == 0)
{
task = queryService.getTaskDetailsById(context, taskId);
}
else
{
task = queryService.getTaskVersionDetails(context,taskId,taskVersion);
}
}
Locale locale = context.getLocale();
// get the TaskId and use above object
SimpleDateFormat dfshort = new SimpleDateFormat( "MM/dd/yy" );
SimpleDateFormat dflong = new SimpleDateFormat( "MM/dd/yy hh:mm a" );
String nextPage = request.getParameter(Constants.WORKLIST_NEXT_PAGE_
PARAMETER_NAME);
String loginPage = request.getParameter(Constants.WORKLIST_LOGIN_PAGE_
PARAMETER_NAME);
%>
Adding Update Support in the Custom JSP
To add update support in the custom JSP, you can write the servlet that uses the
remote task service APIs to update the custom JSP task values:
1.
Get the task object by using the same steps as used in the custom JSP.
2.
Query the task object and set the values based on the custom JSP form.
For example, if the custom JSP form allows a user to update the priority attribute,
then get the priority JSP form value and call task.setPriority(newvalue);.
3.
Use the remote task service API to update the task.
4.
Get the value from servlet parameter WORKLIST_NEXT_PAGE_PARAMETER_NAME,
which the custom JSP page includes as a hidden parameter.
5.
Redirect the page to the URL.
How Changes to a Workflow Appear in Worklist Application
Changes made in Oracle BPEL Control to a BPEL process that includes a human task
impact how tasks display in Oracle BPEL Worklist Application:
15-78 Oracle BPEL Process Manager Developer’s Guide
Notifications from Workflow Services
■
■
■
If you abort an active BPEL process instance on the Instances tab, associated tasks
are marked as Stale in the Status column of the Oracle BPEL Worklist Application
home page.
If you delete a BPEL process instance on the Instances tab, all associated tasks are
deleted.
If you undeploy a BPEL process on the BPEL Process tab, associated tasks are
marked as Stale in the Status column of the Oracle BPEL Worklist Application
home page.
Notifications from Workflow Services
Notifications are sent to alert users of changes to the state of a task. Notifications can
be sent through any of the following channels: e-mail, telephone voice message, fax,
pager, or SMS.
This section contains the following topics:
■
Configuring the Notification Channel
■
Contents of Notification
■
Configuring Messages in Different Languages
■
Sending Actionable E-mails
■
Sending Inbound and Outbound Attachments
■
Sending Inbound Comments
■
Reliability Support
■
Sending Secure Notifications
■
Channels Used for Notifications
■
Sending Reminders
Configuring the Notification Channel
After configuring the notification service for e-mail and other channels in Oracle
JDeveloper, set the NotificationMode parameter for the notification service to
either ALL or EMAIL in the SOA_Oracle_
Home\bpel\system\services\config\ns_emails.xml file.
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, SMS, voice, fax, and pager 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 — acquire, adhoc route, delegate, escalate, information for a
task is submitted, push back, reassign, release, and resume.
Oracle BPEL Process Manager Workflow Services
15-79
Notifications from Workflow Services
■
Task is completed
■
Task is errored
■
Task is expired
■
Information is requested for a task
■
Task outcome is updated
■
Task is suspended
■
Task is withdrawn
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:
■
■
■
"Specifying Participant Notification Preferences" on page 15-42 to
configure task notifications in the Human Task editor
Chapter 14, "Oracle BPEL Process Manager Notification Service"
Service Configuration chapter of the Oracle BPEL Process Manager
Administrator’s Guide for details about editing the ns_
emails.xml file and (for the JAZN XML provider)
users-properties.xml file
Contents of Notification
Each e-mail notification can contain the following parts:
■
■
The notification message
The HTML content from the worklist application — This is a read-only view of the
worklist application on the task.
■
Task attachments — If the notification includes task attachments
■
Actionable links
Notifications through SMS, voice, fax, and pager contain only the notification message.
The notification message is an XPath expression that can contain static text and
dynamic values. In creating the messages, only the task BPEL variable is available for
dynamic values. This restriction is because the messages are evaluated outside the
context of the BPEL process. The payload in the task variable is also strongly typed to
contain the type of the payload for XPath tree browsing. The XPath extension function
hwf:getNotificationProperty(propertyName) is available to get properties
15-80 Oracle BPEL Process Manager Developer’s Guide
Notifications from Workflow Services
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 results in a message similar to the following:
Dear Cooper, James Task 1111 is assigned to you. Congratulations
Configuring Messages in Different Languages
It is possible to get internationalized messages in the notification content using one of
the following methods.
■
■
If you want to use values from the resource bundle specified during the task
definition, use the XPath extension function
hwf:getTaskResourceBundleString(taskId, key, locale?). This
function returns the internationalized string from the resource bundle specified in
the task definition.
–
The locale of the notification recipient can be retrieved with the function
hwf:getNotificationProperty(‘locale’).
–
The task ID corresponding to a notification can be retrieved with the function
hwf:getNotificationProperty(‘taskId’).
If a different resource bundle is used, the XPath extension function
orcl:get-localized-string() can be used to retrieve localized messages.
See Also:
"Specifying Multilingual Settings" on page 15-47
Sending Actionable E-mails
Task actions can be performed through e-mail if the task is set up to enable actionable
e-mail (the same actions can also be performed from the Oracle BPEL Worklist
Application). An actionable e-mail account is the account in which task action-related
e-mails are received and processed. This e-mail account name is identified by the
element actionableEmailAccountName in the configuration file SOA_Oracle_
Home\bpel\system\services\config\wf_config.xml.
Oracle BPEL Process Manager Workflow Services
15-81
Notifications from Workflow Services
Ensure that you select Make e-mail messages actionable in the Notification Settings
section of the Human Task editor to make e-mail notifications actionable. (See
Figure 15–25 on page 15-43.) This enables you to perform task actions through e-mail.
If a notification is actionable, the e-mail contains links for each of the custom
outcomes. Clicking on the links invokes the compose window of the e-mail client. You
do not have to change anything in the subject or the body in this e-mail. If you change
the content with the NID substrings, the e-mail is not processed.
Figure 15–35 shows an actionable e-mail sample:
Figure 15–35 Actionable E-mails
See Also: "Securing Notifications, Making Messages Actionable, and
Sending Attachments" on page 15-45
Sending Inbound and Outbound Attachments
If the include attachments flag is checked; only e-mail is sent. The e-mails include all
the task attachments as e-mail attachments. Select Send task attachments with e-mail
notifications in the Notification Settings section of the Human Task editor. (See
Figure 15–25 on page 15-43.)
In the actionable e-mail reply, the user can add attachments in the e-mail and these
attachments are added as task attachments.
See Also: "Securing Notifications, Making Messages Actionable, and
Sending Attachments" on page 15-45
Sending Inbound Comments
In the actionable e-mail reply, the user can add comments in the e-mail between
Comments[[‘ and ‘]] and those contents are added as task comments. For
example, Comments[[looks good]].
15-82 Oracle BPEL Process Manager Developer’s Guide
Notifications from Workflow Services
Reliability Support
In previous releases, the workflow outbound notification was not reliable. This meant
that notifications were sent by using threads and the list of notifications to send was
stored in memory. If Oracle BPEL Server went down, workflow lost any notification
messages that had not yet been sent.
With release 10.1.3, the workflow outbound notification service uses queues with the
persistency service to send notifications to users.
Whenever a workflow needs to send a notification to a user, it stores the task
information such as notification ID, task ID, version, and so on in the dehydration
store and enqueues the notification ID to the queue. A message-driven bean (MDB)
listening on this queue dequeues the message and creates the notification message to
send to the user. It then uses the notification service to send this message, which uses
the queue with the dehydration store.
See Also: Chapter 14, "Oracle BPEL Process Manager
Notification Service" for additional details about the reliable
notification service
Sending Secure Notifications
If a notification is marked as secure in the Notification Settings section of the Human
Task editor, a default notification message is used. (See Figure 15–25 on page 15-43.)
The default notification message includes a link to the task in the Oracle BPEL
Worklist Application. You must log in to see task details.
See Also: "Securing Notifications, Making Messages Actionable, and
Sending Attachments" on page 15-45
Channels Used for Notifications
The channel through which a user is notified is determined by the notification
preference attribute of the user specified in JAZN. The notification preference is
identified by the attribute orclWorkflowNotificationPreference. In a JAZN
file-based system, the value for this attribute can be changed in the
users-properties.xml file located at SOA_Oracle_
Home\bpel\system\services\config.
In an Oracle Internet Directory-based system, the user properties can be changed using
the Oracle Delegated Administration Service. If this attribute is not set, the e-mail
channel is used as the default.
See Also: Oracle Identity Management Guide to Delegated
Administration for more information on the Oracle Delegated
Administration Service
Sending Reminders
Tasks can be configured to send reminders, which can be based on the time the task
was assigned to a user or the expiration time of a task. The number of reminders and
the interval between the reminders can also be configured. The message used for
reminders is the message that is meant for ASSIGNEES when the task is marked as
ASSIGNED.
You set reminders in the Notification Settings section of the Human Task editor. (See
Figure 15–25 on page 15-43.) Reminder configuration involves these parameters.
Oracle BPEL Process Manager Workflow Services
15-83
End-to-End Workflow Examples
■
■
■
Recurrence — The recurrence specifies the number of times reminders are sent.
The possible values for recurrence are EVERY, NEVER, 0, 1, 2 …, 10.
RelativeDate — The relativeDate specifies if the reminder duration is
computed relative to the assigned date or to the expiration date of the task. The
possible values for the relativeDate are ASSIGNED and EXPIRATION.
Duration — The duration from the relativeDate and the first reminder and
each reminder since then. The data type of duration is xsd:duration, whose
format is defined by ISO 8601 under the form PnYnMnDTnHnMnS. The capital
letters are delimiters and can be omitted when the corresponding member is not
used. Examples include PT1004199059S, PT130S, PT2M10S, P1DT2S, -P1Y, or
P1Y2M3DT5H20M30.123S.
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:
"Setting Up Reminders" on page 15-45
End-to-End Workflow Examples
Table 15–14 shows the end-to-end workflow examples included with Oracle BPEL
Process Manager. Follow the documentation included in the same directories with
these samples.
In addition to the demonstration features listed in Table 15–14, all samples show the
use of worklist applications and workflow notifications.
Table 15–14
End-to-End Examples
Sample
Location
Description
AutoLoanDemo
SOA_Oracle_
Review and approve a
Home\bpel\sample loan request
s\demos
DocumentReview SOA_Oracle_
Review and approve a
Home\bpel\sample document
s\demos
15-84 Oracle BPEL Process Manager Developer’s Guide
Demonstrates
■
■
■
■
Single approval
Integration with a
business rule engine
Group vote
Adding attachments
to tasks
End-to-End Workflow Examples
Table 15–14
(Cont.) End-to-End Examples
Sample
Location
Description
The ExpenseRequest
ExpenseRequestA SOA_Oracle_
pproval
Home\bpel\sample business process is
used to approve and
s\demos
reject an expense
request from an
employee
Demonstrates
■
■
■
HelpDeskService
Request
SOA_Oracle_
Approval of a help
Home\bpel\sample desk service
s\demos
■
■
■
LoanDemoPlus
Approval of a loan
SOA_Oracle_
Home\bpel\sample application
s\demos
■
■
■
OrderApproval
Approve or reject a
SOA_Oracle_
Home\bpel\sample purchase order
s\tutorials\127.
OrderBookingTuto
rial
VacationRequest
Vacation request
SOA_Oracle_
Home\bpel\sample approval or denial
s\demos
Management chain
approval
Use of decision
service to determine
the levels of
approvals required
for a particular
expense request
Microsoft Office
integration
Adhoc approval
Custom worklist user
interface
Promotion of task
payload message
attributes
Group assignment (in
StarLoan process)
Custom worklist user
interface (in
LoanFlowPlusUI and
StarLoanUI)
FYI tasks (in
LoanFlowPlus
process)
■
Sequential workflow
■
Simple workflow
Vacation Request Example
This example describes how to create a vacation request business process. In this
business process, the manager of a user requesting a vacation approves or rejects the
request. The approval or rejection is a one-step process.
This example highlights the use of the following:
■
Modeling a single approval workflow using Oracle JDeveloper
■
Using the Oracle BPEL Worklist Application to view and respond to tasks
Prerequisites
This example assumes the following:
■
You are familiar with basic BPEL constructs, including BPEL activities and partner
links, and basic XPath functions. Familiarity with Oracle JDeveloper—the
environment for creating and deploying BPEL processes—is also assumed.
Oracle BPEL Process Manager Workflow Services
15-85
End-to-End Workflow Examples
■
You must configure the e-mail server settings for the account Default to enable
e-mail notifications. The Default account is used to send e-mails. The e-mail
server configuration is in
SOA_Oracle_Home\bpel\system\services\config\ns_emails.xml
The following code example from the file shows the parameters that may require
configuration in bold.
<EmailAccount>
<Name>Default</Name>
<GeneralSettings>
<FromName>Oracle BPM</FromName>
<FromAddress>accountId@yourdomain.com</FromAddress>
</GeneralSettings>
<OutgoingServerSettings>
<SMTPHost>yourdomain.com</SMTPHost>
<SMTPPort>25</SMTPPort>
</OutgoingServerSettings>
<IncomingServerSettings>
<Server>yourdomain.com</Server>
<Port>110</Port>
<Protocol>pop3</Protocol>
<UserName>accountId</UserName>
<Password ns0:encrypted="false"
xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
password</Password>
<UseSSL>false</UseSSL>
<Folder>Inbox</Folder>
<PollingFrequency>1</PollingFrequency>
<PostReadOperation>
<MarkAsRead/>
</PostReadOperation>
</IncomingServerSettings>
</EmailAccount>
■
You must set the NotificationMode parameter to one of the following values in
the ns_emails.xml file:
–
ALL – If you have the e-mail, SMS, voice, fax, and pager channels set up.
–
EMAIL – If you have only the e-mail channel set up.
For example:
<EmailAccounts xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"
EmailMimeCharset=""
NotificationMode="EMAIL">
■
You must change the e-mail address for the user jstein to an accessible e-mail
address. If the XML-based JAZN provider is used, these properties can be changed
in:
SOA_Oracle_Home\bpel\system\services\config\users-properties.xml
The following XML segment from the users-properties.xml file shows
where the e-mail is configured:
<userObject>
<name>jstein</name>
<description>Demo User</description>
<email>user1@dlsun4254.us.oracle.com</email>
<title>Manager2</title>
15-86 Oracle BPEL Process Manager Developer’s Guide
End-to-End Workflow Examples
<firstName>John</firstName>
<lastName>Steinbeck</lastName>
<manager>wfaulk</manager>
<timeZone>America/Los_Angeles</timeZone>
<languagePreference>en-US</languagePreference>
<notificationPreferences>Mail</notificationPreferences>
</userObject>
■
You must restart Oracle BPEL Process Manager after making any of the preceding
changes.
Modeling the Vacation Request Process
In this phase of the tutorial, you create a new project, OrderApproval, and define the
human workflow process, a single approver workflow in which the order is approved
or rejected. The order is first assigned to the Supervisor role. After a user with the
Supervisor role approves the order, it is sent to the user’s manager for final approval.
This section contains these tasks:
■
Creating the Vacation Request Process and Importing the Schema
■
Adding a Human Task to the Order Approval Process
■
Assigning Input and Output Parameters for the Human Task
■
Creating a Task Form for the Worklist
■
Modeling the Task Outcome
■
Validating, Compiling, and Deploying the Order Approval Process
■
Running the Order Approval Process
Creating the Vacation Request Process and Importing the Schema
1.
Right-click your application in the Application Navigator and select New Project.
2.
Select BPEL Process Project.
3.
Create an asynchronous BPEL process with the name VacationRequest.
4.
Click Next.
5.
Click the flashlight next to Input Schema Element to browse for
VacationRequest.xsd in
SOA_Oracle_Home\bpel\samples\demos\VacationRequest\bpel
6.
Click Open.
The Type Chooser window appears.
7.
Expand and select Imported Schemas > VacationRequest.xsd >
VacationRequestProcessRequest.
8.
Click OK.
9.
Click the flashlight next to Output Schema Element.
10. Expand and select Imported Schemas > VacationRequest.xsd >
VacationRequestProcessResponse.
11. Click Finish.
The schemas are now imported into the project. VacationRequest.xsd appears
under VacationRequest > Integration Content > Schemas in the Application
Oracle BPEL Process Manager Workflow Services
15-87
End-to-End Workflow Examples
Navigator, and under Schemas in the Structure section. The BPEL process—a
Receive activity (receiveInput) and an Invoke activity (callbackClient)—is
displayed.
12. Select Save from the File main menu.
Adding a Human Task to the Order Approval Process
Summary: When you define the human task, the
VacationApproval.task file—the task configuration metadata
file—is created.
1.
Drag and drop a Human Task activity between receiveInput and callbackClient.
2.
Click the Create Task Definition icon (second icon).
3.
Enter VacationApproval for the human task name and click OK. (Accept the
default location.)
The VacationApproval.task file is created.
The Human Task editor is displayed.
4.
For Title, enter Vacation Approval.
5.
Accept the default values for Priority and Outcomes.
6.
For Parameters, click the + icon on the right side of the window.
The Add Task Parameter window is displayed.
7.
Click Element and then the flashlight icon.
8.
In the Type Chooser window, expand and select Project Schema Files >
VacationRequest.xsd > VacationRequestProcessRequest, and click OK.
15-88 Oracle BPEL Process Manager Developer’s Guide
End-to-End Workflow Examples
9.
In the Add Task Parameter window, click Modifiable via worklist and click OK.
This ensures that you can modify task data using the Oracle BPEL Worklist
Application.
10. In the Assignment and Routing Policy section, click the + icon on the right side of
the window.
The Add Participant Type window is displayed.
11. For Type, select Single Approver.
This participant type acts alone on the task.
12. For Label, enter Vacation Approver.
13. Click By expression.
In this example, you assign the task to the manager of the vacation requester.
14. Click the icon to the right of the Dynamic User Xpath field to display the
Expression Builder window.
15. Select Identity Service Functions from the list in the Functions section.
16. Double-click getManager.
17. Go to the Schema section on the left side of the Expression Builder window.
18. Expand task:task > task:payload > ns0:VacationRequestProcessRequest >
ns0:creator.
19. Click Insert Into Expression.
The Expression Builder window appears as follows:
Oracle BPEL Process Manager Workflow Services
15-89
End-to-End Workflow Examples
20. Click OK to return to the Add Participant Type window.
21. Click OK to return to the Human Task editor.
22. Click the + sign to expand the Expiration and Escalation Policy section.
23. Select Expire after from the drop-down list.
24. Click Fixed Duration and select 1 from the Day list.
25. Select Save from the File main menu.
26. Click the X next to VacationApproval.task to close the Human Task editor.
Assigning Input and Output Parameters for the Human Task
Summary:
1.
Map the fields to the variables in the BPEL process.
Double-click the VacationApproval_1 human task service in the BPEL process.
This displays the Human Task window.
2.
In the Task Title field, enter the word for after the words Vacation Approval.
3.
Click the icon at the right to display the Expression Builder window.
4.
In the BPEL Variables section, expand and select inputVariable> payload >
client:VacationRequestProcessRequest > client:creator.
5.
Click Insert Into Expression.
15-90 Oracle BPEL Process Manager Developer’s Guide
End-to-End Workflow Examples
The XPath expression appears in the Expression section.
6.
Click OK.
The XPath expression is appended to the task title.
7.
Click the icon to the right of the Initiator field to display the Expression Builder
window.
8.
Repeat Steps 4 through 6 to insert the same XPath expression in the Initiator field.
9.
Click the flashlight icon under the BPEL Variable column.
The Task Parameters window appears.
10. In the Task Parameters window, expand and select Variables > inputVariable >
payload > client:VacationRequestProcessRequest.
11. Click OK.
12. In the Human Task window, click OK.
Oracle BPEL Process Manager Workflow Services
15-91
End-to-End Workflow Examples
13. Select Save from the File main menu.
Creating a Task Form for the Worklist
Summary: An autogenerated task form, payload-body.jsp, is
created.
1.
In the Application Navigator, right-click the VacationApproval folder and select
Auto Generate Simple Task Form.
This automatically generates a task form file.
2.
Close payload-body.jsp by clicking the X sign at the top.
Modeling the Task Outcome
Summary: The Switch activity reflects the possible outcomes, or
cases, specified previously, Approve and Reject. It also has an
Otherwise case to represent other outcomes, such as errored, stale, or
expired. Inside each of the cases, you can add activities to complete
modeling of the business process. The copyPayloadFromTask Assign
activities copy the payload back to its source.
1.
Double-click VacationRequest.bpel.
2.
Expand the taskSwitch Switch activity.
3.
Drag and drop an Assign activity to below the copyPayloadFromTask Assign
activity in the <case Task outcome is APPROVE> section of the Switch activity.
4.
Double-click the Assign icon to display the Assign window.
5.
Click the General tab.
6.
Enter assignVacationApproval1 in the Name field.
7.
Click Apply.
8.
Click the Copy Operation tab.
9.
Click Create and select Copy Operation.
10. Enter the following details:
Field
Value
From
■
Type
Expression
■
Expression
string(’Approved’)
■
Type
Variable
■
Variables
Expand and select Variables > outputVariable > payload >
client:VacationRequestProcessResponse > client:result
To
Note: The namespace number values (for example, client, ns1) can
vary. Use the namespace values that automatically appear.
11. Click OK to close the Create Copy Operation window and the Assign window.
15-92 Oracle BPEL Process Manager Developer’s Guide
End-to-End Workflow Examples
12. Repeat Steps 3 through 11 to create an Assign activity below the
copyPayloadFromTask Assign activity in the <case Task outcome is REJECT>
section. Enter the same details as described above, with the following exceptions:
■
Name it assignVacationApproval2
■
Set the Expression field to string(’Rejected’)
13. Repeat Steps 3 through 11 to create an Assign Activity below the
copyPayloadFromTask Assign activity in the <otherwise> section. Enter the same
details as described above, with the following exceptions:
■
Name it assignVacationApproval3
■
Set the Expression field to string(’Rejected’)
14. The process looks as follows:
15. Select Save from the File main menu.
16. Click the - sign to close the taskSwitch Switch activity.
Validating, Compiling, and Deploying the Order Approval Process
1.
Go to the Application Navigator section.
2.
Right-click VacationApproval.
3.
Select Deploy > my_integration_server_connection > Deploy to default domain.
This compiles the BPEL process. Check for errors by clicking the buttons at the
bottom of the window. If there are no errors, deployment was successful.
Running the Order Approval Process
1.
Log into Oracle BPEL Control by selecting Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process Manager > BPEL Control.
The Dashboard tab of Oracle BPEL Control appears.
2.
Enter the following details to log into Oracle BPEL Control and click Login:
Oracle BPEL Process Manager Workflow Services
15-93
End-to-End Workflow Examples
Field
Value
Username
oc4jadmin
Password
welcome1
3.
Click VacationApproval in the Deployed BPEL Processes list.
4.
Enter jcooper for the creator of the vacation.
5.
Enter appropriate values for the remaining fields.
6.
Click Post XML Message.
The BPEL Processes tab displays a message similar to the following:
Test Instance Initiated
7.
Click the Instances tab at the top.
8.
Click the OrderApproval instance.
A message appears indicating that the instance is active.
9.
Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process
Manager > Sample Worklist Application to access the login window for Oracle
BPEL Worklist Application:
10. Log in as jstein/welcome1.
The user jstein is the manager of jcooper. This displays Oracle BPEL Worklist
Application. A task waiting to be approved appears.
11. Select Claim in the Actions list for the task to approve.
12. Click Go.
The task details and payload information appear.
13. Review the information. For example, the following information appears if you
copied and pasted in the contents of OrderBookingPO_1.xml.
14. Select Approve from the Task Action list and click Go.
15. Log out as user jcooper.
16. Log into Oracle BPEL Worklist Application as jstein/welcome1.
17. Select Approve from the Actions list and click Go.
After processing, no tasks appear in Oracle BPEL Worklist Application.
18. Log out.
19. Return to Oracle BPEL Control.
20. Click the Instances tab at the top.
21. Click the VacationApproval instance.
A message appears indicating that the instance has completed.
22. Click the Audit and Flow links to observe additional details about the completed
OrderApproval process.
15-94 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Workflow Services
Workflow services and functions are responsible for a variety of tasks. This section
describes the responsibilities of the following workflow services:
■
EJB, SOAP, and Java Support for the Workflow Services
■
Security Model for Services
■
Task Service
■
Task Query Service
■
Identity Service
■
Notification Service
■
Task Metadata Service
■
User Metadata Service
■
Runtime Config Service
See Also:
"Workflow Services Components" on page 15-6
EJB, SOAP, and Java Support for the Workflow Services
Table 15–15 lists the type of SOAP, EJB, and Java support provided for the task
services.
Table 15–15
EJB, SOAP, and Java Support
Service Name
Supports SOAP Supports
Supports Supports Plain
Web Services
Remote EJB Local EJB Java APIs
Task Service
Yes
Yes
Yes
Task Query Service
Yes
Yes
Yes
Yes
Task Metadata Service
Yes
Yes
Yes
Yes
Task Reports Service
Yes
User Metadata Service
Yes
Yes
Yes
Yes
Runtime Config Service
Yes
Yes
Yes
Yes
Identity Service:
■
■
BPM Authentication
Service
Yes
Yes
BPM Authorization
Service
Yes
Yes
Table 15–16 lists the location for the SOAP WSDL file for each task service.
Table 15–16
SOAP WSDL Location for the Task Services
Service name
SOAP WSDL location
Task Service
http://host:port/integration/services/TaskServi
ce/TaskServicePort?WSDL
Task Metadata Service
http://host:port/integration/services/TaskMetad
ataService/TaskMetadataServicePort?WSDL
Task Query Service
http://host:port/integration/services/TaskQuery
Service/TaskQueryService?WSDL
Oracle BPEL Process Manager Workflow Services
15-95
Workflow Services
Table 15–16
(Cont.) SOAP WSDL Location for the Task Services
Service name
SOAP WSDL location
User Metadata Service
http://host:port/integration/services/UserMetad
ataService/UserMetadataService?WSDL
Runtime Config Service
http://host:port/integration/services/RuntimeCo
nfigService/RuntimeConfigService?WSDL
Identity Service
http://host:port/integration/services/IdentityS
ervice/configuration?WSDL
http://host:port/integration/services/IdentityS
ervice/identity?WSDL
Notification Service
http://host:port/integration/services/Notificat
ionService/NotificationService?WSDL
Security Model for Services
With the exception of the identity service, all services that use the above-mentioned
APIs (SOAP, remote EJB, local EJB, and Java WSIF) require authentication to be
invoked. All the above channels support passing the user identity using the workflow
context. The workflow context contains either of the following:
■
Login and password
■
Token
The task query service exposes the authenticate operation that takes the login and
password and returns the workflow context used for all services. Optionally, with each
request, you can pass the workflow context with the login and password.
The authenticate operation also supports the concept of creating the context on behalf
of a user with the admin ID and admin password. This enables you to create the
context for a logged-in user to the Oracle BPEL Worklist Application if the password
for that user is not available.
Security in SOAP Web Services
SOAP Web services also support Web service security. When Web service security is
used, the workflow context does not need to be present in the SOAP input. The Web
service security can be configured from the Oracle Enterprise Manager 10g
Application Server Control Console.
Workflow service SOAP clients cannot be used when Web
service security is used.
Note:
See Also: "Configuring Single Sign-on Using SAML" in the Oracle
Application Server Web Services Security Guide for details about
propagating the identity of a user from a Web application to the Web
service
Security in EJBs
The workflow service EJBs also take a workflow context parameter that is used for
authentication and authorization.
15-96 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Creating Workflow Context on Behalf of a User
The authenticate API operation on the task query service can create the workflow
context on behalf of a user by passing the user ID and password of an admin user in
the request. An admin user is a user who has the BPMWorkflowAdmin role. This
created context is as if it was created using the password on behalf of the user.
In this example, the workflow context is created for user jcooper.
ITaskQueryService taskQueryService = ….
String realm = …;
IWorkflowContext wfCtx =
taskQueryService.authenticate(‘bpeladmin’, ‘welcome1’, realm, ‘jcooper’);
Task Service
The task service exposes operations to act on tasks. Table 15–17 describes the
operations of the task service. Package oracle.bpel.services.workflow.task
corresponds to the task service.
Table 15–17
Task Service Methods
Method
Description
acquireTask
Acquire a task.
acquireTasks
Acquire a set of tasks.
addAttachment
Add an attachment to a task.
addComment
Add a comment to a task.
delegateTask
Delegate a task to a different user. Both the current assignee and
the user to whom the task is delegated can view and act on the
task.
errorTask
Cause the task to error. This operation is typically used by the
error assignee.
escalateTask
Escalate a task. The default escalation is to the manager of the
current user. This can be overridden using escalation functions.
getApprovers
Get the previous approvers of a task.
getFutureParticipants
Get the future participants of a task. The future participants are
returned in the form of a routing slip that contains simple
participants — (participant node and parallel nodes that
contain routing slips in them).
getUsersToRequestInfo
ForTask
Get the users from whom a request for information can be
requested.
initiateTask
Initiate a task.
mergeAndUpdateTask
Merge and update a task. Use this operation when a partial task
should be updated. A partial task is one in which not all the
task attributes are present. In this partial task, only the
following task attributes are interpreted:
overrideRoutingSlip
■
Task payload
■
Comments
■
Task state
■
Task outcome
Override the routing slip of a task instance with a new routing
slip. The current task assignment is nullified and the new
routing slip is interpreted as its task is initiated.
Oracle BPEL Process Manager Workflow Services
15-97
Workflow Services
Table 15–17
(Cont.) Task Service Methods
Method
Description
pushBackTask
Push back a task to the previous approver or original assignees.
The original assignees do not need to be the approver as they
may have reassigned the task, escalated the task, and so on. The
property pushbackAssignee in wf_config.xml controls
whether the task is pushed back to the original assignees or the
approvers.
reassignTask
Reassign a task.
reinitiateTask
Reinitiate a task. Reinitiating a task causes a previously
completed task to be carried forward so that the history,
comments, and attachments are carried forward in a new task.
releaseTask
Release a previously acquired task.
releaseTasks
Release a set of previously acquired tasks.
removeAttachment
Remove a task attachment.
renewTask
Renew a task to extend the time it takes to expire.
requestInfoForTask
Request information for a task.
requestInfoForTaskWith Request information for a task with reapproval. For example,
Reapproval
assume jcooper created a task and jstein and wfaulk
approved the task in the same order. When the next approver,
cdickens, requests information with reapproval from
jcooper, and jcooper submits the information, jstein and
wfaulk approve the task before it comes to cdickens. If
cdickens requests information with reapproval from jstein,
and jstein submits the information, wfaulk approves the
task before it comes to cdickens.
resumeTask
Resume a task. Operations can only be performed by the task
owners (or users with the BPMWorkflowSuspend privilege) to
remove the hold on a workflow. After a workflow is resumed,
actions can be performed on the task.
resumeTasks
Resume a set of tasks.
routeTask
Allow a user to route the task in an adhoc fashion to the next
user(s) who must review the task. The user can specify to route
the tasks in sequential, parallel, or simple assignment. Routing
a task is permitted only when the workflow permits adhoc
routing of the task.
skipCurrentAssignment
Skip the current assignment and move to the next assignment
or pick the outcome as set by the previous approver if there are
no more assignees.
submitInfoForTask
Submit information for a task. This action is typically
performed after the user has made the necessary updates to the
task or has added comments or attachments containing
additional information.
suspendTask
Allows task owners (or users with the BPMWorkflowSuspend
privilege) to put a workflow on hold temporarily. In this case,
task expiration and escalation do not apply until the workflow
is resumed. No actions are permitted on a task that has been
suspended (except resume and withdraw).
suspendTasks
Suspend a set of tasks.
updateOutcomeOfTasks
Update the outcome of a set of tasks.
updateTask
Update the task.
updateTaskOutcome
Update the task outcome.
15-98 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Table 15–17
(Cont.) Task Service Methods
Method
Description
updateTaskOutcomeAndR
oute
Update the task outcome and route the task. Routing a task
allows a user to route the task in an adhoc fashion to the next
user(s) who must review the task. The user can specify to route
the tasks in sequential, parallel, or simple assignment. Routing
a task is permitted only when the workflow permits adhoc
routing of the task.
withdrawTask
The creator of the task can withdraw any pending task if they
are no longer interested in sending it further through the
workflow. A task owner can also withdraw a task on behalf of
the creator. When a task is withdrawn, the business process is
called back with the state attribute of the task set to
Withdrawn.
withdrawTasks
Withdraw a set of tasks.
See Also: Oracle BPEL Process Manager Workflow Services API
Reference located in the SOA_Oracle_Home\bpel\docs\workflow
directory
Task Query Service
The task query service queries tasks based on a variety of search criterion such as
keyword, category, status, business process, attribute values, history information of a
task, and so on. Table 15–18 describes the operations of the task query service. Package
oracle.bpel.services.workflow.query corresponds to the task query service.
Table 15–18
Task Query Service Methods
Method
Description
authenticate
Authenticates a user with the identity authentication service
and passes back a valid IWorkflowContext object.
Authentication can optionally be made on behalf of another
user.
createContext
Creates a valid IWorkflowContext object from a
preauthenticated HTTP request.
getWorkflowContext
Gets a workflow context with the specified context token.
destroyWorkflowContext Cleans up a workflow context that is no longer needed. This
method is typically used when a user logs out.
getTaskDetailsById
Gets the details of a specific task from the task's taskId
property.
getTaskDetailsByNumber Gets the details of a specific task from the task's task number
property.
getTaskHistory
Gets the last of the task versions for the specified task ID.
getTaskVersionDetails
Gets the specific task version details for the specified task ID
and version number.
Oracle BPEL Process Manager Workflow Services
15-99
Workflow Services
Table 15–18
(Cont.) Task Query Service Methods
Method
Description
queryTasks
Returns a list of tasks that match the specified filter conditions.
Tasks are listed according to the ordering condition specified (if
any). The entire list of tasks matching the criteria can be
returned or clients can execute paging queries, in which only a
specified number of tasks in the list are retrieved. The filter
conditions are as follows:
■
assignmentFilter — Filters tasks according to whom
the task is assigned, or who created the task. Possible
values for the assignment filter are as follows:
ADMIN — No filtering; returns all tasks regardless of
assignment or creator.
ALL — No filtering; returns all tasks regardless of
assignment or creator.
CREATOR — Returns tasks where the context user is the
creator.
GROUP — Returns tasks that are assigned to one of the
groups of which the context user is a member.
MY — Returns tasks that are assigned to the context user.
MY_AND_GROUP — Returns tasks that are assigned to
either the context user, or one of the groups of which they
are a member.
OWNER — Returns tasks where the context user is the task
owner.
PREVIOUS — Returns tasks the context user previously
updated.
REPORTEES — Returns tasks that are assigned to reportees
of the context user.
■
■
queryViewTasks
keywords — An optional search string. This only returns
tasks where the string is contained in the task title, task
identification key, or one of the task text flex fields.
predicate — An optional
oracle.bpel.services.workflow.repos.Predica
te object that allows clients to specify complex, SQL-like
query predicates.
Returns a list of tasks according to the criteria in the specified
view. The entire list or paged list of tasks can be returned.
Clients can specify additional filter and ordering criteria to
those in the view.
See Also: Oracle BPEL Process Manager Workflow Services API
Reference located in the SOA_Oracle_Home\bpel\docs\workflow
directory
Identity Service
This section describes the identity service component of Oracle BPEL Process
Manager. The identity service is a thin Web service layer on top of the Oracle
Application Server 10g security infrastructure, namely OracleAS JAAS Provider
(JAZN), or any custom user repository. It enables authentication and authorization of
users and the lookup of user properties, roles, group memberships, and privileges.
15-100 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Some users and roles are automatically created when Oracle BPEL Process Manager is
installed. Seeded users include:
■
guest
■
default
■
bpeladmin
■
oc4jadmin
The identity service predefines the following roles, which can be granted to users to
perform workflow-related operations:
■
PUBLIC—This role is an implicit JAZN role; it does not need to be granted
explicitly to any of the users. If any user can authenticate with the worklist, then
they can see tasks assigned to them or groups they belong to and act on these
tasks.
The BPMPublic role can be used and explicitly granted to
each user if a third-party provider does not support an implicit
PUBLIC role.
Note:
■
■
■
■
■
■
BPMWorkflowReassign—This role enables a user to reassign tasks to any other
user in the organization. A manager can always delegate tasks to any users under
him in the organization hierarchy without any Reassign privileges. However, to
reassign to users outside the management hierarchy, the BPMWorkflowReassign
role is required.
BPMWorkflowSuspend—This role enables users to suspend a process. If a
process is suspended, then the expiration time does not apply. When the process is
resumed, the expiration date is recomputed. Users cannot suspend the workflow if
the process designer has designated Suspend as a restricted action, even if the
user has the BPMWorkflowSuspend role.
BPMWorkflowViewHistory—In general, a user can see only the task assignment
sequence as part of their worklist. This role enables a user to drill down further
into the BPEL business process audit trail from the task approval sequence.
BPMWorkflowAdmin—This role enables a user to perform system actions on any
workflow in the system. This role does not allow you to change the outcome of the
task (such as approve or reject); it only allows you to perform actions such as
delegate, escalate, and suspend. Only the task assignee or the task owner can
change the outcome of the task.
BPMSystemAdmin—Both BPMWorkflowAdmin and BPMSystemAdmin have the
same level of workflow privileges.
BPMDefaultDomainAdmin—This role provides a user with access to the default
domain through Oracle BPEL Control.
See Also: Oracle BPEL Process Manager Administrator’s Guide for
instructions on configuring the identity service and additional details
about the BPMSystemAdmin and BPMDefaultDomainAdmin roles
Some of these roles are nested. The BPMWorkflowReassign,
BPMWorkflowSuspend, and BPMWorkflowViewHistory roles are granted to the
BPMWorkflowAdmin role. The BPMSystemAdmin role is granted to the seeded
bpeladmin user.
Oracle BPEL Process Manager Workflow Services 15-101
Workflow Services
The following table represents the relationship between the grantees and roles:
Role\Grantee
bpeladmin
default
guest
BPMWorkflowAdmin
BPMSystemAdmin
BPMSystemAdmin
Directly
--
--
--
--
BPMWorkflowAdmin
Indirectly through
BPMSystemAdmin
--
--
--
Directly
BPMWorkflowReassign
Indirectly through
BPMSystemAdmin
--
--
Directly
Indirectly through
BPMWorkflowAdmin
BPMWorkflowSuspend
Indirectly through
BPMSystemAdmin
--
--
Directly
Indirectly through
BPMWorkflowAdmin
BPMWorkflowViewHistory Indirectly through
BPMSystemAdmin
--
--
Directly
Indirectly through
BPMWorkflowAdmin
--
Directly
BPMDefaultDomainAdmin
Indirectly through
BPMSystemAdmin
Directly --
Creating Users and Groups
You use directory-specific tools to create realms, users, or groups. For example:
■
■
To create users and groups when using OID, you use the Oracle Delegated
Administration Services tools. See Oracle Identity Management Guide to Delegated
Administration for more information.
To create user and group credentials when using the XML-based JAZN provider,
you use the JAZN Admintool to modify the jazn-data.xml file. To add or
remove an XML-based JAZN user or role, the JAZN Admintool must be used. You
can manually edit the users-properties.xml file to specify detailed user
properties that JAZN does not support.
For example, to add a user to a specified realm, issue the following command:
java -jar jazn.jar -user adminUser -password adminPassword
-adduser realmName newUser newUserPassword
The JAZN Admintool provides different command options. You can list all the
options and their syntax with the -help option, as in:
java -jar jazn.jar -help
■
If you are using a third-party LDAP server or a custom user repository, you must
use the specific tools available for that directory.
See Also: Oracle Containers for J2EE Security Guide for instructions on
using the JAZN Admintool
Identity Service Providers
Oracle BPEL Process Manager identity service supports three types of providers:
JAZN, third-party LDAP, or custom plug-in, as shown in Figure 15–36.
15-102 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Figure 15–36
Identity Service Providers
Oracle BPEL Process Manager
Identity Service
Provider Plug-ins
JAZN Provider
XML-Based
Provider
LDAP-Based
Provider (OID)
Third-party
LDAP
Directories
CUSTOM
Repository
Plug-ins
The identity service providers perform the following operations:
■
■
■
Authentication—authenticates users given their username and password
Authorization—determines roles and group memberships for a specific user.
These roles are then used to control access to various work items and operations
on the worklist.
Retrieve user properties—includes contact information such as first name, last
name, phone, e-mail, preferred notification channel, language preference, time
zone, and organization details such as manager name and reportees.
The JAZN Provider The JAZN provider mode, which is preconfigured, delegates all
authentication and authorization inquires to the JAZN layer. Two JAAS providers are
supplied as part of the OC4J security infrastructure: the XML-based file and
LDAP-based OID.
■
■
XML-Based JAZN Provider Type — The XML-based provider type is used for
lightweight storage of information in the XML files. All the user names, roles, and
permissions are stored in XML files. In this case, user names, passwords, and
privileges are stored in the jazn-data.xml file. In addition, Oracle BPEL Process
Manager uses a user-properties.xml file that works in conjunction with this
file to store detailed user properties such as name, e-mail, phone, and manager.
LDAP-Based JAZN Provider Type (Oracle Internet Directory) — The LDAP-based
provider type is based on the Lightweight Directory Access Protocol (LDAP) for
centralized storage of information in a directory. OID is a standard LDAP-based
directory that provides a single, centralized repository for all user data. It allows
sites to manage user identities, roles, authorization, and authentication credentials,
as well as application-specific preferences and profiles in a single repository.
Third-Party LDAP Server The third-party LDAP provider mode enables identity service
to work with third-party LDAP servers such as Sun Directory Server (iPlanet),
Microsoft Active Directory, or openLDAP. In this mode, identity service assumes that
the directory is the central repository of all user data, including authentication
credentials, roles, and profiles. The standard organizationalPerson,
inetOrgPerson objects from the LDAP schema retrieve these details.
See Also:
Oracle Application Server Containers for J2EE User’s Guide
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. The custom identity
Oracle BPEL Process Manager Workflow Services 15-103
Workflow Services
service plug-in must implement the BPMIdentityService interface (see Javadoc).
This identityservice class name must be registered in is_config.xml.
See Also:
■
■
■
"User and Role Properties" on page 15-104 for more information.
Identity service configuration instructions in Oracle BPEL Process
Manager Administrator’s Guide
See SOA_Oracle_
Home\bpel\docs\workflow\oracle\tip\pc\services\id
entity for Javadoc on the BPMIdentityService interface
User and Role Properties
The identity service supports the following user properties:
■
Display name
■
Given name, middle name, and last name
■
Description
■
Title
■
E-mail address
■
Telephone number
■
Home phone number
■
Mobile phone number
■
Fax number
■
Pager number
■
Manager ID
■
Owners (applies to groups and roles, but not users)
■
Time zone
■
Language preference (Java locale)
■
Notification preference (preferred notification channel)
The preceding properties are optional for Oracle BPEL Process Manager users.
However, some features, such as task notification, are not available if the contact
information is not present in the directory or in the users-properties file for the
JAZN XML-based provider. Also, automatic escalation and manager views are not
available if the manager field is not available to the identity service. If the user is not
listed among the owners of the group, they cannot modify the rule defined for the
group.
See Also: The service configuration chapter of Oracle BPEL Process
Manager Administrator’s Guide for instructions on defining group
ownership
The following OID objectClasses specify user and role properties such as mail,
manager, and telephoneNumber.
■
top
■
person
15-104 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
■
■
■
■
■
–
cn
–
sn
–
description
–
telephoneNumber
organizationalPerson
–
title
–
telephoneNumber
–
facsimileTelephoneNumber
inetOrgPerson
–
uid
–
displayName
–
givenName
–
manager
–
mail
–
homePhone
–
mobile
–
pager
–
preferredLanguage
orclUserV2
–
middleName
–
orclTimeZone
–
orclWorkflowNotificationPref
groupOfUniqueNames
–
description
–
owner
–
uniqueMember
orclGroup
–
displayName
–
mail
The identity service maintains a connection pool to retrieve these properties from the
LDAP directory.
If you are using the XML-based JAZN provider, the same entries are represented as
XML elements in the users-properties.xml file in
SOA_Oracle_Home\bpel\system\services\config
Multirealm Support
The identity service enables you to specify multiple configuration settings (to express
identity contexts, supported realms, and so on) in the is_config.xml file. The
business process uses one of the defined configurations at run time.
Oracle BPEL Process Manager Workflow Services 15-105
Workflow Services
The configuration must specify the realm name to enable a business process to resolve
the context at run time. For the JAZN provider, the realm name must match one of
supported JAZN realm names. Otherwise, a run time exception is thrown. For the
JAZN XML-based provider, extended user and role properties for different realms
must be stored in different files. For the LDAP provider, the realm name can be any
unique name, while the context is defined by the LDAP URL, user search base, and
role search base nodes in the LDAP server tree. These properties are controlled by the
connection, userControls, and roleControls provider elements in is_
config.xml.
If the is_config.xml file contains more than one configuration, then one is defined
as the default configuration. The default context is used by the BPEL process if no
specific context information is found at run time. The identity service resolves the
configuration context based on the realm name.
See Also: The service configuration chapter of the Oracle BPEL
Process Manager Administrator’s Guide for configuration instructions
Authentication, Authorization, and Identity Service Providers
The identity service supports authentication, authorization, and identity service
providers. The identity service provider is the default pseudoservice provider. It must
be defined for each configuration in the is_config.xml file. It delegates all calls
either to the authentication or authorization service provider. By default, all three
service providers share the same context setting defined in the identity provider.
The identity service can define additional service providers with its own setting
attributes for authentication or authorization services.
If the provider service attribute is set to Authentication, the setting and the
provider context are used only for all authentication calls for the configuration. If the
provider service attribute is set to Authorization, the setting and provider context
are used only for authorization calls.
See Also: The multiple service providers section of the service
configuration chapter of the Oracle BPEL Process Manager
Administrator’s Guide for an example of a configuration with two
providers:
■
■
The JAZN XML-based identity service provider is used for all
calls, except authentication
The custom plug-in provider is used only for authentication calls
Notification Service
The notification service exposes operations that can be invoked from the BPEL
business process to send notifications through e-mail, voice, fax, pager, or short
message service (SMS) channels.
See Also:
■
"Notifications from Workflow Services" on page 15-79
■
Chapter 14, "Oracle BPEL Process Manager Notification Service"
■
Oracle BPEL Process Manager Administrator’s Guide for instructions
on configuring notification service delivery channels
15-106 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Task Metadata Service
Task metadata service exposes operations to retrieve metadata information related to a
task. Table 15–19 describes these methods. Package
oracle.bpel.services.workflow.metadata corresponds to the task metadata
service.
Table 15–19
Task Metadata Service Methods
Method
Description
getOutcomes
Get the permitted outcomes of a task. The outcomes are returned
with their display values.
getResourceBundleInfo Get the resource bundle information of the task. The resource
bundle information contains the location and the name of the
bundle.
getRestrictedActions
Get the actions that are restricted for a particular task.
getTaskAttributes
Get the task message attributes.
getTaskAttributesForT Get the message attributes for a particular task definition.
askDefinition
getTaskDefinition
Get the task definition associated with the task.
getTaskDefinitionById Get the task definition by the task definition ID.
getTaskDefinitionOutc Get the outcomes given the task definition ID.
ome
getTaskDisplay
Get the task display for a task.
getTaskDisplayRegion
Get the task display region for a task.
getVersionTrackedAttr Get the task attributes that when changed causes a task version
s
creation.
listTaskMetadata
List the task definitions in the system.
See Also: Oracle BPEL Process Manager Workflow Services API
Reference located in the SOA_Oracle_Home\bpel\docs\workflow
directory
User Metadata Service
The user metadata service provides methods for managing metadata specific to
individual users and groups. It is used for getting and setting user worklist
preferences, managing user custom views, and managing workflow rules for users
and groups.
For most methods in the user metadata service, the authenticated user can query and
update their own user metadata. However, they cannot update metadata belonging to
other users.
In the case of group metadata (for example, workflow rules for groups), only a user
designated as an owner of a group (or a BPMWorkflowAdmin user) can query and
update the metadata for that group. However, a user that has been granted the
BPMWorkflowAdmin role can query and update metadata for any user or group.
Table 15–20 describes the methods in the user metadata service. Package
oracle.bpel.services.workflow.user corresponds to the user metadata
service.
Oracle BPEL Process Manager Workflow Services 15-107
Workflow Services
Table 15–20
User Metadata Service Methods
Method
Description
setVacationInfo
Sets a date range over which the user is unavailable for the
assignment of tasks. (Dynamic assignment functions do not assign
tasks to a user that is on vacation.)
getVacationInfo
Retrieves the date range (if any) during which a user is unavailable
for the assignment of tasks.
getRuleList
Retrieves a list of rules for a particular user or group.
getRuleDetail
Gets the details for a particular workflow rule.
createRule
Creates a new rule.
updateRule
Updates an existing rule.
deleteRule
Deletes a rule.
increaseRulePriorit Increases the priority of a rule by one. Rules for a user or group are
y
maintained in an ordered list of priority. Higher priority rules
(those closer to the head of the list) are executed before rules with
lower priority. This method does nothing if this rule already has
the highest priority.
decreaseRulePriorit Decreases the priority of a rule by one. This method does nothing if
y
this rule already has the lowest priority.
getRuleSetInfo
Returns information relating to the Oracle Business Rules rule set
being used to store the rules for a particular user or group. This is
useful if a client wants to make use of the rules SDK directly for
manipulating rules, rather than using the user metadata service.
getUserTaskViewList Gets a list of the user task views that the user owns.
getGrantedTaskViewL Gets a list of user task views that have been granted to the user by
ist
other users. Users can use granted views for querying lists of tasks,
but they cannot update the view definition.
getStandardTaskView Gets a list of standard task views that ship with the workflow
List
service, and are available to all users.
getUserInboxView
Gets a special view to store configuration information, allowing
users to personalize their main inbox list of tasks.
getUserTaskViewDeta Gets the details for a single view.
ils
createUserTaskView
Creates a new user task view.
updateUserTaskView
Updates an existing user task view.
deleteUserTaskView
Deletes a user task view.
updateGrantedTaskVi Updates details of a view grant made to this user by another user.
ew
Updates are limited to hiding or unhiding the view grant (hiding a
view means that the view is not listed in the main inbox page of the
worklist application), and changing the name and description that
the granted user sees for the view.
getUserPreferences
Gets a list of user preferences for the user. User preferences are
simple name-value pairs of strings. User preferences are private to
each user (but can still be queried and updated by
BPMWorkflowAdmin).
setUserPreferences
Sets the user preference values for the user. Any preferences that
were previously stored and are not in the new list of user
preferences are deleted.
15-108 Oracle BPEL Process Manager Developer’s Guide
Workflow Services
Table 15–20
(Cont.) User Metadata Service Methods
Method
Description
getPublicPreference Gets a list of public preferences for the user. Public preferences are
s
similar to user preferences, except any user can query them.
However, only the user that owns the preferences, or the
BPMWorkflowAdmin, can update them. Public preferences are
useful for storing application wide preferences (preferences can be
stored under a dummy user name, such as MyAppPrefs).
setPublicPreference Sets the public preferences for the user.
s
See Also:
■
■
■
Chapter 16, "Worklist Application" for details about the rule
configuration and user preference pages
Oracle BPEL Process Manager Administrator’s Guide 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
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.
The task object used by the task service contains a number of flex field attributes,
which can be populated with information from the task payload. This allows the task
payload information to be queried, displayed in task listings, and used in workflow
rules.
The runtime config service allows administrators to create mappings between simple
task payload attributes and these flex field attributes.
Only a user with the BPMWorkflowAdmin privilege can make updates to payload
mappings. However, 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.
Mappings can then be created between task payload fields and the attribute labels. For
example, the payload field customerLocation can be mapped to the attribute label
Location. Different task types can share the same attribute label. This allows payload
attributes from different task types that have the same semantic meaning to be
mapped to the same attribute label.
Note: Only payload fields that are simple XML types can be
mapped.
Oracle BPEL Process Manager Workflow Services 15-109
Workflow Services
The runtime config service also provides methods for querying the dynamic
assignment functions supported by the server.
Table 15–21 describes the methods in the runtime config service. Package
oracle.bpel.services.workflow.runtimeconfig corresponds to the runtime
config service.
Table 15–21
Runtime Config Service
Method
Description
GetWorkflowPayloadMap Gets a list of all the flex field mappings for a particular workflow
pings
task definition.
CreateAttributeLabel
Creates a new attribute label for a particular task flex field
attribute.
updateAttributeLabel
Updates an existing attribute label.
DeleteAttributeLabel
Deletes an existing attribute label.
getAttributeLabelUsag Gets a list of attribute labels (either all attribute labels, or labels
es
for a specific type of attribute) for which mapping (if any) the
labels are currently used.
createPayloadMapping
Creates a new mapping between an attribute label and a task
payload field.
deletePayloadMapping
Deletes an existing payload mapping.
getUserDynamicAssignm Returns a list of the dynamic assignment functions that can
entFunctions
select a user that are implemented on this server.
getGroupDynamicAssign Returns a list of the dynamic assignment functions that can
mentFunctions
select a group that are implemented on this server.
See Also:
■
■
■
"Dynamic Assignment Functions" on page 15-111 for additional
details
Chapter 16, "Worklist Application" for details about flex field
mapping
Oracle BPEL Process Manager Workflow Services API Reference
located in the SOA_Oracle_Home\bpel\docs\workflow
directory
Internationalization of Attribute Labels
Attribute labels provide a method of attaching a meaningful label to a task flex field
attribute. It can be desirable to present attribute labels that are translated into the
appropriate language for the locale of the user.
To achieve this, you can add entries to the WorkflowLabels.properties resource
property file, and associated resource bundles in other languages. This file exists in the
SOA_Oracle_Home\bpel\system\services\config\wfresource directory.
Entries for flex field attribute labels must be of the form:
FLEX_LABEL.[label name]=Label Display Name
For instance, the entry for a label named Location is:
FLEX_LABEL.Location=Location
15-110 Oracle BPEL Process Manager Developer’s Guide
Configuring the Assignment Service
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.
Configuring the Assignment Service
This section describes how to configure the assignment service.
This section contains the following topics:
■
Dynamic Assignment Functions
■
Dynamically Assigning Task Participants with the Assignment Service
■
Custom Escalation Function
Dynamic Assignment Functions
Dynamic assignment functions select a particular user or group from either a group, or
from a list of users or groups.
The selection is made according to criteria specific to the particular dynamic
assignment function. The three dynamic assignment functions shown in Table 15–22
are included with Oracle BPEL Process Manager:
Table 15–22
Dynamic Assignment Functions
Function
Description
ROUND_ROBIN
Picks each user or group in turn.
least-busy
Picks the user or group with the least number of tasks currently
assigned to it.
most-productive
Picks the user or group that has completed the most tasks over a
certain time period (by default, the last seven days).
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).
Additional optional parameters specific to the dynamic assignment function. In
the case of the most-productive assignment function, this is the length of time
(in days) to calculate a user’s productivity. The two other functions do not use
additional parameters.
Oracle BPEL Process Manager Workflow Services 15-111
Configuring the Assignment Service
In addition, workflow rules created for a group can use dynamic assignment functions
to select a member of that group for reassignment of a task.
In addition to the three functions, a dynamic assignment framework is provided that
allows you to implement and configure your own dynamic assignment functions.
Implementing a Dynamic Assignment Function
To implement your own dynamic assignment function, write a Java class that
implements one or both of the following interfaces:
oracle.bpel.services.workflow.assignment.dynamic. IDynamicUserAssignmentFunction
oracle.bpel.services.workflow.assignment.dynamic. IDynamicGroupAssignmentFunction
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 below:
public interface IDynamicAssignmentFunction
{
/**
* Sets the initialization parameters required by the function (if any)
* This function is called automatically by the DynamicAssignmentRegistry
* on registration of a new function. Initialization parameters can be
* specified in the xml definition of the function in the dynamic assign
* config file
* @param initParams Map of String parameter values keyed by String parameter
* names
* @throws DynamicAssignmentException if implementation of method finds invalid
* parameters
*/
public void setInitParams( Map initParams ) throws DynamicAssignmentException;
/**
* Gets the name of this Dynamic Assignment Function
* @return String the name of the Dynamic Assignment Function
*/
public String getFunctionName();
/**
* Gets a description of this Dynamic Assignment Function
* @return String description of function
*/
public String getDescription();
}
public interface IDynamicGroupAssignmentFunction extends
IDynamicAssignmentFunction
{
/**
* This method contains the implementation of the Assignment Function
* Given a group name, it will return a subgroup in that group,
* according to the assignment pattern implemented
15-112 Oracle BPEL Process Manager Developer’s Guide
Configuring the Assignment Service
* @return String name of group
* @param groupName String name of group to select group from
* @param realm String name of Identity Service realm the group belongs
* to. If realm is null, the default Identity Service realm will be used.
* @param parameters String[] optional array of parameter values.
* Use of parameter values is implementation-specific.
*/
public String getGroupAssignment( String groupName, String realm, String[]
parameters )
throws DynamicAssignmentException;
/**
* This method contains the implementation of the Assignment Function
* Given an arbitrary list of groups, it will return a group in that
* list, according to the assignment pattern implemented
* @return String name of group
* @param groupNames List of groups to select from
* @param realm String name of Identity Service realm the groups belong
* to. If realm is null, the default Identity Service realm will be used.
* @param parameters String[] optional array of parameter values.
* Use of parameter values is implementation-specific.
*/
public String getGroupAssignment( List groupNames, String realm, String[]
parameters )
throws DynamicAssignmentException;
}
public interface IDynamicUserAssignmentFunction extends IDynamicAssignmentFunction
{
/**
* This method contains the implementation of the Assignment Function
* Given a group name, it will return a user in that group,
* according to the assignment pattern implemented
* @return String username of user
* @param groupName String name of group to select user from
* @param realm String name of Identity Service realm the group belongs
* to. If realm is null, the default Identity Service realm will be used.
* @param parameters String[] optional array of parameter values.
* Use of parameter values is implementation-specific.
*/
public String getUserAssignment( String groupName, String realm, String[]
parameters )
throws DynamicAssignmentException;
/**
* This method contains the implementation of the Assignment Function
* Given an arbitrary list of users, it will return a user in that
* list, according to the assignment pattern implemented
* @return String username of user
* @param usernames List of usernames to select user from
* @param realm String name of Identity Service realm the users belong
* to. If realm is null, the default Identity Service realm will be used.
* @param parameters String[] optional array of parameter values.
* Use of parameter values is implementation-specific.
*/
public String getUserAssignment( List usernames, String realm, String[]
parameters )
throws DynamicAssignmentException;
}
The dynamic assignment framework also provides the utility class
oracle.bpel.services.workflow.assignment.dynamic.DynamicAssignme
ntUtils.
Oracle BPEL Process Manager Workflow Services 15-113
Configuring the Assignment Service
This class provides a number of methods that are useful when implementing dynamic
assignment functions.
These include:
/**
* Method returns a list of users belonging to the specified group
* that are available (i.e. not on vacation etc.)
* @return List of String usernames of available users
* @param group - name of group to lookup users for
* @throws DynamicAssignmentException if error encountered looking up
* group, or checking users.
*/
public static List getAvailableUsersFromGroup( String group, String realm )
throws DynamicAssignmentException
/**
* Method returns a list of users from the specified list
* that are available (i.e. not on vacation etc.)
* @return List of String usernames of available users
* @param usernames - List of String usernames to check
* @param realm - realm that users belong to
* @throws DynamicAssignmentException if error encountered looking up
* group, or checking users.
*/
public static List getAvailableUsersFromList( List usernames, String realm )
throws DynamicAssignmentException
/**
* Method uses the specified group name to lookup the sub-groups belonging to
* that group using the identity service.
* @return List of String names of groups
* @param groupName name of group to lookup
* @param realm to lookup group in - if null, then use identity service default
* @realm
* @batam boolean - directsOnly: if true return only the direct sub-groups
* of this group. If false, return all groups belonging to this group.
* @throws DynamicAssignmentException if group could not be found
*/
public static List getGroupsFromGroup( String groupName
, String realm
, boolean directsOnly )
throws DynamicAssignmentException
/**
* Method uses the specified group name to lookup the users belonging to that
* group using the identity service.
* @return List of String usernames of user
* @param groupName String name of group to lookup
* @param realm to lookup group in - if null, then use identity service default
* @realm
* @throws DynamicAssignmentException if group could not be found
*/
public static List getUsersFromGroup( String groupName, String realm )
throws DynamicAssignmentException
/**
*Method returns the default identity management realm for the Identity Service
*Instance.
*/
public static String getIDServiceDefaultRealm( ) throws
DynamicAssignmentException
/**
* Method checks WF Schema to determine if the specified user is available
15-114 Oracle BPEL Process Manager Developer’s Guide
Configuring the Assignment Service
* (i.e. they are not on vacation etc.).
* @return true if user is available, false if they are on vacation
* @param username
* @param realm
*/
public static boolean isUserAvailable( String username, String realm )
throws DynamicAssignmentException
Configuring Dynamic Assignment Functions
Dynamic assignment functions are configured using the
wf-dynamic-assign-cfg.xml file in the SOA_Oracle_
Home\bpel\system\services\config directory.
Each dynamic assignment function must have an entry in this file, in the form of a
<function> tag.
The function tag must contain two attributes:
■
name — the name of the function.
■
classpath — the classpath of the class that implements the function.
In addition, the function tag can optionally contain any number of <property> tags.
These tags pass initialization parameters to the dynamic assignment function. Each
property tag must contain a name attribute. The value of the property is specified in
the body of the tag.
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.
Configuring Display Names for Dynamic Assignment Functions
The runtime config service provides methods for returning a list of available user and
group dynamic assignment functions. These functions return both the name of the
function, and a user-displayable label for the function. The functions support
localization of the display name, so that it displays in the appropriate language for the
context user. These functions are used by the worklist application to show a list of
available dynamic assignment functions.
To specify display names (and appropriate translations) for your dynamic assignment
functions, add entries to the resource property file WorkflowLabels.properties,
and associated resource property files in other languages. This file exists in the SOA_
Oracle_Home\bpel\system\services\config\wfresource directory.
Entries for dynamic assignment functions must be of the form:
DYN_ASSIGN_FN.[function name]=Function Display Name
Oracle BPEL Process Manager Workflow Services 15-115
Configuring the Assignment Service
For instance, the entry for the ROUND_ROBIN function is:
DYN_ASSIGN_FN.ROUND_ROBIN = Round Robin
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.
Dynamically Assigning Task Participants with the Assignment Service
Workflow task participants are specified declaratively in a routing slip. The routing
slip guides the workflow by specifying the participants and how they participate in
the workflow task (for example, management chain hierarchy, sequential list of
approvers, and so on).
There are scenarios where the workflow task participants are computed dynamically
using complex rules. To support such dynamic assignment, an assignment service is
used. The assignment service is responsible for determining the task assignees. You
can also implement your own assignment service and plug in that implementation for
use with a particular workflow.
Assignment Service Overview
The assignment service determines the following task assignment details in a
workflow:
■
The assignment when the task is initiated
■
The assignment when the task is reinitiated
■
■
■
■
The assignment when a user updates the task outcome. When the task outcome is
updated, the task can either be routed to other users or completed.
The assignees from whom information for the task can be requested
If the task supports reapproval from the Oracle BPEL Worklist Application, a user
can request information for reapproval.
The users who reapprove the task if reapproval is supported.
The workflow service identifies and invokes the assignment service for a particular
task to determine the task assignment.
For example, a simple assignment service iteration is as follows:
1.
A client initiates an expense approval task whose routing is determined by the
assignment service.
2.
The assignment service determines that the task assignee is jcooper.
3.
When jcooper approves the task, the assignment service assigns the task to
jstein. The assignment service also specifies that a notification must be sent to
the creator of the task, jlondon.
4.
jstein approves the task and the assignment service indicates that there are no
more users to which to assign the task.
Implementing an Assignment Service
The assignment service is implemented with the IAssignmentService interface.
The workflow service passes the following information to the assignment service to
determine the task assignment:
15-116 Oracle BPEL Process Manager Developer’s Guide
Configuring the Assignment Service
■
■
■
Task document — The task document that is executed by the workflow. The task
document contains the payload and other task information like current state, and
so on.
Map of properties — When an assignment service is specified, a list of properties
can also be specified to correlate callbacks with backend services that determine
the task assignees.
Task history — The task history is a list of chronologically ordered task documents
to trace the history of the task. The task documents in this list contain a subset of
attributes in the actual task (such as state, updatedBy, outcome,
updatedDate, and so on).
Example of Assignment Service Implementation
Notes:
■
■
The assignment service class cannot be stateful because every time
workflow 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
workflow service tries to determine the permitted actions for a
task.
You can implement your own assignment service plug-in that the workflow service
invokes during workflow 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.*;
Oracle BPEL Process Manager Workflow Services 15-117
Configuring the Assignment Service
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
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++];
ObjectFactory objFactory = new ObjectFactory();
Participants participants = objFactory.createParticipants();
Participant participant = objFactory.createParticipantsTypeParticipant();
participant.setName("Loan Agent");
ResourceType resource2 = objFactory.createResourceType(user);
resource2.setIsGroup(false);
resource2.setType("STATIC");
participant.getResource().add(resource2);
15-118 Oracle BPEL Process Manager Developer’s Guide
Workflow Service and Identity Service Related XPath Extension Functions
participants.getParticipantOrSequentialParticipantOrAdhoc().
add(participant);
return participants;
}
}
Custom Escalation Function
The custom escalation function enables you to integrate a custom rule in a workflow.
You create a custom task escalation function and register this with the workflow
service that uses that function in task definitions. The Advanced Settings section of
the Human Task editor enables you to integrate the rule in a human task.
See Also:
"Specifying Escalation Rules" on page 15-46 for details
Workflow Service and Identity Service Related XPath Extension Functions
Oracle BPEL Process Manager provides XPath extension functions for use with the
workflow services and the identity service. XPath extension functions mimic XPath 2.0
standards. Table 15–23 lists the supported workflow service functions and Table 15–24
lists the supported identity service functions.
Table 15–23
Function
Workflow Service Functions
Description
See
hwf:clearTaskAssignees Clears the task assignees in a
()
task.
"clearTaskAssignees" on
page D-28
hwf:createWordMLDocume Creates a Word document by
nt()
transforming the given XSLT to
WordML
"createWordMLDocument"
on page D-29
hwf:getNotificationPro Gets properties for a particular
perty()
notification.
"Contents of Notification"
on page 15-80
"getNotificationProperty"
on page D-29
hwf:getNumberOfTaskApp Gets the number of task
rovals()
approvals.
"getNumberOfTaskApprov
als" on page D-30
hwf:getPreviousTaskApp Gets the previous task approver.
rover()
"getPreviousTaskApprover"
on page D-30
hwf:getTaskAttachmentB Gets the task attachment by
yIndex()
attachment index.
"getTaskAttachmentByInde
x" on page D-30
hwf:getTaskAttachmentB Gets the task attachment by
yName()
attachment name.
"getTaskAttachmentByNam
e" on page D-30
hwf:getTaskAttachmentC Gets the task attachment contents "getTaskAttachmentConten
ontents()
by attachment name.
ts" on page D-31
hwf:getTaskAttachments Gets the number of task
Count()
attachments.
"getTaskAttachmentsCount
" on page D-31
hwf:getTaskAttachmentB Gets the resource string for a
yIndex()
particular task
"getTaskAttachmentByInde
x" on page D-30
Oracle BPEL Process Manager Workflow Services 15-119
Workflow Service and Identity Service Related XPath Extension Functions
Table 15–23
(Cont.) Workflow Service Functions
Function
Description
See
hwf:wfDynamicGroupAssi Gets the name of an identity
"wfDynamicGroupAssign"
gn()
service group, selected according on page D-32
to the specified assignment
pattern.
hwf:wfDynamicUserAssig Gets the name of an identity
n()
service user, selected according
to the specified assignment
pattern.
Table 15–24
"wfDynamicUserAssign" on
page D-33
Identity Service Functions
Function
Description
See
ids:getDefaultRealmNam Gets the default realm name.
e()
"getDefaultRealmName" on
page D-23
ids:getGroupProperty() Gets a group property.
"getGroupProperty" on
page D-24
ids:getManager()
Gets the manager of a given user. "getManager" on page D-24
ids:getReportees()
Gets the direct reportees of the
user.
ids:getSupportedRealmN Gets the supported realm names.
ames()
"getReportees" on
page D-25
"getSupportedRealmName
s" on page D-25
ids:getUserProperty()
Gets a user property.
"getUserProperty" on
page D-25
ids:getUserRoles()
Gets the user roles.
"getUserRoles" on
page D-26
ids:getUsersInGroup()
Gets the users in a group.
"getUsersInGroup" on
page D-26
ids:isUserInRole()
Verifies if a user has a given role.
"isUserInRole" on
page D-27
ids:lookupGroup()
Gets the group object.
"lookupGroup" on
page D-27
ids:lookupUser()
Gets the user object.
"lookupUser" on page D-28
Deprecated Workflow Service and Identity Service Functions
Table 15–25 lists the workflow and identity service functions that are deprecated for
this release.
Table 15–25
Deprecated Workflow Service and Identity Service Functions
Workflow 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()
15-120 Oracle BPEL Process Manager Developer’s Guide
Summary
Table 15–25
(Cont.) Deprecated Workflow Service and Identity Service Functions
Workflow Function
Identity Service Functions
ora:lookupGroup()
ora:lookupUser()
ora:getUserProperty()
NLS Configuration
You can specify resource bundles for displaying task details in different languages in
Oracle BPEL Worklist Application.
In addition, the resource property file WorkflowLabels.properties can be used
for setting display names for the following:
■
Dynamic assignment functions
■
Payload mapping attribute labels
■
Task attributes
See Also:
■
■
"Specifying Multilingual Settings" on page 15-47 for details about
resource bundles
"Internationalization of Attribute Labels" on page 15-110 and
"Configuring Display Names for Dynamic Assignment Functions"
on page 15-115 for additional details about the resource property
file WorkflowLabels.properties.
Summary
This chapter describes how you can integrate systems and services with human
workflow into a single end-to-end process flow using Oracle BPEL Process Manager.
The predefined workflow participant types are described, as are the components of
workflow services—the task service, task routing service, identity service, worklist
service, notification service, and others.
Oracle BPEL Process Manager Workflow Services 15-121
Summary
15-122 Oracle BPEL Process Manager Developer’s Guide
16
Worklist Application
The Oracle BPEL Worklist Application (Worklist Application) is a Web interface that
enables users to act on their assigned human workflow tasks. This chapter discusses
the sample Worklist Application that is provided with Oracle BPEL Process Manager,
and how you can modify it to create your own worklist application.
This chapter contains the following topics:
■
Use Cases for the Worklist Application
■
Overview of Worklist Application Concepts
■
Features of the Worklist Application
■
Accessing the Worklist Application in Local Languages
■
Customizing the Worklist Application
■
Building Clients for Workflow Services
■
Summary
Use Cases for the Worklist Application
You can use the Web interface of the Worklist Application for any activity that requires
you to act on tasks in a BPEL process. A manager can approve employee vacation
requests or a loan agent can review a loan application, each of which has been
submitted as part of a BPEL process. Supervisors or group administrators can use the
Worklist Application to analyze tasks assigned to the group and route them
appropriately. Worklist Application users can also update payloads, attach documents
or comments, and route the task to other users, in addition to completing tasks by
providing conclusions such as approvals or rejections.
The Worklist Application is demonstrated in the following use cases:
■
■
■
Vacation Request—In this use case, an employee files a vacation request that is
routed to his manager for approval. The manager sees the task in the Worklist
Application in the My Tasks tab.
Document Review—In this use case, an author submits a document for review by
multiple reviewers in parallel.
Expense Request Approval—In this use case, an employee’s expense request is
automatically routed to his manager for approval. The manager sees the task in
the Worklist Application in the My Tasks tab. After the manager’s approval, the
task may be routed further up the management chain, depending on the content of
the expense request. The BPEL process uses a decide activity to define the
approval chain for a human workflow task dynamically, using Oracle Business
Worklist Application 16-1
Overview of Worklist Application Concepts
Rules. The business rules determine the approval level required for the expense
request, based on factors such as the amount of the request and the type of
expense. The sample demonstrates how the approval chain for each expense
report can be different, and how users can change the rules governing the
approvals at run time.
■
■
Help Desk Service Request—In this use case, the supervisor resolves a service
request by assigning it to any of his reportees using ad hoc routing. The assignee
then approves the task after he responds to the service request.
Loan Demo Plus—In this use case, a loan application is assigned to the LoanAgent
role. All loan agents see the task in their My & Group tasks view. One of the loan
agents claims the task and reviews it. If the loan agent approves it, and if the loan
amount is greater than $100,000, then the task is routed further, to two levels of
management approval. When the loan agent’s managers log in to their worklists,
they see tasks that were routed to them and the actions performed by the previous
approvers (for example, suggested APR, comments, or attachments).
SOA_Oracle_Home\bpel\samples\demos for the following
directories:
See:
■
VacationRequest
■
DocumentReview
■
ExpenseReportApproval
■
HelpDeskServiceRequest
■
LoanDemoPlus
Sample applications that are built with the workflow service APIs and demonstrate
common features such as listing, updates, approvals, and login and logout are also
provided.
See:
SOA_Oracle_Home\bpel\samples\ for the following:
■
demos\ExpenseReportApproval
■
demos\LoanDemoPlus
■
tutorials\132.UserTasks
■
utils\AsyncLoanService\ StarLoanUI
The OrderBooking tutorial also demonstrates how to use the Worklist Application to
approve a purchase order manually.
See:
Oracle BPEL Process Manager Order Booking Tutorial
Overview of Worklist Application Concepts
Chapter 15, "Oracle BPEL Process Manager Workflow Services" discussed how BPEL
workflow services enable you to interweave human interactions along with
connectivity to systems and services into an end-to-end process flow. The workflow
service provides a programmatic interface to view and manage tasks from the BPEL
process. The tasks displayed depend on the user’s profile, and the actions allowed
depend on the user’s privileges. This Worklist Application is layered on top of the
BPEL workflow service.
16-2 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Worklist Application User Types
The Worklist Application recognizes different types of users, as listed in Table 16–1.
Table 16–1
Worklist Application User Types
Type of User
Access
End user
Acts on tasks assigned to him or his group and has access to system and custom
actions, routing rules, and custom views
Supervisor (manager)
Acts on the tasks, reports, and custom views of his reportees, in addition to his own
end-user access
Process owner
Acts on tasks belonging to the process but assigned to other users, in addition to his
own end-user access
Group administrator
Manages group rules and dynamic assignments, in addition to his own end-user
access
Workflow administrator
Administers tasks that are in an errored state, for example, tasks that must be
reassigned or suspended. The workflow administrator can also change application
preferences and map flex fields, and manage rules for any user or group, in addition
to his own end-user access.
See "Identity Service" on page 15-100 for more information about predefined roles in
the identity service.
Task Components
A work item or task that is assigned to a user has the following components:
■
■
■
■
■
Task attributes—Includes task title, number, status, priority, expiration,
identification key, assignees, and other flex fields.
Task form—Consists of detailed information (the payload) about the task; for
example, a loan application in the LoanDemoPlus sample or support ticket details
in the HelpDeskServiceRequest sample.
Task comments—Comments entered by various users who have participated in
the workflow.
Task attachments—Other documents or reference URLs that are associated with a
task. These are typically associated with the workflow by the BPEL process or
attached and modified by any of the participants in the workflow.
Task history—Consists of the approval sequence and the update history for the
task. The history maintains an audit trail of the actions performed by the
participants in the workflow and a snapshot of the task payload and attachments
at various points in the workflow.
The types of actions that users can perform on a task include:
■
■
Update task details—The task form can include content that needs to be added or
modified by the task reviewer. The reviewer can modify the task priority, include
comments, or add attachments to the task.
Change outcome for the task—As part of the process model, the workflow
designer can include various custom outcomes for the task (for example, approve
or reject, acknowledge, defer). If a user modifies a task outcome, it is removed
from his worklist and routed to the next approver or back to the business process
based on the workflow pattern.
Worklist Application 16-3
Features of the Worklist Application
■
Perform system actions—In addition to the custom actions specified as part of
workflow modeling, the user can perform other system actions such as escalate or
delegate. These actions are available on all tasks based on the user’s privileges.
The process owner or workflow administrator can always perform any of these
operations on processes that they own. See "Task Actions" on page 16-10 for more
information about system actions.
Features of the Worklist Application
Use Internet Explorer 6.0 or Mozilla Firefox 1.0.4 to access the Worklist Application.
1.
Open a Web browser.
2.
Go to the following URL:
http://hostname:portnumber/integration/worklistapp/Login
■
■
hostname is the name of the host on which Oracle BPEL Process Manager is
installed
The portnumber used at installation (typically 9700 or 8888) is noted in
bpelsetupinfo.txt, at
SOA_Oracle_Home\install\
You can also select Start, then All Programs, then Oracle - Oracle_Home, then
Oracle BPEL Process Manager, and then Worklist Application.
3.
Type the username and password, and click Login.
You can use jstein and welcome1 to access the sample Worklist Application.
The username and password must exist in the user community provided to JAZN.
See Oracle BPEL Process Manager Administrator’s Guide for the organizational
hierarchy of the demonstration user community used in examples throughout this
chapter. See "Identity Service" on page 15-100 for information on JAZN.
The Worklist Application displays tasks specific to the logged-in user based on the
user’s permissions and assigned groups and roles. Figure 16–1 shows the Worklist
Application for the user jstein, who is a manager and is responsible for approving or
rejecting his reportees’ vacation requests.
16-4 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–1 Worklist Application—Task Listing (Home) Page
All task interactions—listing tasks, viewing task details, reassigning tasks, performing
actions on tasks, setting outcomes, and so on—are initiated from the Task Listing
(home) page. As Figure 16–1 shows, when jstein logs in to the Worklist Application, he
sees the Task Listing (home) page, which shows the tasks assigned to him and to the
group to which he belongs. Because jstein is a manager, the My Staff Tasks tab also
appears. For tasks assigned to jstein, he selects an action from the Actions list to
participate in the workflow. For tasks assigned to a group to which jstein belongs, he
must claim the task before selecting an action. The task is not available to other users
until jstein releases it back to the group.
From the home page, you can retrieve worklist tasks by using the Search field to do a
keyword search or by using the Category, Priority, and Status fields to specify search
criteria. The category filters that are available depend on which tab is selected. From
the My Tasks tab, the category filters are My, Group, My & Group, and Previous
(tasks worked on in the past). From the My Staff Tasks tab, the only category filter is
Reportees. From the Initiated Tasks tab, the only category filter is Creator. In addition
to the My Tasks, My Staff Tasks, and Initiated Tasks tabs, other tabs may be
displayed, depending on the role granted to the logged-in user, as described in
Table 16–2 (Tabs). From the Administration Tasks tab, the category filter is Owner if
the user (who has been granted the BPMWorkflowAdmin role in order to see this tab)
owns the tasks and Admin otherwise.
Table 16–2 describes the salient features of the Task Listing (home) page of the Worklist
Application shown in Figure 16–1.
Worklist Application 16-5
Features of the Worklist Application
Table 16–2
Location in
Figure 16–1
Top left
Contents of the Worklist Application My Tasks Page
Page Element
Tabs—The tabs displayed depend on the role granted to the logged-in user. Everyone sees My
Tasks and Initiated Tasks. Managers also see My Staff Tasks. A user with the
BPMWorkflowAdmin role also sees the Administration Tasks, Manage Rules, Flex Field
Mappings, and Application Customization tabs. See "Using the Administration Functions" on
page 16-27 for more information.
Welcome jstein [jazn.com]—In the banner area, the logged-in user’s name appears. Click the user
name to display information. See "User and Group Information" on page 16-39 for more
information.
Top right
Reports link—The following reports are available: Unattended Tasks Report, Tasks Priority
Report, Tasks Cycle Time Report, Tasks Productivity Report. See "Creating Reports" on page 16-33
for more information.
Preferences link—Manages the logged-in user’s preferences, including setting vacation and other
workflow rules, managing custom views, and customizing worklist displays. See "Setting
Preferences" on page 16-21 for more information.
Left pane
Work Queues—Standard, custom, and proxy views. See "Using Work Queues" on page 16-20 for
more information.
16-6 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Table 16–2 (Cont.) Contents of the Worklist Application My Tasks Page
Location in
Figure 16–1
Page Element
Center pane
Show (Hide) Chart button—Toggles to show or hide a bar chart of the listed tasks in the selected
task filter, broken down by status. See "Viewing a Bar Chart of Task Status" on page 16-19 for more
information.
Center pane,
Search area
Search Keyword field—Enter a keyword to search task titles, comments, identification keys, and
the flex string fields of tasks that qualify for the specified filter criterion.
Category—Select from the following:
■
My—Retrieves tasks directly assigned to the logged-in user
■
Group—Tasks assigned to the groups to which the logged-in user belongs
■
My & Group—Tasks assigned to the user and the groups to which the logged-in user belongs
■
Previous—Tasks that the logged-in user has updated
Priority—Select from Any or 1 through 5, where 1 is the highest priority.
Status—Select from the following: Any, Assigned, Completed, Suspended (can be resumed later),
Withdrawn, Expired, Errored (while processing), Information Requested
Advanced Search link—Provides additional search filters. See "Using Advanced Search" on
page 16-17 for more information.
Center pane,
task list area
The default display shows the following columns. You can change the display from the
Preferences link. See "Display Preferences" on page 16-26 for more information.
Task Number—The task number generated when the BPEL process was created.
Title—The title specified when the human workflow task was created. Tasks associated with a
purged or archived process instance do not appear. See "Specifying the Task Title, Priority,
Outcome, and Owner" on page 15-15 for more information.
Priority—The priority specified when the human workflow task was created. See "Reviewing the
Sections of the Human Task Editor" on page 15-15 for more information.
Assigned Users—The assignments specified when the human workflow task was created. See
"Assigning Task Participants" on page 15-22 for more information.
Assigned Groups—The assignments specified when the human workflow task was created. See
"Assigning Task Participants" on page 15-22 for more information.
State—One of the following: Assigned, Completed, Errored, Expired, Info Requested, Stale,
Suspended, and Withdrawn. See "Overriding Default System Actions" on page 15-48 for more
information.
Created Date—Date and time the task was created using Oracle BPEL Process Manager
Expiration Date—Date and time the tasks expires, specified when the human workflow was
created.
Actions—The group action (Claim) and the custom actions (for example, Accept and Reject) that
were defined for the workflow. Other possible actions for a task, such as system actions, are
displayed on the Task Details page for a specific task. See "Using Advanced Search" on page 16-8
for more information.
This section contains the following topics:
■
Using the Task Details Page
■
Using Advanced Search
■
Viewing a Bar Chart of Task Status
■
Using Work Queues
■
Setting Preferences
■
Using the Administration Functions
Worklist Application 16-7
Features of the Worklist Application
■
Creating Reports
■
User and Group Information
Using the Task Details Page
If you click a task in the Task Title column, the Task Details page for that task is
displayed, as shown in Figure 16–2.
16-8 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–2 Task Details Page
Worklist Application 16-9
Features of the Worklist Application
This section describes the following elements of the Task Details page:
■
Task Actions
■
Request Status
■
Header Section
■
Payload Section
■
Comments and Attachments Section
■
History Section
■
Routing
■
Requesting More Information
■
Reassignment
■
Parallel Tasks
■
Determining Action Permissions
Task Actions
Figure 16–3 shows a Task Action list. The actions in the list depend on the task design,
the state of the task (for example, if the task has been completed, then no actions are
listed), and the roles assigned to the logged-in user. Custom actions (actions defined in
the BPEL process), such as Accept or Reject, are listed first. System actions, such as
Escalate or Suspend, are listed below a separator line.
Figure 16–3 Task Actions List
You act on tasks using either the Task Action list or a button. The Task Action list
contains actions that do not require additional input, such as accept, reject, renew, and
suspend. Buttons are provided for actions that require additional input, such as
reassignment and requests for information.
System actions are available on all tasks based on the user’s privileges. Table 16–3 lists
system actions.
16-10 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Table 16–3
System Task Actions
Action
Description
Claim
If a task is assigned to a group or multiple users, then the task must be claimed first.
Claim is the only action available in the Task Action list for group or multiuser
assignments. After a task is claimed, all applicable actions are listed.
Escalate
If you are not able to complete a task, you can escalate it and add an optional
comment in the Comments area. The task is reassigned to your manager.
Pushback
Use this action to send a task up one level in the workflow to the previous assignee.
Reassign
If you are a manager, you can delegate a task to reportees. A user with
BPMWorkflowReassign privileges can delegate a task to anyone.
Release
If a task is assigned to a group or multiple users, it can be released if the user who
claimed the task cannot complete the task. Any of the other assignees can claim and
complete the task.
Renew
If a task is about to expire, you can renew it and add an optional comment in the
Comments area. The task expiration date is extended one week. A renewal appears in
the task history. The renewal duration for a task can be controlled by an optional
parameter, oracle.tip.worklist.samples.taskactin.renew.duration, in
the file pc.properties, which appears in SOA_Oracle_
Home\bpel\system\services\config. The default value is P7D (seven days).
Submit More Information Use these actions if another user requests that you supply more information or if you
and Request More
want to request more information from the task creator or any of the previous
Information
assignees. If reapproval is not required, then the task is assigned to the next approver
or the next step in the business process.
Suspend and Resume
If a task is not relevant at present, you can suspend it. These options are available
only to users who have been granted the BPMWorkflowSuspend role. Other users
can access the task by selecting Previous in the task filter or by looking up tasks in the
Suspended status. Buttons that update a task are disabled after suspension.
Withdraw
If you are the creator of a task and do not want to continue with it, for example, you
want to cancel a vacation request, you can withdraw it and add an optional comment
in the Comments area. The business process determines what happens next. You can
use the Withdraw action on the home page by using the Creator task filter.
After you select one of the actions, the task is routed to the next step, depending on
how the business process was designed. When a task is completed, all actions and
form elements are disabled.
Request Status
For every update request (custom or system action) that you submit, the status of the
request is displayed in the left portion of the header. If a request is successful, then you
see a confirming message, as shown near the top of the page in Figure 16–4.
Worklist Application 16-11
Features of the Worklist Application
Figure 16–4 A Successful Update Request
If a request is not successful, then you see an error message, as shown in Figure 16–5.
You can click the link for additional information about the error.
Figure 16–5 Error Message Display
The error shown in Figure 16–5 occurs when a user has attempted an action that is not
permitted. This is possible in the following scenarios:
■
■
The task expired between the time the user loaded the page and actually
performed the action.
The task was claimed and updated concurrently by another user (such as a
manager, owner, or administrator) between the time the user loaded the page and
actually performed the action.
16-12 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Errored tasks are not assigned to a specific user. They are only assigned to the
bpeladmin user. If you are a user other than bpeladmin and want to see these
errors, select All in the Category list and Errored or Any in the Status list.
Header Section
Figure 16–6 shows the header section. Header information includes the task number
and title; the state, outcome, and priority of the BPEL process, and information about
who created, updated, claimed, or is assigned to the task. It also displays dates related
to task creation, last modification, and expiration.
Figure 16–6 Header Section of the Task Details Page
Payload Section
Figure 16–7 shows the payload section for the Vacation Request Process Request
workflow. The fields displayed—Creator, From Date, To Date, Reason—reflect how
the BPEL process for vacation approval was designed, using the autogenerated JSP.
Figure 16–7 Payload Section
See "Automatically Generating a Simple Task Display Form" on page 15-67 for
information on using the autogenerated JSP in your workflow design.
Comments and Attachments Section
Figure 16–8 shows where you add or delete comments and attachments. To add or
delete a comment or attachment, you must have permission to update the task.
Worklist Application 16-13
Features of the Worklist Application
Figure 16–8 Adding a Comment or Attachment
A newly added comment and the comment writer’s username are appended to the
existing comments. A trail of comments is maintained throughout the life cycle of the
task. When adding attachments, you can use an absolute path name or browse for a
file or provide a URL.
History Section
Figure 16–9 shows the short history for a vacation approval task.
Figure 16–9 History Section of the Task Details Page
The short history for a task lists all versions created by the following tasks:
■
Initiate task
■
Reinitiate task
■
Update outcome of task
■
Completion of task
■
Erroring of task
■
Expiration of task
■
Withdrawal of task
■
Alerting of task to the error assignee
You can include the following actions in the short history list by modifying the
shortHistoryActions element in
SOA_Oracle_Home\bpel\system\services\config\wf_config.xml
■
Acquire
■
Adhoc route
16-14 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
■
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 lists all version changes in a task.
Routing
If there is no predetermined sequence of approvers or if the workflow was designed to
permit ad hoc routing, then the task can be routed in an ad hoc fashion. For such tasks,
a Route button appears on the Task Details page. From the Routing page, you can look
up one or more users for routing. When you specify multiple assignees, you can
choose whether the list of assignees is for simple (group assignment to all users),
sequential, or parallel assignment. In the case of parallel assignment, you provide the
percentage of votes required for approval.
Requesting More Information
From the Task Details page, you can request more information by using the Request
Info button. The Reapproval Needed field appears if previous approvers must
reapprove given the additional information, assuming that the process was designed
to support reapproval. You can also add comments. After you have requested
additional information, the task is assigned to the user from whom the additional
information is needed. The user from whom additional information is requested uses
Submit More Info to fulfill the request.
Reassignment
From the Task Details page, you can reassign a task using the Reassign button. As
Figure 16–10 shows, you can either reassign (transfer) or delegate:
Worklist Application 16-15
Features of the Worklist Application
Figure 16–10 Reassigning Tasks
■
■
Reassign (transfer task to another user or group)—The task is moved from the
assignee’s worklist to another user’s worklist. The newly assigned user then acts
on the task, rather than the original user.
Delegate (allow specified user to act on my behalf)—The task is delegated to
another user, but it shows up in both the original user’s and the delegated user’s
worklists. The delegated user can act on behalf of the original assignee.
Use the Search button to find assignees and the up and down arrows to select or
deselect assignees. Wildcard search is supported.
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.
16-16 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Parallel Tasks
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.
Determining Action Permissions
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 listing 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.
See "Identity Service" on page 15-100 for information about the identity service and
how privileges can be assigned to users.
Using Advanced Search
If you click the Advanced Search link, the page shown in Figure 16–11 is displayed.
Worklist Application 16-17
Features of the Worklist Application
Figure 16–11
Advanced Search Page
When you search on a task type, the Select Workflow Task Type page is displayed.
From this page, you select a task type and are returned to the Advanced Search page.
As Figure 16–12 shows, you can filter the search by adding conditions.
16-18 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–12
Adding Conditions to an Advanced Search
Conditions can be AND operations (the All of the following option) or OR operations
(the Any of the following option). Each filter specifies a combination of attribute,
operator, and value. The operator and value are tied to the type of the attribute and
change based on the attribute chosen. For example, for identity fields such as Created
By or Updated By, a flashlight icon appears so that you can search for names using the
identity browser. For date fields, a calendar icon appears so that you an pick a date.
Viewing a Bar Chart of Task Status
When you click the bar chart icon, a bar chart of the tasks is displayed, as shown in
Figure 16–13.
Worklist Application 16-19
Features of the Worklist Application
Figure 16–13 My Tasks Page with Chart Displayed
The bar chart shows the tasks broken down by status, with a count of how many tasks
in each status category.
Using Work Queues
The Work Queues pane, shown in Figure 16–14, is displayed by default. (Use the work
queues icon to reopen a closed pane.)
16-20 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–14
Work Queues Pane
The Work Queues pane displays the following:
■
■
■
Inbox—Shows all tasks that qualify for the user-chosen filter. The default shows
all tasks, including high priority tasks, tasks due soon, new tasks, and so on.
My Work Queues—Shows standard work queues, and custom work queues that
users have defined based on specific search criteria.
Proxy Work Queues—Shows queues to which a user has granted access to other
users. Other users can act on those tasks on behalf of the user who granted access.
Setting Preferences
From the Preferences link, the following kinds of preferences are available:
■
Vacation Preferences
■
My Rules
■
Group Rules
■
Custom Views
■
Display Preferences
Vacation Preferences
Use the vacation preferences to make yourself unavailable for task assignments. As
Figure 16–15 shows, you specify a vacation date range, and optionally create a rule.
Based on the rules you specify, tasks can be approved automatically or reassigned to
someone else, for example.
Worklist Application 16-21
Features of the Worklist Application
Figure 16–15 Setting a Vacation Preference in the Worklist Application
As Figure 16–16 shows, when creating a rule, you can specify which task the rule
applies to, add conditions, and delegate or reassign the task to another user or a group.
Figure 16–16 Creating a Rule in the Worklist Application
My Rules
Use a rule to specify conditions which, if true, cause an automatic action on a task.
Examples include vacation rules, as discussed in the previous section, or a rule in
which certain types of tasks are approved automatically. As Figure 16–16 shows, you
can specify the following when creating a rule:
■
Rule name and description
■
Which task the rule applies to—If unspecified, then the rule applies to all tasks.
■
When the rule applies
16-22 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
■
Conditions on the rule—These are filters that further define the rule, such as
specifying that a rule acts on priority 1 tasks only, or that a rule acts on tasks
created by a specific user. The conditions can be based on standard task attributes
as well as any flex fields that have been mapped for the specific tasks. See "Using
the Administration Functions" on page 16-27 for information about mapping flex
fields.
Figure 16–17 shows how you add conditions to a rule.
Figure 16–17
■
Adding Conditions on a Rule
Actions
–
Reassign to—You can reassign tasks to subordinates or groups you manage. If
you have been granted the BPMWorkflowReassign role, then you can reassign
tasks to any user or group.
–
Delegate to—You can delegate to any user or group.
–
Set outcome to—You can specify an automatic outcome if the workflow task
was designed for those outcomes, for example, accepting or rejecting the task.
The rule must be for a specific task type. If a rule is for all task types, then this
option is not displayed.
–
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.
Figure 16–18 shows the Rules List page. Rules are executed in the order in which they
are listed. Use the Move Up and Move Down buttons to reorder 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.
Worklist Application 16-23
Features of the Worklist Application
Figure 16–18 Setting User Rules in Worklist Preferences
Figure 16–18 also shows the following:
■
■
You can create, delete, and edit rules (click the rule name).
A rule is active (see the Active column in Figure 16–18) if the date range you
specified when you created the rule is current.
Group Rules
Use a group rule to specify how a workflow rule applies to members of a group.
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
Creating a group rule is similar to creating other rules (see Figure 16–16, "Creating a
Rule in the Worklist Application"); only some of the actions are different. For group
rules, you can specify the following actions:
■
■
■
Reassign 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. See the following for more
information:
–
"Runtime Config Service" on page 15-109 for more information about
dynamic assignment
–
"Implementing a Dynamic Assignment Function" on page 15-112 for more
information about custom functions
Reassign to—As with user rules, you can reassign 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.
16-24 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
The group Rules List page is similar to the user Rules List page, with the addition of a
list of the groups that you (as the logged-in user) manage. You can select from this list
to specify the group for which you are creating a rule.
Custom Views
Use a custom view to customize your task list display. Examples of custom displays
include:
■
Ordering the task list in a particular way
■
Displaying only those tasks that meet a particular condition
■
Displaying specific attributes (columns) in your task list
You can also grant other users access to your views.
Figure 16–19 shows the Custom Views page.
Figure 16–19
The Custom Views Page
The following functionality is available:
■
■
■
You can create, edit, copy, and delete views, and choose to make the view visible
or not in the My Views section of the Work Queues pane.
For each view in the Granted Views list, you can choose to make the view visible
or not in the Delegated Views section of the Work Queues pane on the Task List
page.
Details are available for granted views. You can rename a view granted to you.
Figure 16–20 shows the Create Custom View page.
Worklist Application 16-25
Features of the Worklist Application
Figure 16–20 Creating a Custom View
You can specify the following when creating a custom view:
■
■
General—You must specify a name for your view.
Columns—You can specify which columns you want to display in your task list.
The columns in the views can be standard task attributes as well as any flex fields
that have been mapped for the specific task type. See "Using the Administration
Functions" on page 16-27 for information about mapping flex fields.
The default columns are the same as the columns in your inbox. You can also
choose to show tasks actions in your task list and select ascending or descending
order for a single column.
■
■
Filter—You can specify which task categories you want to display, for example,
My, Group, My & Group, and so on. You can also add conditions, for example, a
condition that displays a task only when the title contains the words loan request.
Sharing—You can grant access to this view to another user; for example, if jstein
grants access to a My & Group category of tasks to jcooper, then jcooper will see
jstein’s tasks and group tasks. 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 visible in the Proxy Work Queues
section of the worklist (shown in Figure 16–14, "Work Queues Pane").
Display Preferences
Use display preferences to customize how tasks are displayed in your worklist. As
Figure 16–21 shows, you can use the following options to customize the display:
■
Maximum number of tasks per page
■
Page height in pixels
■
Default ordering of tasks
■
Show the following columns in the inbox view
■
Show task actions in task list
16-26 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–21
Setting Display Preferences in the Worklist Application
Using the Administration Functions
Administrators are users who have been granted the BPMWorkflowAdmin role.
Administrators see the following tabs on the Worklist Application home page:
■
Manage Rules
■
Flex Field Mappings
■
Application Customization
Manage Rules
An administrator uses the Manage Rules tab, shown in Figure 16–22, to view or edit
the rules for any user or group.
Worklist Application 16-27
Features of the Worklist Application
Figure 16–22 The Manage Rules Tab
This tab is useful if an administrator is needed to fix a problem with a rule. Also, for a
user who no longer works for the company, administrators can set up a rule for that
user so that all tasks assigned to the user are automatically assigned to another user or
group.
Flex Field Mappings
An administrator uses the Flex Field Mappings tab, shown in Figure 16–23, to promote
data from the payload to inline attribute flex fields. By promoting data to flex fields,
the data becomes searchable and can be displayed as columns in the Task Listing
(home) page.
Figure 16–23 The Flex Field Mappings Tab
Creating 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 Create Label to use the Create Payload Mapping Label interface, as shown in
Figure 16–24.
16-28 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–24
Creating a Label
As the figure shows, the label amount is mapped to the flex field NumberAttribute1,
The payload attribute is also mapped to the label. In this example, the Number
attribute type is associated with the amount label. The end result is that the value of
the Number attribute is stored in the NumberAttribute1 column, and amount is the
column label for that value as 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.
Browsing All Mappings When this option is selected, all flex field mappings defined for
all task types are displayed, as shown in Figure 16–25.
Figure 16–25 Browsing Mappings
To display all the payload attributes mapped to a particular label, click the respective
row in the label table.
Worklist Application 16-29
Features of the Worklist Application
Editing Mappings by Task Type When this option is selected, administrators can view or
edit flex field mappings for a particular task type.
To edit mappings by task type:
1.
Select Edit mappings by task type and click the flashlight icon.
2.
Select a task type and click Select, as shown in Figure 16–26.
Figure 16–26 Selecting a Task Type
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 16–27.
16-30 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–27 Selecting a Label
4.
Select a mapping label and click Select.
Figure 16–28 shows a completed mapping.
Figure 16–28 Flex Field Mapping Created
If you want to create a new label, click Create Label and provide a label name, as
shown in Figure 16–29. Note that the data type will be restricted based on the data
type of the payload attribute.
Worklist Application 16-31
Features of the Worklist Application
Figure 16–29 Creating a Payload Mapping Label
5.
To add a new mapping, click Add Row (if needed) and select a payload attribute
from the list.
6.
Click the flashlight icon and select a label.
Restrictions 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.
Application Customization
An administrator uses the Application Customization tab, shown in Figure 16–30, to
customize the appearance of the Worklist Application.
16-32 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–30
The Application Customization Tab
Values can be specified for the following parameters:
■
Login page realm label—If the identity service is configured with multiple realms,
then the Worklist Application 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.
See "Customizing the Login Page" on page 16-44 for information on customizing
the image on the login page.
■
Branding image location—This is the image displayed in the top left corner of
every page of the Worklist Application. (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 of the Worklist Application.
See "Customizing Header Information" on page 16-44 for information about the
header.
■
Application resource bundle classname—A resource bundle provides the strings
displayed in the Worklist Application. By default, this is the class at:
oracle.bpel.services.workflow.resource.WorkflowResourceBundle
Administrators can change the strings shown in the application by copying
WorkflowResourceBundle and creating their own. This parameter allows
administrators to specify the classpath to this custom resource bundle.
Creating Reports
The Worklist Application offers the following reports from the Reports link:
■
Unattended Tasks Report
■
Tasks Priority Report
■
Tasks Cycle Time Report
■
Tasks Productivity Report
To create a report:
1. Click the Reports link.
2.
Click the name of the report you want.
3.
Provide inputs to define the search parameters of the report.
Worklist Application 16-33
Features of the Worklist Application
See the following sections on each report type for information about input
parameters.
4.
Click Run.
As shown in Figure 16–31, report results (for all report types) are displayed in both a
table format and a bar chart format. The input parameters used to run the report are
displayed under Report Inputs, in the lower-left corner (may require scrolling to
view).
Figure 16–31 Report Display—Table Format, Bar Chart Format, and Report Inputs
Unattended Tasks Report
This report provides an analysis of tasks assigned to users' groups or reportees' groups
that have not yet been claimed (unattended tasks). Use the following input parameters
to define the report:
■
Assignee—The tasks analyzed are based on the category chosen as it applies to the
user; that is, tasks assigned to the user's groups, tasks assigned to the reportee's
groups, tasks where the user is a creator, and tasks where the user is an owner.
■
Creation Date (range)
■
Expiration Date (range)
■
Task State
■
Priority
See Table 16–2 on page 16-6 for descriptions of Creation (or Created) Date, Expiration
Date, Task State (or Status), and Priority.
Figure 16–32 shows an example of an Unattended Tasks Report.
16-34 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–32 Unattended Tasks Report
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.
Tasks Priority Report
This report provides an analysis of the number of tasks assigned to a user, reportees, or
their groups, broken down by priority. Use the following input parameters to define
the report:
■
Assignee—Depending on the assignee that you choose, this includes tasks
assigned to you (My), tasks assigned to you and groups that you belong to (My &
Group), or tasks assigned to groups to which your reportees belong.
■
Creation Date (range)
■
Ended Date (range)—This is the end dates of the tasks to be included in the report.
■
Priority
See Table 16–2 on page 16-6 for descriptions of Creation (or Created) Date and Priority.
Figure 16–33 shows an example of a Tasks Priority Report.
Worklist Application 16-35
Features of the Worklist Application
Figure 16–33 Tasks Priority Report
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.
Tasks Cycle Time Report
This report provides an analysis of the time taken to complete tasks from creation to
completion based on users' groups or reportees' groups. Use the following input
parameters to define the report:
■
Assignee—Depending on the assignee that you choose, this includes your tasks or
tasks assigned to groups to which your reportees belong.
■
Creation Date (range)
■
Ended Date (range)—This is the end dates of the tasks to be included in the report.
■
Priority
See Table 16–2 on page 16-6 for descriptions of Creation (or Created) Date and Priority.
Figure 16–34 shows an example of a Tasks Cycle Time Report.
16-36 Oracle BPEL Process Manager Developer’s Guide
Features of the Worklist Application
Figure 16–34 Tasks Cycle Time Report
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.
Tasks Productivity Report
This report provides an analysis of assigned tasks and completed tasks in a given time
period for a user, reportees, or their groups. Use the following input parameters to
define the report:
■
■
■
Assignee—Depending on the assignee that you choose, this includes your tasks or
tasks assigned to groups to which your reportees belong.
Creation Date (range)—The default is one week.
Task Type—Use the flashlight icon to select from a list of task titles. All versions of
a task are listed on the Select Workflow Task Type page, as shown in Figure 16–35.
Worklist Application 16-37
Features of the Worklist Application
Figure 16–35 Select Workflow Task Type
Figure 16–36 shows an example of a Tasks Productivity Report.
Figure 16–36 Tasks Productivity Report
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.
16-38 Oracle BPEL Process Manager Developer’s Guide
Accessing the Worklist Application in Local Languages
User and Group Information
In the banner area, the logged-in user’s name appears, as in Welcome jstein
[jazn.com]. Click the user name to display information such as the user’s full name,
telephone number, e-mail address, manager, reportees, groups to which the user
belongs, and roles that have been granted, as shown in Figure 16–37.
Figure 16–37 User Information
The roles that have been granted control the actions that the user can perform in the
application. The user can click the manager and reportee links to get user information
by traveling up and down the management chain. Clicking a group displays the
Group Info page for that group. The Group Info page displays the list of direct and
indirect users (users contained in child groups of the current group).
Accessing the Worklist Application in Local Languages
The identity service determines a user’s preferred language and time zone. This
information is extracted from either the JAZN file-based community or from an
external directory service such as Oracle Internet Directory. If no preference
information is available, then the user’s preferred language and time zone are set to
the system default (en_US and America/Los_Angeles, as shown in the following
sample code).
Using the sample worklist configured with the user community in the JAZN XML file,
you can set the user's preferred language and time zone in the
demo-users-properties.xml file as follows:
<timeZone>America/Los_Angeles</timeZone>
<languagePreference>en_US</languagePreference>
Worklist Application 16-39
Accessing the Worklist Application in Local Languages
The demo-users-properties.xml file is found in
SOA_Oracle_Home\bpel\system\services\config
The Worklist Application supports the locales shown in Table 16–4.
Table 16–4
Languages and Java Locales Supported by the Worklist Application
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)
If an LDAP-based provider such as OID is used, then language settings are changed in
the OID community.
When a user opens a browser and logs in to the Worklist Application, the worklist
screens are rendered in the browser’s locale and time zone. Most strings in the
Worklist Application come from the worklist application bundle. By default, this is the
class
oracle.bpel.services.workflow.resource.WorkflowResourceBundle
However, this can be changed to a custom resource bundle by setting the appropriate
application preference. See "Using the Administration Functions" on page 16-27 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 15, "Oracle BPEL Process Manager Workflow
Services" for information on adding entries to this file for dynamic assignment
functions and attribute labels.
For custom actions and task titles, the display names come from the message bundle
specified in the task configuration file. If no message bundle is specified, then the
values specified at design time are used. See Chapter 15, "Oracle BPEL Process
Manager Workflow Services" for information on how to specify message bundles so
that custom actions and task titles are displayed in the preferred language.
16-40 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
Customizing the Worklist Application
The sample Worklist Application described in this chapter is fully functional. Use it as
a starting point to create a customized Worklist Application to suit your specific needs.
This section discusses the architecture of the Worklist Application and provides
specific details for customizing it.
The Worklist Application is available in the samples directory at
SOA_Oracle_Home\bpel\samples\hw\worklistapp
Worklist Application Architecture
The Worklist Application follows the standard model-view-controller approach, as
shown in Figure 16–38.
Figure 16–38
Worklist Application Architecture
Browser
Java
Local EJB
Remote EJB
SOAP
Servlet
Workflow
Service Client
Workflow
Service
JSP
A request coming from the browser is handled by a servlet. The servlet validates the
request and calls the appropriate workflow service client API to query or update data.
The worklist client APIs support a variety of different protocols (local and remote
EJBs, direct java invocation, SOAP) for invoking the underlying workflow service. The
clients send the API request to the workflow services, using the appropriate protocol.
After the API call, the servlet stores the data required for rendering the next page in
the session. The JSP picks up the data from the session, renders the data, and removes
it from the session. Hence the servlets and the JSPs have different functions. The
servlets are responsible for making the back-end API calls and the JSPs are responsible
for formatting the data.
The Worklist Application servlets are at
SOA_Oracle_Home\bpel\samples\hw\worklistapp\src\worklistapp\servlets
All servlets extend the class worklistapp.servlets.BaseServlet. This class
implements common functionality required by all servlets, such as authentication.
The JSPs are at
SOA_Oracle_Home\bpel\samples\hw\worklistapp\public_html
The workflow client API is a public interface made available by the workflow services.
The interface is at
oracle.bpel.services.workflow.client.IWorkflowServiceClient
An instance of the API interface can be obtained by invoking the
getWorkflowServiceClient method on
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory
Worklist Application 16-41
Customizing the Worklist Application
See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for more
information.
A typical page flow sequence is shown in Figure 16–39.
Figure 16–39 A Typical Page Flow Sequence
Browser
Servlet
Login
JSP
Login
User enters
username /
password
Browser
Servlet
Login
Servlet
TaskList
User clicks
on a task
link
Browser
authenticate
Workflow Service
(Task Query Service)
queryTasks
Workflow Service
(Task Query Service)
JSP
TaskList
Servlet
TaskDetails
getTaskDetailsById
Workflow Service
(Task Query Service)
JSP
TaskDetails
This sequence encompasses logging in to the application to view the details of a task.
The first time a user enters the login URL, the login servlet redirects the page to the
login JSP that is sent to the browser. The user enters a username and password and the
login servlet calls the authenticate method on the task query service. If successful,
it redirects to the TaskList servlet URL. The browser's request then goes to the TaskList
servlet that calls the queryTasks method on the task query service for getting the
tasks that the user should see. Then it redirects the page to the TaskList JSP that is sent
to the browser. When a user clicks a task link, the request is handled by the TaskDetails
servlet. This calls the getTaskDetailsById method on the task query service and
redirects the page to the TaskDetails JSP that is sent to the browser. Page flows for
other functionality, such as updating the payload, adding an attachment, reassigning a
task, viewing history, and updating user preferences, are similar.
The separation of responsibility—between servlets that handle API calls and
processing, and JSPs that handle formatting of the data—facilitates customizing the
application. The page flow requirements for many customer requirements are
probably similar to the page flow for the sample Worklist Application. Therefore, it
16-42 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
may be sufficient to modify the JSPs (and the Java class HTMLFormatter.java used
for formatting HTML data).
Table 16–5 lists the Worklist Application JSPs.
Table 16–5
Worklist Application JSPs
JSP
Servlet
Notes
AdminPrefs.jsp
Admin
Application customization preferences
AdvancedSeach.jsp
TaskList
Advanced query for tasklist
Branding.jsp
--
Branding information displayed in the top
left corner of every page
ColumnSelectIncludes.jsp
--
Control that allows users to select a list of
columns. Used in DisplayPrefs.jsp and
ViewEdit.jsp
DisplayPrefs.jsp
Preferences
User display preferences
Error.jsp
--
All servlets redirect to this page when the
exception is caught
FilterForm.jsp
--
Control that allows users to define
advanced task queries. Used in
AdvancedSearch.jsp and ViewEdit.jsp
FilterIncludes.jsp
--
Control that allows users to define task
filtering criteria, used in FilterForm.jsp
and RuleEdit.jsp
Footer.jsp
--
Appears at the bottom of every page
GetHWTaskHistory.jsp
--
--
Header.jsp
--
Appears at the top of every page
HeaderIncludes.jsp
--
Used to include common Javascript
function into the page headers
Home.jsp
Admin
Used as a container for the administrator
pages
IdentityBrowser.jsp
IdentityBrowserPopup
Control that allows users to select users
and groups
IdentityBrowserPopup.jsp
IdentityBrowserPopup
Pop-up window that includes the identity
browser control
Login.jsp
Login
Application login page
PayloadMapping.jsp
Admin
Flex field payload mapping
PayloadMappingBrowser.jsp
PayloadMappingBrowser
Flex field payload mapping
PayloadMappingBrowserPopup.jsp PayloadMappingBrowserPopup
Flex field payload mapping
PayloadMappingEditor.jsp
--
Flex field payload mapping
PayloadMappingLabelPopup.jsp
--
Flex field payload mapping
PopUpHeader.jsp
--
Header displayed in pop-up windows
Preferences.jsp
Preferences
Used as a container for the user
preferences pages
ReportChart.jsp
Reports
Task reporting
ReportEdit.jsp
Reports
Task reporting
ReportInput.jsp
Reports
Task reporting
Worklist Application 16-43
Customizing the Worklist Application
Table 16–5 (Cont.) Worklist Application JSPs
JSP
Servlet
Notes
ReportOutput.jsp
Reports
Task reporting
Reports.jsp
Reports
Container page for the task reporting
pages
RequestInfo.jsp
RequestInfo
Task request info requests
RuleCreate.jsp
Preferences
Create a new workflow rule
RuleEdit
Preferences
Edit workflow rule details
RuleList.jsp
Preferences
Listing of workflow rules
SubTasks.jsp
SubTasks
View task subtasks
TaskAssignees.jsp
TaskAssignee
Handle task reassignment
TaskDetails.jsp
TaskDetails
Display task details
TaskHistory.jsp
TaskHistory
Display task history
TaskList.jsp
TaskList
Main application page. Displays lists of
tasks
TaskRouting.jsp
TaskRouting
Handle updates to task routing
TaskTypeDetails.jsp
TaskType
Display details for workflow tasktype
TaskTypeList.jsp
TaskType
Display a list of task types in a pop-up
window
UserInfo.jsp
UserInfo
Display user information
UserInfoContent.jsp
UserInfo
Display user information
Vacation.jsp
Preferences
User vacation preference
ViewDetails.jsp
Preferences
Details for delegated user task views
ViewEdit.jsp
Preferences
Edit details for owned user task views
ViewList.jsp
Preferences
Listing of user task views
The following sections discuss how to customize some commonly used pages.
Customizing the Login Page
You can customize the image on the login page (the default is an image of people). In
Login.jsp, replace the portion of the image tag shown in bold (people.jpg) with
your own image:
<IMG HEIGHT="55" SRC="img/people.jpg">
See "Application Customization" on page 16-32 for information on customizing the
login page realm label.
Customizing Header Information
The header section appears on every page above the bread crumb navigation. You can
customize the header by modifying the Header.jsp file. The logo and the name of
the application in the left corner are contained in the Branding.jsp file that is
included in the header.
See "Application Customization" on page 16-32 for information on changing the
branding image.
16-44 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
The upper-right area contains HTML controls for filters and search criteria for
retrieving tasks. The filters can be customized to include only those choices that are
relevant to the application.
Customizing the Task Details Page
The Task Details page is used to examine the contents of the task and view or update
the payload. The layout of the details page consists of the actions and buttons at the
top, a header section, the payload section, and the footer section consisting of optional
contents such as comments and attachments. The information displayed on this form
is typically defined by the task definition for the task being displayed (and the format
is controlled by the workflow task designer). You can customize the Task Details page
by modifying the TaskDetails.jsp file. See "Generating a Custom Task Display
Form" on page 15-73 for information on how to customize this file.
Changing the Client-Service Binding for the Worklist Application
The workflow services client interfaces can use a number of protocols to communicate
with the workflow services. The client implementations encapsulate all the
communication details, and users of the client interfaces do not need to be concerned
with the details.
The Worklist Application is deployed in the same container as the workflow services,
by default, and the application uses the Java client.
To switch the client type used by the Worklist Application, modify the init method in
BaseServlet.java as follows:
public void init(ServletConfig config) throws ServletException
{
super.init(config);
try
{
wfSvcClient
= WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.JAVA_CLIENT);
}
catch (Exception e)
{
wlSvcError = getStackTraceString(e);
}
}
Also, change WorkflowServiceClientFactory.JAVA_CLIENT to one of the
following:
■
■
■
WorkflowServiceClientFactory.SOAP_CLIENT—to use the SOAP-based
Web services interface
WorkflowServiceClientFactory.LOCAL_CLIENT—to use the local EJB
interface
WorkflowServiceClientFactory.REMOTE_CLIENT—to use the remote EJB
interface
In addition, ensure that the wf_client_config.xml file is correctly set up for the
client type that you select.
Worklist Application 16-45
Customizing the Worklist Application
Deploying the Custom Application
The top-level directory of the sample Worklist Application contains an ant script,
build.xml, that can be used to build and deploy the Worklist Application. This ant
script makes use of the properties file orabpel.properties that exists in the same
directory.
To deploy the Worklist Application to a standalone OC4J instance:
1. In orabpel.properties, set the following:
■
orabpel.home to BPEL home
■
j2ee.home to BPEL J2EE home
■
OC4J-related properties such as oc4j.ormi.url, oc4j.admin.username,
oc4j.admin.password
2.
Ensure that the classpath includes the correct servlet JAR file.
3.
Run ant oc4j.deploy.
4.
Log in to the custom Worklist Application at
http://hostname:portnumber/integration/custom_app_name
To deploy the Worklist Application on an Oracle Application Server middle tier:
1. In orabpel.properties, set the following:
■
orabpel.home to BPEL home
■
j2ee.home to BPEL J2EE home
■
iAS middle tier-related properties such as ias.home and
ias.oc4j.instance.
2.
Ensure that the classpath includes the correct servlet JAR file.
3.
Run ant iasmid.deploy.
4.
Log in to the custom Worklist Application at
http://hostname:portnumber/integration/custom_app_name
Customizing the Worklist Application Using Preferences
The Worklist Application offers a number of ways to customize its look-and-feel
without editing the JSP code or changing the application servlets.
Every worklist user is able to customize the columns displayed in his inbox, the size of
the worklist page, and how many tasks to display at a time. See "Setting Preferences"
on page 16-21 for more information.
Worklist administrators can also change a number of preferences that influence the
appearance of the Worklist Application for all users, such as the branding image.
Administrators can specify a different resource bundle and change the label for the list
of realms on the login screen. See "Using the Administration Functions" on page 16-27
for more information.
Configuring Display Names for Task Attributes Using WorkflowLabels.properties
You can change the names used for various task attributes in the application by
updating the following file (and its associated translations):
SOA_Oracle_Home/bpel/system/services/config/wfresource/WorflowLabels.properties
16-46 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
Note that this changes the labels returned by the task metadata service methods
getTaskAttributes and getTaskAttributesForTaskDefinition. Any
service clients that use these methods will be affected.
Controlling Access to Information and Actions for Different Users
The workflow service uses the identity service that supports the JAZN file-based
community or LDAP communities such as Oracle Internet Directory. A static set of
role-actions (privileges) has been defined and assigned to roles. Users then get those
privileges by way of roles assigned to them. The most important of the role-actions
currently defined include:
■
CLAIM
■
WITHDRAW
■
ESCALATE
■
RENEW
■
RELEASE
■
REQUEST_INFO
■
SUBMIT_INFO
■
CUSTOM
■
ADMIN
■
REASSIGN
■
SUSPEND
■
RESUME
■
VIEW_TASK_HISTORY
The role-actions apply globally; that is, at the application level and not at the process
level or instance level.
You can customize the Worklist Application so that the information viewed and the
actions performed on a given page are altered for different sets of users. The first part
consists of creating new roles and assigning them to the required users. Then, in the
JSP, the identity service can be used to check if the user has the granted role and to
determine which code path to take.
For example, you can create a new role called BPMProcessingManager in
jazn-data.xml. This file is at
SOA_Oracle_Home\bpel\system\appserver\oc4j\j2ee\home\config
The required users must be assigned this role, as shown in the following code
example:
...
<role>
<name>BPMProcessingManager</name>
<members>
<member>
<type>user</type>
<name>jstein</name>
</member>
</members>
</role>
Worklist Application 16-47
Building Clients for Workflow Services
...
If an LDAP-based service such as OID is used, then these roles must be created and
granted to users in that service.
The JSP code can be customized using the identity service as follows.
import="oracle.tip.pc.services.common.ServiceFactory"
import="oracle.tip.pc.services.identity.*"
boolean canEditTaskHeaderPriority = false;
// get info from identity service
try
{
BPMAuthorizationService authorizationService =
ServiceFactory.getAuthorizationServiceInstance(realm);
// lookup user based on worklist context user
BPMUser bpmUser = authorizationService.lookupUser(user);
// check for BPMProcessManager role
if (bpmUser.isInRole("BPMProcessingManager "))
canEditTaskHeaderPriority = true;
}
catch (Exception e)
{
out.println("Could not get information from identity service");
}
// use the canEditTaskHeaderPriority flag to control HTML behavior
if (canEditTaskHeaderPriority)
// display the priority information & edit controls
else
// just display the priority information
Building Clients for Workflow Services
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.
You can start with the sample Worklist Application to build your own application.
The typical sequence of calls when building a simple worklist application is as follows:
1.
Get a handle to IWorklistServiceClient from
WorkflowServiceClientFactory.
2.
Get a handle to ITaskQueryService from IWorklistServiceClient.
3.
Authenticate a user by passing a username and password to the authenticate
method on ITaskQueryService. Get a handle to IWorkflowContext.
4.
Query the list of tasks using ITaskQueryService.
5.
Get a handle to ITaskService from IWorklistServiceClient.
6.
Iterate over the list of tasks returned, performing actions on the tasks using
ITaskService.
Example 16–1 demonstrates how to build a client for workflow services. A list of all
tasks assigned to jstein is queried. A task whose outcome has not been set is approved.
16-48 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
Example 16–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");
//Query a list of tasks assigned to jstein
List tasks = querySvc.queryTasks(ctx,
queryColumns,
null, //Do not query addtional info
ITaskQueryService.ASSIGNMENT_FILTER_MY,
null, //No keywords
null, //No custom predicate
null, //No special ordering
0,
//Do not page the query result
0);
//Get the task service
ITaskService taskSvc = wfSvcClient.getTaskService();
//Loop over the tasks, outputting task information, and approving any
//tasks whose outcome has not been set...
for(int i = 0 ; i < tasks.size() ; i ++)
{
Task task = (Task)tasks.get(i);
int taskNumber = task.getSystemAttributes().getTaskNumber();
String title = task.getTitle();
String taskId = task.getSystemAttributes().getTaskId();
String outcome = task.getSystemAttributes().getOutcome();
if(outcome == null)
{
outcome = "APPROVED";
taskSvc.updateTaskOutcome(ctx,taskId,outcome);
}
System.out.println("Task #"+taskNumber+" ("+title+") is "+outcome);
}
}
catch (Exception e)
{
//Handle any exceptions raised here...
System.out.println("Caught workflow exception: "+e.getMessage());
}
Worklist Application 16-49
Building Clients for Workflow Services
See Also:
■
The following samples, which demonstrate how to write a custom UI for
the Worklist Application:
SOA_Oracle_home\bpel\samples\utils\AsyncLoanService\StarLoanUI
SOA_Oracle_home\bpel\samples\demos\HelpDeskServiceRequest\HelpDeskUI
SOA_Oracle_home\bpel\samples\demos\ExpenseRequestApproval\
ExpenseRequestUI
■
SOA_Oracle_Home\bpel\docs\workflow\index.html for Javadoc
that describes the workflow service APIs
Packages and Classes for Building Clients
Use the following packages and classes for building clients:
■
oracle.bpel.services.workflow.metadata.config.model
The classes in this package contain the object model for the workflow
configuration in the task definition file. The ObjectFactory class can be used to
create objects.
■
oracle.bpel.services.workflow.metadata.routingslip.model
The classes in this package contain the object model for the routing slip. The
ObjectFactory class can be used to create objects.
■
oracle.bpel.services.workflow.metadata.taskdisplay.model
The classes in this package contain the object model for the task display. The
ObjectFactory class can be used to create objects.
■
oracle.bpel.services.workflow.metadata.taskdefinition.model
The classes in this package contain the object model for the task definition file. The
ObjectFactory class can be used to create objects.
■
oracle.bpel.services.workflow.client.IWorkflowServiceClient
Interface for the workflow service client.
■
oracle.bpel.services.workflow.client.WorkflowServiceClientFacto
ry
The factory for creating the workflow service client.
■
oracle.bpel.services.workflow.metadata.ITaskMetadataService
The interface for task metadata service.
■
oracle.bpel.services.workflow.task.ITaskService
The interface for task service.
■
oracle.bpel.services.workflow.task.IRoutingSlipCallback
The interface for callback class to receive callbacks during task processing.
■
oracle.bpel.services.workflow.task.IAssignmentService
The interface for the assignment service.
Workflow Service Client
Any worklist application accesses the various workflow services through the
workflow service client. The workflow service client code encapsulates all the logic
16-50 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
required for communicating with the workflow services using different local and
remote protocols. After the worklist application has an instance of the workflow
service client, it does not need to consider how the client communicates with the
workflow services.
The advantages of using the client are as follows:
■
■
■
Hides the complexity of the underlying connection mechanisms such as
SOAP/HTTP and EJB
Facilitates changing from using one particular invocation mechanism to another,
for example from SOAP/HTTP to remote EJB
Helps to program with Java APIs for service input/outputs instead of XML
inputs/outputs for SOAP/HTTP or Java WSIF invocation mechanism
The following class is used to create instances of the IWorkflowServiceClient
interface:
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory
WorkflowServiceClientFactory has a single method,
getWorkflowServiceClient, which takes a single parameter, the client type. The
client type can be one of the following:
■
■
■
■
WorkflowServiceClientFactory.JAVA_CLIENT—The client uses Java to
invoke the workflow services directly.
WorkflowServiceClientFactory.LOCAL_CLIENT—The client uses a local
EJB interface to invoke the workflow services.
WorkflowServiceClientFactory.REMOTE_CLIENT—The client uses a
remote EJB interface to invoke workflow services located remotely from the client.
WorkflowServiceClientFactory.SOAP_CLIENT—The client uses SOAP to
invoke Web service interfaces to the workflow services, located remotely from the
client.
Through the factory, it is possible to get the client libraries for all the workflow
services. Table 16–6 shows the clients available for each of the services.
Table 16–6
Clients Available for the Workflow Services
Service Name
Supports SOAP Supports
Supports Supports Plain
Web Services
Remote EJB Local EJB Java APIs
Task Service
Yes
Yes
Yes
Task Query Service
Yes
Yes
Yes
Yes
Task Metadata Service
Yes
Yes
Yes
Yes
Task Reports Service
Yes
User Metadata Service
Yes
Yes
Yes
Yes
Runtime Config Service
Yes
Yes
Yes
Yes
Identity Service:
■
■
BPM Authentication
Service
Yes
Yes
BPM Authorization
Service
Yes
Yes
Worklist Application 16-51
Building Clients for Workflow Services
The client classes use the configuration file wf_client_config.xml for the service
end points. This file is at
SOA_Oracle_Home/bpel/system/services/config
In the client classpath, this file should be in the classpath directly, meaning the
containing directory should be 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>
■
A section for SOAP end points for each of the services
<taskService>
<soapEndPoint>http://localhost:9700/integration/services/TaskService/
TaskServicePort</soapEndPoint>
</taskService>
See Also:
■
The following for more information about task services:
Table 15–16, " SOAP WSDL Location for the Task Services" on
page 15-95
■
Table 15–17, " Task Service Methods" on page 15-97
■
Table 15–18, " Task Query Service Methods" on page 15-99
■
Table 15–19, " Task Metadata Service Methods" on page 15-107
■
Table 15–20, " User Metadata Service Methods" on page 15-108
■
Table 15–21, " Runtime Config Service" on page 15-110
The IWorkflowServiceClient Interface
The IWorkflowServiceClient interface provides methods, summarized in
Table 16–7, for obtaining handles to the various workflow services interfaces.
Table 16–7
IWorkflowServiceClient Methods
Method
Interface
getTaskService
oracle.bpel.services.workflow.task.ITaskService
getTaskQueryService
oracle.bpel.services.workflow.query.ITaskQueryService
getTaskReportService
oracle.bpel.services.workflow.report.ITaskReportService
getTaskMetadataService
oracle.bpel.services.workflow.metadata.ITaskMetadataService
getUserMetadataService
oracle.bpel.services.workflow.user.IUserMetadataService
16-52 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
Table 16–7 (Cont.) IWorkflowServiceClient Methods
Method
Interface
getRuntimeConfigService
oracle.bpel.services.workflow.runtimeconfig.IRuntimeConfigService
getAuthenticationService
oracle.tip.pc.services.identity.BPMAuthenticationService
getAuthorizationService
oracle.tip.pc.services.identity.BPMAuthorizationService
Classpaths for Java Clients
The following JAR files are necessary for the Java client classpath.
■
$BPEL_HOME/bpel/lib/bpm-infra.jar
■
$BPEL_HOME/bpel/lib/orabpel-common.jar
■
$BPEL_HOME/bpel/lib/orabpel-thirdparty.jar
■
$BPEL_HOME/bpel/lib/orabpel.jar
■
$BPEL_HOME/bpel/system/appserver/oc4j/j2ee/home/jazncore.jar
■
$BPEL_
HOME/bpel/system/appserver/oc4j/j2ee/home/oc4jclient.jar
■
$BPEL_HOME/bpel/system/appserver/oc4j/lib/xml.jar
■
$BPEL_HOME/bpel/system/appserver/oc4j/lib/xmlparserv2.jar
■
$BPEL_
HOME/bpel/system/appserver/oc4j/webservices/lib/orasaaj.jar
■
$BPEL_
HOME/bpel/system/appserver/oc4j/webservices/lib/soap.jar
■
$BPEL_HOME/bpel/system/services/config
■
$BPEL_HOME/bpel/system/services/lib/bpm-services.jar
■
$BPEL_HOME/bpel/system/services/schema
■
wsclient_extended.zip
Note: The wsclient_extended.jar file is available as a separate
download from the Oracle Technology Network at
http://download.oracle.com/otn/java/oc4j/1013/
wsclient_extended.zip
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
EJB References in Web Applications
If a Web application uses the workflow service local EJBs, then the client application
must do the following:
■
■
The application must be a child application of the hw_services application.
The application must define the EJB local references in its web.xml file. The local
references for each of the services are shown in Example 16–2 and Example 16–3.
Worklist Application 16-53
Building Clients for Workflow Services
Example 16–2 Task Service
<ejb-local-ref id="EjbRef_TaskServiceBean_Message">
<ejb-ref-name>ejb/local/TaskServiceBean</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>oracle.bpel.services.workflow.task.ejb.TaskServiceLocalHome</local-home>
<local>oracle.bpel.services.workflow.task.ejb.TaskServiceLocal</local>
<ejb-link>TaskServiceBean</ejb-link>
</ejb-local-ref>
Example 16–3 Task Metadata Service
<ejb-local-ref id="EjbRef_TaskMetadataServiceBean_Message">
<ejb-ref-name>ejb/local/TaskMetadataServiceBean</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>oracle.bpel.services.workflow.metadata.ejb.TaskMetadataServiceLocalHome</local-home>
<local>oracle.bpel.services.workflow.metadata.ejb.TaskMetadataServiceLocal</local>
<ejb-link>TaskMetadataServiceBean</ejb-link>
</ejb-local-ref>
Only child applications can use local EJBs. This restricts
standalone Java clients to using either remote EJBs or SOAP clients.
Note:
See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for more
information on the task query service, task report service, user metadata service, and
runtime config service.
Initiating a Task
Tasks can be initiated programmatically, in which case the following task attributes
must be set:
■
taskDefinitionURI
■
title
■
payload
■
priority
The following task attributes are optional, but are typically set by clients:
■
creator
■
ownerUser—Defaults to bpeladmin if empty
■
processInfo
■
identificationKey—Tasks can be queried based on the identification key from
the TaskQueryService
Creating a Task
The task object model is available in the package
oracle.bpel.services.workflow.task.model
To create objects in this model, use the ObjectFactory class.
16-54 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
Creating a Payload Element in a Task
The task payload can contain multiple payload message attributes. Since the payload
is not well defined until the task definition, the Java object model for the task does not
contain strong type objects for the client payload. The task payload is represented by
the AnyType Java object. The AnyType Java object is created with an XML element
whose root is payload in the namespace
http://xmlns.oracle.com/bpel/workflow/task
The payload XML element contains all the other XML elements in it. Each XML
element defines a message attribute.
Example 16–4 shows how to set a task payload.
Example 16–4
Setting a Task Payload
import oracle.bpel.services.workflow.task.model.AnyType;
import oracle.bpel.services.workflow.task.model.ObjectFactory;
import oracle.bpel.services.workflow.task.model.Task;
..........
Document document = //createXMLDocument
Element payloadElem = document.createElementNS("http://xmlns.oracle.com/bpel/workflow/
task", "payload");
Element orderElem = document.createElementNS("http://xmlns.oracle.com/pcbpel/test/order", "order");
Element child = document.createElementNS("http://xmlns.oracle.com/pcbpel/test/order", "id");
child.appendChild(document.createTextNode("1234567"));
orderElem.appendChild(child);
payloadElem.appendChild(orderElem);
document.appendChild(payloadElem);
task.setPayloadAsElement(payloadElem);
The AnyType.getContent() element returns an
unmodifiable list of XML elements. You cannot add other message
attributes to the list.
Note:
Initiating a Task Programmatically
Example 16–5 shows how to initiate a vacation request task programmatically.
Example 16–5
Initiating a Vacation Request Task Programmatically
// create task object
ObjectFactory objectFactory = new ObjectFactory();
Task task = objectFactory.createTask();
// set title
task.setTitle("Vacation request for jcooper");
// set creator
task.setCreator("jcooper");
// set task definition URI
task.setTaskDefinitionURI("http://localhost:9700/orabpel/default/VacationRequest/1.0/
VacationApproval/VacationApproval.task");
// create and set payload
Document document = XMLUtil.createDocument();
Worklist Application 16-55
Building Clients for Workflow Services
Element payloadElem = document.createElementNS(TASK_NS, "payload");
Element vacationRequestElem = document.createElementNS(VACATION_REQUEST_NS,
"VacationRequestProcessRequest");
Element creatorChild = document.createElementNS(VACATION_REQUEST_NS, "creator");
creatorChild.appendChild(document.createTextNode("jcooper"));
vacationRequestElem.appendChild(creatorChild);
Element fromDateChild = document.createElementNS(VACATION_REQUEST_NS, "fromDate");
fromDateChild.appendChild(document.createTextNode("2006-08-05T12:00:00"));
vacationRequestElem.appendChild(fromDateChild);
Element toDateChild = document.createElementNS(VACATION_REQUEST_NS, "toDate");
toDateChild.appendChild(document.createTextNode("2006-08-08T12:00:00"));
vacationRequestElem.appendChild(toDateChild);
Element reasonChild = document.createElementNS(VACATION_REQUEST_NS, "reason");
reasonChild.appendChild(document.createTextNode("Hunting"));
vacationRequestElem.appendChild(reasonChild);
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;
See "Vacation Request Example" on page 15-85 for more information.
Writing a Worklist Application Using the HelpDeskUI Sample
The following example shows how to modify the help desk interface that is part of the
HelpDeskServiceRequest demo found at
SOA_Oracle_home\bpel\samples\demos\HelpDeskServiceRequest\HelpDeskUI
To write a Worklist Application
1. Create the workflow context by authenticating the user.
// get workflow service client
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.JAVA_CLIENT);
//get the workflow context
IWorkflowContext wfCtx =
wfSvcClient.getTaskQueryService().authenticate(userId, pwd,
oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(),
null);
This is Step 3 in "Building Clients for Workflow Services" on page 16-48.
16-56 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
The login.jsp file of HelpDeskServiceRequest uses the preceding API to
authenticate the user and create a workflow context. After the user is
authenticated, the statusPage.jsp file displays the tasks assigned to the
logged-in user. Example 16–6 shows sample code from the login.jsp file.
Example 16–6
Login.jsp
<%@ page import="javax.servlet.http.HttpSession"
import="oracle.bpel.services.workflow.client.IWorkflowServiceClient"
import="oracle.bpel.services.workflow.client.WorkflowServiceClientFactory"
import="java.util.Set"
import="java.util.Iterator"
import="oracle.bpel.services.workflow.verification.IWorkflowContext"
import="oracle.tip.pc.services.identity.config.ISConfiguration"%>
<%@ page contentType="text/html;charset=windows-1252"%>
<html>
<head>
<title>Help desk request login page</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#F0F0F0" text="#000000" style="font: 12px verdana; line-height:18px">
<center>
<div style="width:640px;padding:15px;border-width: 10px; border-color: #87b4d9; border-style:
solid;
background-color:white; text-align:left">
<!-- Page Header, Application banner, logo + user status -->
<jsp:include page="banner.jsp"/>
<!-- Initiate Meta Information -->
<div style="background-color:#F0F0F0; border-top:10px solid white;border-bottom:
10px solid white;padding:10px;text-align:center" >
<b>Welcome to the HelpDesk application</b>
</div>
<%
String redirectPrefix = "/HelpDeskUI/";
// Ask the browser not to cache the page
response.setHeader("Pragma", "no-cache");
response.setHeader("Cache-Control", "no-cache");
HttpSession httpSession = request.getSession(false);
if (httpSession != null) {
IWorkflowContext ctx = (IWorkflowContext) httpSession.getAttribute("workflowContext");
if (ctx != null) {
response.sendRedirect(redirectPrefix + "statusPage.jsp");
}
else
{
String authFailedStr = request.getParameter("authFailed");
boolean authFailed = false;
if ("true".equals(authFailedStr))
{
authFailed = true;
}
else
Worklist Application 16-57
Building Clients for Workflow Services
{
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");
}
if(userId != null && (!("".equals(userId.trim())))
&& pwd != null && (!("".equals(pwd.trim()))))
{
try {
HttpSession userSession = request.getSession(true);
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");
}
}
}
%>
<form action='<%= request.getRequestURI() %>' method="post">
<div style="width:100%">
<table cellspacing="2" cellpadding="3" border="0" width="30%" align="center">
<tr>
<td>Username
</td>
<td>
<input type="text" name="userId"/>
</td>
</tr>
<tr>
<td>Password
16-58 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
</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>
2.
Query tasks using the queryTask API from TaskQueryService.
//add list of attributes to be queried from the task
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");
// get the list of tasks
List tasks = wfSvcClient.getTaskQueryService().queryTasks
(wfCtx,
displayColumns,
null,
ITaskQueryService. ASSIGNMENT_FILTER_MY_AND_GROUP,
null,
null,
null,
0,
0);
// create listing page by using above tasks
//add href links to title to display details of the task by passing taskId
as input parameter
Use getTaskDetailsById(IWorkflowContext wftx, String taskId);
This is Step 4 in "Building Clients for Workflow Services" on page 16-48.
The statusPage.jsp file of HelpDeskServiceRequest is used to display the
status of help desk requests. Example 16–7 shows the statusPage.jsp example
code.
Example 16–7
statusPage.jsp
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<%@ page import="oracle.tip.pc.services.identity.BPMAuthorizationService,
oracle.bpel.services.workflow.verification.IWorkflowContext,
Worklist Application 16-59
Building Clients for Workflow Services
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) {
ctx = (IWorkflowContext) httpSession.getAttribute("workflowContext");
if (ctx != null) {
bpmUser = getAuthorizationService(ctx.getIdentityContext()).
lookupUser(ctx.getUser());
}
else
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
16-60 Oracle BPEL Process Manager Developer’s Guide
Building Clients for Workflow Services
}
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>
Worklist Application 16-61
Building Clients for Workflow Services
<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++)
{
16-62 Oracle BPEL Process Manager Developer’s Guide
Summary
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>
Summary
This chapter describes how to access a user's tasks, view task details, and perform
actions on the tasks in the sample Oracle BPEL Worklist Application. 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. Instructions are provided for customizing the Worklist
Application (including a number of language settings) and for building your own
Worklist Application using the workflow service APIs.
Worklist Application 16-63
Summary
16-64 Oracle BPEL Process Manager Developer’s Guide
17
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:
■
Use Cases for Sensors
■
Overview of Sensor Concepts
■
Implementing Sensors and Sensor Actions in Oracle JDeveloper
■
Sensors and Oracle BPEL Control
■
Sensor Integration with Oracle Business Activity Monitoring
■
Sensor Public Views
■
Sensor Actions XSD File
■
Summary
Use Cases for Sensors
Using sensors is demonstrated in the sample 125.ReportsSchema. The sample uses
sensors to identify key data during an employee update process and a sensor action to
publish information about the update to the database.
See: SOA_Oracle_
Home\bpel\samples\tutorials\125.ReportsSchema
Inserting sensors on activities is also demonstrated in the OrderBooking tutorial.
See:
Oracle BPEL Process Manager Order Booking Tutorial
Overview of Sensor Concepts
You can define the following types of sensors, either through Oracle JDeveloper or
manually by providing sensor configuration files.
■
Activity sensors
Activity sensors are used to monitor the execution of activities within a BPEL
process. For example, they can be used to monitor the execution time of an invoke
activity or how long it takes to complete a scope. Along with the activity sensor,
you can also monitor variables of the activity.
Sensors 17-1
Implementing Sensors and Sensor Actions in Oracle JDeveloper
■
Variable sensors
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:
■
sensor.xml—contains the sensor definitions of a BPEL process
■
sensorAction.xml—contains the sensor action definitions of a BPEL process
See "Configuring Sensors" on page 17-3 and "Configuring Sensor Actions" on
page 17-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
Implementing Sensors and Sensor Actions in Oracle JDeveloper
In Oracle JDeveloper, sensor actions and sensors are displayed as part of the process
tree structure, as shown in Figure 17–1.
17-2 Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in Oracle JDeveloper
Figure 17–1 Sensors and Sensor Actions Displayed 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.
See Also: The LoanDemoPlus tutorial, at SOA_Oracle_
Home\bpel\samples\demos
Configuring Sensors
If you are monitoring the LoanFlow application, you may want to know when the
getCreditRating scope is initiated, when it is completed, and, at completion, what
the credit rating for the customer is. The solution is to create an activity sensor for the
getCreditRating scope in Oracle JDeveloper, as shown in Figure 17–2. Activities
that have sensors associated with them are identified with a magnifying glass in
Oracle JDeveloper.
Sensors 17-3
Implementing Sensors and Sensor Actions in Oracle JDeveloper
Figure 17–2 Creating an Activity Sensor
The Evaluation Time attribute shown in Figure 17–2 controls the point at which the
sensor fires. You can select from the following:
■
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.
■
All—Monitoring occurs during all of the preceding phases.
A new entry is created in the sensor.xml file, as follows:
<sensor sensorName="CreditRatingSensor"
classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent"
kind="activity"
target="getCreditRating">
<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 17–3.
17-4 Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in Oracle JDeveloper
Figure 17–3 Creating a Variable Sensor
A new entry is created in the sensor.xml file, as follows:
<sensor sensorName="LoanApplicationSensor"
classname="oracle.tip.pc.services.reports.dca.agents.BpelVariableSensorAgent"
kind="variable"
target="$input/payload">
<variableConfig outputNamespace="http://www.autoloan.com/ns/autoloan"
outputDataType="loanApplication"/>
</sensor>
If you want to monitor faults from the identity service, create a fault sensor, as shown
in Figure 17–4.
Figure 17–4 Creating a Fault Sensor
A new entry is created in the sensor.xml file, as follows:
<sensor sensorName="IdentityServiceFault"
classname="oracle.tip.pc.services.reports.dca.agents.BpelFaultSensorAgent"
kind="fault"
Sensors 17-5
Implementing Sensors and Sensor Actions in Oracle JDeveloper
target="is:identityServiceFault">
<faultConfig/>
</sensor>
Configuring Sensor Actions
When you create sensors, you identify the activities, variables, and faults you want to
monitor during run time. If you want to publish the values of the sensors to an
endpoint (for example, you want to publish the data of LoanApplicationSensor to
a JMS queue), then create a sensor action, as shown in Figure 17–5, and associate it
with the LoanApplicationSensor.
Figure 17–5 Creating a Sensor Action
A new entry is created in the sensorAction.xml file, as follows:
<action name="BAMFeed"
enabled="true"
publishType="JMSQueue"
publishTarget="jms/bamTopic">
<sensorName>LoanApplicationSensor</sensorName>
<property name=“JMSConnectionFactory“>
jms/QueueConnectionFactory
</property>
</action>
If you want to publish the values of LoanApplicationSensor and
CreditRatingSensor to the reports schema in the database, create an additional
sensor action, as shown in Figure 17–6, and associate it with both
CreditRatingSensor and LoanApplicationSensor.
Figure 17–6 Creating an Additional Sensor Action
A new entry is created in the sensorAction.xml file, as follows:
17-6 Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in Oracle JDeveloper
<action name="PersistingAction"
enabled="true"
publishType="BPELReportsSchema">
<sensorName>LoanApplicationSensor</sensorName>
<sensorName>CreditRatingSensor</sensorName>
</action
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 17–7.
Figure 17–7 Creating a Sensor Action with a Filter
A new entry is created in the sensorAction.xml file, as follows:
<action name="BigMoneyBAMAction"
enabled='true'
filter="boolean(/s:actionData/s:payload
/s:variableData/s:data
/autoloan:loanAmount > 100000)"
publishType="JMSQueue"
publishTarget="jms/bigMoneyQueue">
<sensorName>LoanApplicationSensor</sensorName>
<property name=“JMSConnectionFactory“>
jms/QueueConnectionFactory
</property>
</action>
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 17–8. The name in the Publish Target field denotes a fully qualified Java class
name that must be implemented.
Sensors 17-7
Implementing Sensors and Sensor Actions in Oracle JDeveloper
Figure 17–8 Using the Custom Publish Type
Publishing to Remote Topics and Queues
The JMS Queue and JMS Topic publish types only publish to local JMS destinations. If
you want to publish sensor data to remote topics and queues, use the JMS adapter
publish type, as shown in Figure 17–9.
Figure 17–9 Using the JMS Adapter Publish Type
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
Creating a Custom Data Publisher
To create a custom data publisher, double-click your BPEL project in Oracle
JDeveloper and do the following:
1.
Select Project Properties > Libraries > Add Jar/Directory from the Tools main
menu.
2.
Browse and select SOA_Oracle_Home\bpel\lib\orabpel.jar.
17-8 Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in Oracle JDeveloper
3.
Create a new Java class.
The package and class name must match the publish target name of the sensor
action.
4.
Implement the com.oracle.bpel.sensor.DataPublisher interface.
This updates the source file and fills in the methods and import statements of the
DataPublisher interface.
5.
Using the Oracle JDeveloper editor, implement the publish method of the
DataPublisher interface, as shown in the following sample custom data
publisher class.
Sensors 17-9
Implementing Sensors and Sensor Actions in Oracle JDeveloper
6.
Ensure that the class compiles successfully.
The next time that you deploy the BPEL process, the Java class is added to the
BPEL suitcase and deployed to Oracle BPEL Process Manager.
17-10 Oracle BPEL Process Manager Developer’s Guide
Sensors and Oracle BPEL Control
Note: Ensure that additional Java libraries needed to implement the
data publisher are in the CLASSPATH of the Oracle BPEL Server.
Oracle BPEL Process Manager can execute multiple process instances
simultaneously, so ensure that the code in your data publisher is
thread safe, or add appropriate synchronization blocks. To guarantee
high throughput, do not use shared data objects that require
synchronization.
Registering the Sensors and Sensor Actions in bpel.xml
Oracle JDeveloper automatically updates the process deployment file bpel.xml to
include appropriate properties for sensors and sensor actions, as follows:
<configurations>
…
<property name="sensorLocation">sensor.xml</property>
<property name="sensorActionLocation">sensorAction.xml</property>
…
<property name="SLACompletionTime">P0YT1.5S</property>
</configurations>
You can specify additional properties with <property name= ...>, as shown in the
preceding code sample.
Sensors and Oracle BPEL Control
The console provides support to view the metadata of sensors and sensor actions as
well as the sensor data created as part of the process execution. Access Oracle BPEL
Control at
http://localhost:port/BPELConsole
You can also select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL
Process Manager > BPEL Control.
Viewing Sensor and Sensor Action Definitions
After the BPEL process is deployed to Oracle BPEL Process Manager, you can view the
definitions of sensors and sensor actions without going back to Oracle JDeveloper. In
Oracle BPEL Control, click the BPEL Processes tab and choose the process for which
you want to see sensor definitions. Click the Sensors link. A page similar to
Figure 17–10 is displayed.
Sensors 17-11
Sensors and Oracle BPEL Control
Figure 17–10 Sensor Data on the BPEL Processes Tab of Oracle BPEL Control
Viewing Sensor Data
The console provides support to monitor sensors for which a BpelReportsSchema
sensor action is defined. In Oracle BPEL Control, click the Instances tab and choose
the process instance for which you want to see the sensor data created as the result of
process execution. A page similar to Figure 17–11 is displayed.
17-12 Oracle BPEL Process Manager Developer’s Guide
Sensor Integration with Oracle Business Activity Monitoring
Figure 17–11 Sensor Data on the Instances Tab of Oracle BPEL Control
Only sensors associated with a database sensor action are
displayed in Oracle BPEL Control. Sensors associated with a JMS
queue, JMS topic, or custom sensor action are not displayed.
Note:
Sensor Integration with Oracle Business Activity Monitoring
Oracle Business Activity Monitoring (BAM) enables you to monitor business services
and processes in an enterprise, correlate key performance indicators (KPIs), and
change business processes or take corrective actions if the business environment
changes.
Oracle BAM enables you to build real-time operational dashboards and monitoring
and alerting applications over the Web. Using this technology, you build interactive,
real-time dashboards and proactive alerts to monitor business services and processes.
You can create sensor actions in Oracle BPEL Process Manager to publish sensor data
as data objects on an Oracle BAM Server. When you create the sensor action, you can
select an Oracle BPEL Process Manager variable or activity sensor that you want to
monitor and the data object in Oracle BAM Server in which you want to publish the
Sensors 17-13
Sensor Integration with Oracle Business Activity Monitoring
sensor data. Oracle BAM Server publishes the data objects and types information in
WSDL files. It uses basic HTTP authentication to enable access to these files.
This section contains the following topics:
■
Creating a Connection to Oracle BAM Server
■
Creating a Sensor
■
Creating a BAM Sensor Action
These instructions assume you have installed and configured Oracle BAM.
See Also:
Oracle Business Activity Monitoring Administrator’s Guide
Creating a Connection to Oracle BAM Server
Only one Oracle BAM Server per BPEL project is currently
supported.
Note:
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 Connection Navigator from the View main menu in Oracle JDeveloper.
2.
Right click BAM Server.
3.
Select New BAM Server Connection.
4.
Click Next on the Welcome page.
5.
Provide a name for connecting to the server.
6.
Click Next.
7.
Enter the following connection information about the Oracle BAM Server host.
Field
Description
Host Name
Enter the name of the host on which Oracle BAM Server is
installed. Depending on your organization's security policy, the
fully-qualified host name may be required.
Port Number
Enter the port number or accept the default value of 80.
User Name
Enter your Windows domain user name. Oracle BAM Server
uses the Windows domain for authentication.
Password
Enter the password of the domain user name.
Domain Name
Enter the domain name in which the Oracle BAM Server host is
located. This field is case sensitive. If you do not enter the correct
case sensitive name, you receive an authentication failure error.
Use secure HTTP protocol
Select this check box if you want to use secure HTTP (HTTP/S)
to connect to the Oracle BAM Server. Otherwise, HTTP is used.
8.
Click Next.
9.
Test the connection by clicking Test Connection. If the connection was successful,
the following message appears:
Success.
17-14 Oracle BPEL Process Manager Developer’s Guide
Sensor Integration with Oracle Business Activity Monitoring
10. Click Finish.
Oracle JDeveloper reserves the following property names. These property names
define values for the Oracle BAM Server connection you just created.
■
bamserver.hostname
■
bamserver.protocol
■
bamserver.username
■
bamserver.password
■
bamserver.port
■
bamserver.domain
These property names are added in the Preferences tab of the Deployment Descriptor
Properties window. If your BPEL process uses a BAM sensor action and you want run
time to use a different Oracle BAM Server than the one used during design time, you
must update these values prior to BPEL process deployment. If you have already
deployed the process, then you can use Oracle BPEL Control to update these values.
See Also:
■
■
Chapter 19, "BPEL Process Deployment and
Domain Management"
Appendix C, "Deployment Descriptor Properties"
Creating a Sensor
You must create one of the following types of sensors prior to creating a BAM sensor
action:
■
■
A variable sensor. Since you map the sensor data to Oracle BAM Server data
objects, only one variable is allowed for the sensor. If the variable has message
parts, then there should be only one message part. This variable must not be
defined inline in the WSDL. Only XSD element definitions are supported.
An activity sensor containing exactly one sensor variable.
See Also: "Implementing Sensors and Sensor Actions in Oracle
JDeveloper" on page 17-2 for instructions on creating sensors
Creating a BAM Sensor Action
When you create the sensor action, you select the BPEL variable or activity sensor that
you want to monitor and the data object in Oracle BAM Server in which you want to
publish the sensor data.
1.
Right click Sensor Actions in the Structure section of Oracle JDeveloper.
2.
Select Create > BAM Sensor Action.
The Create Sensor Action window appears. You create BAM sensor actions to
publish sensor data to data objects on Oracle BAM Server.
Sensors 17-15
Sensor Integration with Oracle Business Activity Monitoring
3.
Enter the following details:
Field
Description
Action Name
Enter a unique and recognizable name for the sensor action.
Select Sensor
Select a BPEL sensor to monitor. This is the sensor that you created in
"Creating a Sensor" on page 17-15 for mapping sensor data to a data
object in Oracle BAM Server.
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. You must have already created a connection to
Oracle BAM Server in order to select data objects.
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 decision to periodically send the data is based on
upper and lower limit parameter settings on the Set Batch Parameters
window. The Oracle BAM component may decide to send data prior to
a batch timeout if the cache has a number of data objects between the
lower and upper limit values. Disable batching by unselecting this
check box.
To modify the batch parameters, click Set Batch Parameters. See Step 4
on page 17-17 for additional details.
17-16 Oracle BPEL Process Manager Developer’s Guide
Sensor Integration with Oracle Business Activity Monitoring
Field
Description
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
Keys/Selected Keys
If you selected the Delete, Update, or Upsert operation, you must also
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 Select 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).
WARNING: If you restart Oracle BPEL Server, any messages
currently being batched are lost. Ensure that all messages have
completed batching before restarting Oracle BPEL Server.
After you click the Create Mapping or Edit Mapping or OK
button on the Create Sensor Action window, you must explicitly save
the BPEL file.
Notes:
4.
If you want to specify custom batch parameter settings, click Set Batch
Parameters.
The Set Batch Parameters window appears.
5.
Deselect the Use Default Batch Parameters check box and provide customized
values in the fields below. If you provide customized values and then select this
check box again, the settings revert to the default values.
6.
Enter the following details:
Field
Description
Batch size lower
limit
Use the default value of 1000 or specify a lower batch limit. This
parameter controls the minimum number of rows in the cache. With
this parameter, the data remains in the Oracle BPEL Process Manager
run-time cache until the queue size reaches at least this limit or a
timeout occurs.
Sensors 17-17
Sensor Public Views
Field
Description
Batch size upper
limit
Use the default value of 5000 or specify an upper batch limit. This
parameter controls the maximum number of rows in the cache. With
this parameter, the Oracle BPEL Process Manager run time flushes the
data to Oracle BAM Server prior to the upper limit being reached.
Batch timeout
(milliseconds)
Specify the timeout in minutes. The default value is 50 milliseconds.
When the timeout occurs, the BPEL run time flushes any data in the
queue to Oracle BAM Server.
7.
Click OK to close the Set Batch Parameters window and the Create Sensor Action
window.
Sensor Public Views
The sensor framework of Oracle BPEL Process Manager provides the functionality to
persist sensor values created by processing BPEL instances in a relational schema
stored in the dehydration store of Oracle BPEL Process Manager. The data is used to
display the sensor values of a process instance in Oracle BPEL Control.
A set of public views is exposed to allow SQL access to sensor values from literally any
application interested in the data.
BPM Schema
The database publisher persists the sensor data in a predefined relational schema in
the database. The following public views can be used from a client (Oracle Warehouse,
OracleAS Portal, and so on) to query the sensor values using SQL.
Note: In Table 17–1 through Table 17–5, the Indexed or Unique?
column provides unique index names and the order of the attributes.
For example, U1,2 means that the attribute is the second one in a
unique index named U1. PK means primary key.
BPEL_PROCESS_INSTANCES
This view provides an overview of all the process instances of Oracle BPEL Process
Manager.
Table 17–1
BPEL_PROCESS_INSTANCES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
INSTANCE_KEY
NUMBER
--
PK
N
Unique instance ID
BPEL_PROCESS_ NVARCHAR2
NAME
100
--
N
Name of the BPEL process
BPEL_PROCESS_ VARCHAR2
REVISION
50
--
N
Revision of the BPEL process
DOMAIN_ID
VARCHAR2
50
--
N
Oracle BPEL Process Manager domain
name
TITLE
VARCHAR2
50
--
Y
User-defined title of the BPEL process
STATE
NUMBER
--
--
Y
State of the BPEL process instance
STATE_TEXT
VARCHAR2
--
--
Y
Text presentation of the state attribute
17-18 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
Table 17–1 (Cont.) BPEL_PROCESS_INSTANCES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
PRIORITY
NUMBER
--
--
Y
User-defined priority of the BPEL
process instance
STATUS
VARCHAR2
100
--
Y
User-defined status of the BPEL
process
STAGE
VARCHAR2
100
--
Y
User-defined stage property of a BPEL
process
CONVERSATION_ VARCHAR2
ID
100
--
Y
User-defined conversation ID of a
BPEL process
CREATION_DATE TIMESTAMP
--
--
N
Creation time stamp of the process
instance
MODIFY_DATE
TIMESTAMP
--
--
Y
Time stamp when the process instance
was modified
TS_DATE
DATE
--
--
Y
Date portion of modify_date
TS_HOUR
NUMBER
--
--
Y
Hour portion of modify_date
EVAL_TIME
NUMBER
--
--
Y
Evaluation time of the process instance
in milliseconds
SLA_
COMPLETION_
TIME
NUMBER
--
--
Y
SLA completion time in milliseconds.
This is populated with the value of an
optional property you can set in
bpel.xml. For example,
<configurations>
...
<property
name="SLACompletionTime">POYT1.5S
</property>
SLA_SATISFIED VARCHAR2
1
--
Y
Y means SLA satisfied: SLA_
COMPLETION_TIME < EVAL_TIME.
N means SLA not satisfied; SLA_
COMPLETION_TIME > EVAL_TIME.
BPEL_ACTIVITY_SENSOR_VALUES
This view contains all the activity sensor values of the monitored BPEL processes.
Table 17–2
BPEL_ACTIVITY_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
N
ID of process instance
BPEL_PROCESS_ NVARCHAR2
NAME
100
--
N
Name of the BPEL process
BPEL_PROCESS_ VARCHAR2
REVISION
50
--
N
Revision of the BPEL process
DOMAIN_ID
VARCHAR2
50
--
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
U1,2
N
The name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
The target of the fired sensor
Sensors 17-19
Sensor Public Views
Table 17–2 (Cont.) BPEL_ACTIVITY_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ACTION_NAME
NVARCHAR2
100
U1,3
N
The name of the sensor action
ACTION_FILTER NVARCHAR2
256
--
Y
The filter of the action
CREATION_DATE TIMESTAMP
--
--
N
The creation date of the activity sensor
value
MODIFY_DATE
TIMESTAMP
--
--
Y
The time stamp of last modification
TS_DATE
DATE
--
--
Y
Date portion of modify_date
TS_HOUR
NUMBER
--
--
Y
Hour portion of modify_date
CRITERIA_
SATISFIED
VARCHAR2
1
--
Y
NULL, Y, or N
ACTIVITY_NAME NVARCHAR2
100
--
N
The name of the BPEL activity
ACTIVITY_TYPE VARCHAR2
30
--
N
The type of the BPEL activity
ACTIVITY_
STATE
VARCHAR2
30
--
Y
The state of the BPEL activity
EVAL_POINT
VARCHAR2
20
--
N
The evaluation point of the activity
sensor
ERROR_MESSAGE NVARCHAR2
2000
--
Y
An error message
RETRY_COUNT
NUMBER
--
--
Y
The number of retries of the activity
EVAL_TIME
NUMBER
--
--
Y
Evaluation time of the activity in
milliseconds
BPEL_FAULT_SENSOR_VALUES
This view contains all the fault sensor values.
Table 17–3
BPEL_FAULT_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
N
BPEL process ID
BPEL_PROCESS_ NVARCHAR2
NAME
100
--
N
Name of the BPEL process
BPEL_PROCESS_ VARCHAR2
REVISION
50
--
N
Revision of the BPEL process
DOMAIN_ID
VARCHAR2
50
--
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
U1,2
N
The name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
The target of the fired sensor
ACTION_NAME
NVARCHAR2
100
U1,3
N
The name of the sensor action
ACTION_FILTER NVARCHAR2
256
--
Y
The filter of the action
CREATION_DATE TIMESTAMP
--
--
N
The creation date of the activity sensor
value
MODIFY_DATE
TIMESTAMP
--
--
Y
The time stamp of last modification
TS_DATE
DATE
--
--
Y
Date portion of modify_date
17-20 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
Table 17–3 (Cont.) BPEL_FAULT_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
TS_HOUR
NUMBER
--
--
Y
Hour portion of modify_date
CRITERIA_
SATISFIED
VARCHAR2
1
--
Y
NULL if no action filter specified; Y if
action filter is specified and evaluates
to true; N otherwise
ACTIVITY_NAME NVARCHAR2
100
--
N
The name of the BPEL activity
ACTIVITY_TYPE VARCHAR2
30
--
N
The type of the BPEL activity
MESSAGE
--
--
Y
The fault message
CLOB
BPEL_VARIABLE_SENSOR_VALUES
This view contains all the variable sensor values.
Table 17–4
BPEL_VARIABLE_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
INSTANCE_KEY
NUMBER
--
U1,1
N
BPEL process ID
BPEL_PROCESS_ NVARCHAR2
NAME
100
--
N
Name of the BPEL process
BPEL_PROCESS_ VARCHAR2
REVISION
50
--
N
Revision of the BPEL process
DOMAIN_ID
VARCHAR2
50
--
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
U1,2
N
Name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
Target of the sensor
ACTION_NAME
NVARCHAR2
100
U1,3
N
Name of the action
ACTION_FILTER NVARCHAR2
256
--
Y
Filter of the action
ACTIVITY_
SENSOR
--
--
Y
ID of corresponding activity sensor
value
CREATION_DATE TIMESTAMP
--
--
N
Creation date
TS_DATE
DATE
--
--
N
Date portion of creation_date
TS_HOUR
NUMBER
--
--
N
Hour portion of creation_date
VARIABLE_NAME NVARCHAR2
256
--
N
The name of the BPEL variable
EVAL_POINT
VARCHAR2
30
--
Y
Evaluation point of the corresponding
activity sensor
CRITERIA_
SATISFIED
VARCHAR2
1
--
Y
NULL, Y, or N
TARGET
NVARCHAR2
256
--
--
--
UPDATER_NAME
NVARCHAR2
100
--
N
The name of the activity or event that
updated the variable
UPDATER_TYPE
NVARCHAR2
100
--
N
The type of the BPEL activity or event
SCHEMA_
NAMESPACE
NVARCHAR2
256
--
Y
Namespace of variable sensor value
NUMBER
Sensors 17-21
Sensor Public Views
Table 17–4 (Cont.) BPEL_VARIABLE_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
SCHEMA_
DATATYPE
NVARCHAR2
256
--
Y
Datatype of the variable sensor value
VALUE_TYPE
SMALLINT
--
--
N
The value type of the variable
(corresponds to java.sql.Types
values)
VARCHAR2_
VALUE
NVARCHAR2
2000
--
Y
The value of string-like variables
BPMERRORS
This view provides an overview of all errors from BPM services.
Table 17–5
BPMERRORS View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
BPEL_PROCESS_ NVARCHAR2
NAME
100
U1,1
N
Name of the BPEL process
BPEL_PROCESS_ VARCHAR2
REVISION
50
U1,2
N
Revision of the BPEL process
DOMAIN_ID
50
U1,3
N
Oracle BPEL Process Manager domain
name
CREATION_DATE TIMESTAMP
--
--
N
Creation date of the activity sensor
value
TS_DATE
DATE
--
--
N
Date portion of creation_date
TS_HOUR
NUMBER
--
--
N
Hour portion of creation_date
ERROR_CODE
NUMBER
--
--
N
Error code
EXCEPTION_
TYPE
NUMBER
--
--
N
Type of the error
EXCEPTION_
SEVERITY
NUMBER
--
--
N
Severity of the error
EXCEPTION_
NAME
NVARCHAR2
200
--
N
Name of the error
EXCEPTION_
DESCRIPTION
NVARCHAR2
2000
--
Y
A short description of the error
EXCEPTION_FIX NVARCHAR2
2000
--
Y
A description on how to fix the error
EXCEPTION_
CONTEXT
VARCHAR2
4000
--
Y
The context of the error
COMPONENT
NUMBER
--
--
N
The BPM component that caused the
error
THREAD_ID
VARCHAR2
200
--
N
The Java thread name in which the
error occurred.
STACKTRACE
CLOB
--
--
N
The Java stack trace
VARCHAR2
17-22 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
Sensor Actions XSD File
The section provides a sample sensor action schema that you can import into Oracle
JDeveloper. This schema is also relevant to custom data publishers.
<?xml version="1.0" encoding="utf-8"?>
<!-This schema contains the sensor definition. Sensors monitor data
and execute callbacks appropriately.
-->
<xsd:schema blockDefault="#all" elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/bpel/sensor"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://xmlns.oracle.com/bpel/sensor">
<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.
Sensors 17-23
Sensor Actions XSD File
+ filter (to potentially suppress data publishing even if a sensor marks
it as interesting). - Optional. If not defined, no filter is
used.
+ publishName A name of a publisher
+ publishType What to do with the sensor data?
+ publishTarget Name of a JMS Queue/Topic or custom publisher.
+ potentially many sensors.
-->
<xsd:complexType name="tSensorAction">
<xsd:sequence>
<xsd:element name="sensorName" type="xsd:string" minOccurs="1"
maxOccurs="unbounded"/>
<xsd:element name="property" minOccurs="0" maxOccurs="unbounded"
type="tns:tSensorActionProperty"/>
</xsd:sequence>
<xsd:attributeGroup ref="tns:tSensorActionAttributes"/>
</xsd:complexType>
<!-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>
17-24 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
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>
Sensors 17-25
Sensor Actions XSD File
<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"/>
</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"/>
17-26 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
<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>
Sensors 17-27
Sensor Actions XSD File
<xsd:element name="processName" type="xsd:string"/>
<xsd:element name="processVersion" type="xsd:string"/>
<xsd:element name="processID" type="xsd:long"/>
<xsd:element name="midTierInstance" type="xsd:string"/>
</xsd:sequence>
<xsd:attribute name="actionName" use="required" type="xsd:string"/>
</xsd:complexType>
<!-Sensor Action data is presented in the form of a header and potentially many
data elements depending on how many sensors associated to the sensor action
marked the data as interesting.
-->
<xsd:complexType name="tSensorActionData">
<xsd:sequence>
<xsd:element name="header" type="tns:tHeaderInfo"/>
<xsd:element name="payload" type="tns:tSensorData" minOccurs="1"
maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<!-<xsd:simpleType name="tActivityEvalPoint">
<xsd:restriction>
<xsd:enumeration value="start"/>
<xsd:enumeration value="complete"/>
<xsd:enumeration value="fault"/>
<xsd:enumeration value="compensate"/>
<xsd:enumeration value="retry"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="tNotificationAction">
<xsd:restriction>
<xsd:enumeration value="creation"/>
<xsd:enumeration value="statusUpdate"/>
</xsd:restriction>
</xsd:simpleType>
-->
<!-The process sensor value header comprises of a timestamp
where the sensor was triggered and the sensor metadata
-->
<xsd:complexType name="tProcessSensorValueHeader">
<xsd:sequence>
<xsd:element name="timestamp" type="xsd:dateTime"/>
<xsd:element ref="tns:sensor"/>
</xsd:sequence>
</xsd:complexType>
<!-Extend tActivityData to include more elements
-->
<xsd:complexType name="tProcessActivityData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
17-28 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
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
Sensors 17-29
Sensor Actions XSD File
-->
<xsd:complexType name="tProcessNotificationData">
<xsd:complexContent>
<xsd:extension base="tns:tNotificationData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Copy of tSensorData type with some modified types.
-->
<xsd:complexType name="tProcessSensorData">
<xsd:sequence>
<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"
17-30 Oracle BPEL Process Manager Developer’s Guide
Summary
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"/>
<!-- A sensor is used to monitor a particular aspect of a bpel process -->
<xsd:element name="sensor" type="tns:tSensor"/>
<!-- 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 -->
<xsd:element name="actions" type="tns:tSensorActionList"/>
<!-- 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>
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.
Sensors 17-31
Summary
17-32 Oracle BPEL Process Manager Developer’s Guide
18
BPEL Process Integration with Business
Rules
This chapter describes how to build adaptive business processes by using a decision
service to integrate BPEL processes with a business rule engine.
This chapter contains the following topics:
■
Business Rules and Decision Service Concepts
■
Decision Service Architecture
■
Use Cases for Integration of Business Processes and Business Rules
■
Integration of BPEL Processes with Business Rules
■
Methodology for Rule Set Modeling and Integration with a BPEL Process
■
Decision Service Deployment and Run Time
■
Advanced Decision Service Features
■
Example of BPEL Process Integration with Business Rules
See Also: The AutoLoanDemo tutorial, which describes how to
design a BPEL process that integrates with business rules and uses
human workflow:
SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
Business Rules and Decision Service Concepts
This section provides an overview of Oracle BPEL Process Manager support for
business rules and business rule engines.
This section contains the following topics:
■
Business Rules and Business Rule Engines
■
Decision Service
■
Oracle Business Rules with Oracle BPEL Process Manager
Business Rules and Business Rule Engines
Business rules are statements that describe the policies of a company. Examples of
business rules can include the following:
■
All customers that buy more than $100 worth of products at one time or who are
over the age of 65 receive a 10% discount.
BPEL Process Integration with Business Rules 18-1
Business Rules and Decision Service Concepts
■
■
■
A sales department is notified when inventory quantity is lower than ten and there
are more than five pending orders on a given day.
If the annual income of a customer is less than $10,000, a loan request is denied.
If a customer submitted a late payment for a previous purchase, an additional
charge of 2% is added to their next purchase.
A business rule engine is a system that manages and executes business rules. A
business rule system typically consists of a rule repository, rule author, and rule
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 rule 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.
Decision Service
Oracle BPEL Process Manager provides support for a decision service. A decision
service is a mechanism for publishing rules and rule sets as a reusable service that can
be invoked from multiple business processes. The decision service is a standalone
deployment unit that consists of the following components:
■
■
■
A Web service that wraps the rule session to the underlying rule engine. This
service lets business processes assert and retract facts as part of the process. In
some cases, all facts can be asserted from the business process as one unit. In other
cases, the business process can incrementally assert facts and eventually consult
the rule engine for inferences. Therefore, the service has to support both stateless
and stateful interactions.
Rules that are evaluated by the decision service using the rule engine. These are
defined using the rule author and loaded into the rule repository.
Metadata that describes facts required for specific rules to be evaluated. Each rule
exposed as a service uses different types of facts. These facts must be exposed
through XSD definitions. Appropriate WSDL operations must be exposed for rule
evaluation.
For example, a credit rating rule set may expect a customer’s SSN, previous loan
history, and so on as facts, but a pension payment rule may expect an employee’s
years of service, salary, age, and so on as facts.
See Also:
"Decision Service Architecture" on page 18-3
Oracle Business Rules with Oracle BPEL Process Manager
Oracle BPEL Process Manager provides support for Oracle Business Rules. Oracle
Business Rules is a component included with Oracle Application Server. Business
analysts use Oracle Business Rules to create and change business rules that are
separate from the application code. This enables analysts to change business rules
without stopping business processes or having to involve programmers.
In Oracle Business Rules, facts are data objects asserted in the Oracle Business Rules
Rules Engine. For example:
■
■
For a car rental company to create a rule to match a driver's age, the driver's age
represents the fact used in the rule.
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.
18-2 Oracle BPEL Process Manager Developer’s Guide
Decision Service Architecture
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 Oracle Business Rules
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 Rule Author, 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:
■
■
Oracle Business Rules Rule Author — A Web browser-based tool that provides a
point-and-click interface to create and edit rules.
Oracle Business Rules Rules Engine — A Java library that applies rules to facts and
defines and processes rules. The Oracle Business Rules Rules Engine defines a
declarative rule language, provides a language processing engine, and provides
debugging tools.
Oracle BPEL Process Manager provides support for the following Oracle Business
Rules Rules Engine repositories that store the business rules:
–
Oracle Rules Engine File Repository — Stores rules in a file repository.
–
Oracle Rules Engine WebDav Repository — Stores rules in a Web Distributed
Authoring and Versioning (WebDAV) repository.
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 — A Java library that provides business rule
management features to use for writing customized rules programs.
Oracle Business Rules RL Language —A language that defines the syntax for
Oracle Business Rules Rules Engine programs. Oracle Business Rules RL
Language includes an intuitive Java-like syntax for defining rules that supports
Java semantics.
See Also:
The following documentation:
■
Oracle Business Rules User’s Guide
■
Oracle Business Rules Java API Reference
■
Oracle Business Rules Language Reference Guide
Decision Service Architecture
This section describes the components that comprise the decision service.
This section contains the following topics:
■
Decision Service Components
■
Interaction with Other Components
BPEL Process Integration with Business Rules 18-3
Decision Service Architecture
■
Contents of Decision Service Configuration File
Decision Service Components
The decision service consists of the following components:
■
Rule Provider Interface (RPI) — An interface used by decision service design time
clients such as Oracle JDeveloper. The RPI hides the details of a concrete rule
engine implementation. This enables the RPI to interface with any rule engine
from any provider. The main purpose of the RPI is to expose a uniform view of
rule engine metadata such as fact types, rule sets, dictionaries, and so on.
A design time component (such as Oracle JDeveloper) can use the RPI to browse
the metadata of a backend rule engine. According to what you model, metadata
information for a decision service partner link can be materialized in the decision
service configuration file.
■
■
Decision Service Builder — Reads the metadata information from a decision
service configuration file and creates a self-contained J2EE enterprise archive that
can be deployed to an application server.
Decision Service Runtime — A JAX-RPC Web service that is the Web service
enabler for business rule engines such as Oracle Business Rules. The run time itself
consists of the following components:
–
Decision Service Cache — Maintains metadata information about the rule data
model used by the service. This includes metadata about the fact types, rule
set, and decision service configuration. In addition, all stateful rule sessions
are stored in that cache. Oracle Java Object Cache (JOC) is used. Therefore, the
cache can be configured to run in clustered environments.
–
Fact Converter — Converts data coming from and going to Oracle BPEL
Process Manager to a format understood by a rule engine. For the Oracle
Business Rules Rules Engine, the fact converters use the JAXB 1.0 tech stack to
convert BPEL variable data (XML) to and from Java objects.
–
Execution Unit — Executes the various steps defined by the interaction
pattern at the backend rule engine. The execution unit uses the RPI for
executions.
See Also: Oracle Containers for J2EE Services Guide for cache
configuration options to use in clustered environments
Interaction with Other Components
Figure 18–1 shows how the decision service interacts with other components.
18-4 Oracle BPEL Process Manager Developer’s Guide
Decision Service Architecture
Figure 18–1 Decision Service Component Interaction
Design
Time
Deployment
Metadata
Model Rules
Decision Service
Partner Link
Decide
Activity
Rule
Repository
decisionservices.decs
BPEL
Process
Decision Service
Enterprise Archive
Process
Instance
JAX-RPC
Web Service
4
Runtime
1.
The rule author is used for rule modeling
The rule model is saved to a rule repository. The rule repository can be a file or a
directory at a WebDav backend.
2.
The RPI of the decision service is used by the Decision Service wizard to create a
connection to the rule repository and browse the repository metadata.
3.
The Decision Service wizard creates the decision service metadata configuration
file. The metadata consists of information about the backend rule engine being
used (rule provider) and the interaction patterns (together with fact type
information) modeled for the partner link.
4.
The decision service builder creates the decision service enterprise archive for
deployment into an application server. As part of this, a WSDL is created with
message types and operations adjusted to what you modeled in Step 3.
5.
The decide activity uses decision service metadata information to present you with
a list of available operations of the service and detailed information on the number
and types of facts used for an interaction with the rule engine
6.
The decide activity completes generation of a new BPEL scope in the BPEL process
model. Appropriate assign activities are created to convert the data from BPEL
variables to data that the decision service (and more importantly the backend rule
engine) expects.
7.
The BPEL process is deployed to Oracle BPEL Process Manager during
deployment time.
8.
The decision service enterprise archive is deployed to the application server.
9.
The BPEL process instance invokes the JAX-RPC decision service at run time,
which then interacts with the backend rule engine, executes rule sets, invokes
functions, and so on. Results are eventually returned to the BPEL process.
Contents of Decision Service Configuration File
The decision service configuration file (decisionservices.xml) defines the
contract between the various components involved in the interaction of the decision
service with the design time and a backend rule engine.
The decision service configuration file consists of two parts:
BPEL Process Integration with Business Rules 18-5
Decision Service Architecture
■
■
The first part specifies metadata about the rule engine connections.
The second part provides the metadata for specific interaction patterns with a
backend rule engine.
For example:
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
<ruleEngineProvider provider="Oracle" name="CreditRatingRuleRepository">
<repository type="File">
<file>
/D:/bpeldev/10.1.3/demo/LoanDemoPlusRules/repository/CreditRatingRepository
</file>
</repository>
</ruleEngineProvider>
<ruleEngineProvider provider="Oracle" name="LoanAdvisorRepository">
<repository type="File">
<file>
/D:/bpeldev/10.1.3/demo/LoanDemoPlusRules/repository/CarLoanBrokerRepository
</file>
</repository>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
targetNamespace="http://cr.org/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
<decisionService name="LoanAdvisorAgent"
targetNamespace="http://laa.org/LoanAdvisorAgent"
ruleEngineProviderReference="LoanAdvisorRepository">
<catalog>LoanOfferings</catalog>
<catalogVersion>REVIEWED_060518</catalogVersion>
<pattern name="CallFunctionStateless">
<arguments>
<call>DM.computeAdvisePrivateFinancing</call>
</arguments>
</pattern>
</decisionService>
</decisionServices>
The configuration file includes the following elements:
■
■
ruleEngineProvider — Specifies metadata about a backend rule engine
connection. Apart from the rule engine provider, information on the rule
repository is specified. You distinguish between these types of repositories:
–
File — The rule repository is stored in a file or directory.
–
WebDav — The rule repository is stored in a WebDav location.
decisionService — Consists of a name, an optional target namespace, and a
mandatory reference to the rule engine to use for the interaction. A complete
interaction with the rule engine is specified, which includes the catalog and
catalog version to use, and the rule set to execute. Various interaction patterns are
18-6 Oracle BPEL Process Manager Developer’s Guide
Integration of BPEL Processes with Business Rules
supported. Apart from the name of the pattern, the pattern signature is specified
in terms of input and output facts or function names.
Use Cases for Integration of Business Processes and Business Rules
Oracle BPEL Process Manager and business rules are complementary technologies.
Oracle BPEL Process Manager focuses on orchestration of systems, services, and
people. Business rules focus on decision making and policies.
Some examples of where decision service can be used include:
■
■
■
■
Dynamic processing — Rules can perform intelligent routing within the business
process based on service level agreements or other guidelines. For example, if the
customer requires response within one day, send the loan application to the
StarLoan loan agency only. If the customer can wait longer, then route the request
to three different loan agencies.
Externalize decision points in the process — There are typically many conditions
that must be evaluated as part of a business process. However, the parameters to
these can be changed independent of the process. For example, you provide loans
only to customers with a credit score of at least 650. This value may be changed
dynamically based on new guidelines set by business analysts.
Data validation and constraint checks — Rules can validate input documents or
apply additional constraints on requests. For example, a new customer request
must always be accompanied with an employment verification letter and bank
account details.
Human workflow — Rules are frequently used in the context of human tasks in
the business process:
–
Policy-based task assignments dispatch tasks to specific roles or users. For
example, a process that handles incoming requests from a portal can route
loan requests and insurance quotes to a different set of roles.
–
Load balancing of tasks among users – When a task is assigned to a set of
users or a role, each user in that role acquires a set of tasks and acts on them in
a specified time. For new incoming tasks, policies may be applied to set
priorities on the task and put them in specific user queues. For example, a
specific loan agent is assigned a maximum of 10 loans at any time.
Integration of BPEL Processes with Business Rules
Oracle BPEL Process Manager provides the following design-time components that
enable you to integrate BPEL processes with business rules.
■
Create Rule Engine Connection Wizard
■
Decision Service Wizard
■
Decide Activity
See Also: "Example of BPEL Process Integration with Business
Rules" on page 18-51
Create Rule Engine Connection Wizard
The Create Rule Engine Connection wizard enables you to create a connection to a rule
engine. This connection enables you to browse and select rule sets and functions
available in rule dictionaries of a rule repository in the business rule engine. You only
BPEL Process Integration with Business Rules 18-7
Integration of BPEL Processes with Business Rules
need to create one connection to the rule engine. Once created, this connection is
shared between multiple BPEL projects.
1.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
2.
Right-click Rule Engines and select New Rule Engine Connection.
3.
Click Next on the Welcome window.
4.
Enter a name. When creation of the rule engine connection is complete, this name
displays in the Connection Navigator under Rule Engines.
5.
Select the type of repository in which the rule sets and functions are stored in the
repository of the business rule engine. For this release, the Oracle Business Rules
Rules Engine is supported.
6.
Click Next.
7.
Click the folder icon to select a file repository directory. If you selected Oracle
Rules Engine WebDav Repository, you are instead prompted to select a WebDav
connection to the repository.
18-8 Oracle BPEL Process Manager Developer’s Guide
Integration of BPEL Processes with Business Rules
You can create a WebDav connection by right-clicking
WebDAV Server and selecting New WebDAV Connection in the
Connection Navigator.
Note:
8.
Click Next.
The Test Connection window appears.
9.
Click Test.
If the connection to the business rule repository is successful, the following
message appears:
Success
If the connection is unsuccessful, click Details to view the reason for failure. Take
appropriate corrective actions.
10. Click Finish.
The connection name displays in the Connection Navigator under Rule Engines.
If you need to edit the connection, double-click the connection name to display
configuration details.
Decision Service Wizard
The Decision Service wizard enables you to integrate your BPEL process with a
business rule (for example, a rule set or function) that you created in the Oracle
Business Rules Rules Engine. This enables you to make business decisions based on
these rules.
Figure 18–3 provides an overview of this integration process.
Figure 18–2 Decision Service
Rule Author
Rules
Repository
Rules
Engine
Decision
Service
This wizard performs the following tasks:
■
■
Guides you through the selection of a rule set or function from a repository and
the invocation pattern (operation) to perform
Converts your selection into a Web service to use in the BPEL process
A new decision service partner link for this Web service is automatically created that
interfaces with the Oracle Business Rules Rules Engine. A WSDL file based on the rule
set is generated.
The Decision Service wizard provides the following benefits:
BPEL Process Integration with Business Rules 18-9
Integration of BPEL Processes with Business Rules
■
■
■
Dynamic processing (provides for intelligent routing, validation of policies within
a process, and constraint checks)
Integration with adhoc workflows (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)
The following sections describe Decision Service wizard functionality in further detail:
■
Selecting an Invocation Pattern
■
Selecting a Business Rule
■
Specifying Input and Output Facts
■
Importing Schema Files
Selecting an Invocation Pattern
The Decision Service wizard enables you to select an invocation pattern that describes
how to interact with the business rule engine.
1.
Drag and drop a Decision Service from the Services list of the Component Palette
onto either side of the designer window beneath the header Services.
2.
Enter a name in the Service Name field. When complete, this name is used as the
partner link name. A WSDL file of the same name is also created.
The Namespace field is automatically completed with your entry from the Service
Name field. You must have a unique namespace for each WSDL in your project.
This is because some BPEL variables are generated from elements in the WSDL
files.
3.
Select an invocation pattern for invoking the rule set or function. The wizard
creates rule sessions based on the invocation pattern you select. You do not have
the option of selecting between stateful or stateless rule sessions.
The following invocation patterns are available for selection:
■
Execute Ruleset
18-10 Oracle BPEL Process Manager Developer’s Guide
Integration of BPEL Processes with Business Rules
■
4.
Execute function
Click the flashlight next to the Ruleset or Function field. The name of this field is
based on your selection in the Invocation Pattern field. This opens the Explorer
window.
Selecting a Business Rule
1.
Click Show All Versions to display all the catalog versions of rule dictionaries in
the rule repository of the business rule engine.
2.
Expand and select the dictionary (RatingFY06), dictionary version (Approved_
0600205), and rule set (PrivateCustomerRatingRules).
Notes:
■
■
3.
If you have not created a connection to the rule engine, you cannot
access the rule sets and functions in the rule repository. Click the
first icon in the upper right to start the Create Rule Engine
Connection wizard.
An alternative to creating a connection to a file-based rule
repository is to directly import a file into a project. Note that each
BPEL project must physically copy the repository file to the
project at the time of Web service creation. After the file is copied,
any changes to the original file are not reflected in the Web
service. Click the second button in the upper right to browse for
the file to import. The file must be a valid Oracle rule repository
file. Otherwise, an error appears.
Click OK.
You are returned to the Select a Ruleset or a Function window.
BPEL Process Integration with Business Rules 18-11
Integration of BPEL Processes with Business Rules
Specifying Input and Output Facts
Based on the type of invocation pattern you selected, the Select a Ruleset or a Function
window displays a table with different details at the bottom of the window.
■
Rule Sets
■
Functions
Rule Sets
The table displays the facts in the data model of the catalog from which you selected
the rule set. You select the facts to assert (that is, set the value from the BPEL variable
to the fact) and retrieve the results to return. Note that the columns that appear are
based on whether the selected pattern asserts facts, retrieves facts, or does both.
1.
Specify the input (assert) and (optionally) the output (watch) facts. The assert facts
enable you to assert a fact to the rule set or function (send factual data to the
business rule engine). The watch facts enable you to return results from the rule
set or function. Watch facts only appear if you selected an invocation pattern that
retrieves results.
The Check here to assert all descendants from the top level element check box
enables you to assert all the descendants of the selected rule set or function. For
example, assume that a purchase order rule set contains three fact types. If this
check box is selected, the purchase order and all three fact types are asserted. If
this check box is not selected, only the purchase order is asserted.
2.
Click Next.
Functions
The table displays the input parameters and parameter types to return.
18-12 Oracle BPEL Process Manager Developer’s Guide
Integration of BPEL Processes with Business Rules
1.
Click Next.
Importing Schema Files
1.
Review the on-screen messages to ensure that all necessary XSD schema files for
this project are imported from the repository by the wizard.
The wizard attempts to identify all the schema files in the repository that must be
imported into this project. Based on this attempt, this window can display the
following status messages:
■
■
■
If the Decision Service Wizard finds the schema files to import, the directory
paths to the files display at the top of this window. No action is required on
your part.
If the Decision Service Wizard cannot find the schema files to import, the
directory paths to the files display at the top of this window. You must
manually copy these files to the specified directory.
If this XSD schema file includes or imports other schema files, ensure that
those files are copied into the bpel\rules\xsd subdirectory of your BPEL
BPEL Process Integration with Business Rules 18-13
Integration of BPEL Processes with Business Rules
project indicated on-screen. Ensure that you use only relative directory paths
for these schema files.
2.
Click Next.
The decision service partner link is created. A directory named
decisionservices is also created in the BPEL project. A directory with the
same name as the service name is created inside the decisionservices
directory.
See Also: "Decision Service Partner Link Directory Structure" on
page 18-39 for specific details about directories and files created with
the decision service partner link
Decide Activity
The decide activity enables you to create a BPEL process activity that invokes the
decision service partner link you created with the Decision Service wizard. This
activity also enables you to create copy operation assignments between the fact data in
your rule set or function and BPEL variables.
When complete, a decide activity consisting of assign and invoke activities to the
decision service partner link is created.
Figure 18–3 provides an overview of this integration process.
Figure 18–3 Decide Activity
Rule Author
BPEL
Process
Rules
Repository
!
Rules
Engine
Decision
Service
Mapping Input and Output Facts to BPEL Variables
1.
Drag and drop a Decide activity from the Process Activities list of the Component
Palette into your BPEL process.
2.
Enter a name.
18-14 Oracle BPEL Process Manager Developer’s Guide
Integration of BPEL Processes with Business Rules
3.
Select the decision service partner link you created. If you have not created a
decision service, click the first icon to the right of the Decision Service field.
4.
Select the operation of the invocation pattern to perform. The operations available
for selection are based on the invocation pattern you selected in Step 3 on
page 18-10.
■
■
5.
If you selected Execute Ruleset
–
Assert facts only — Select the rule engine facts you want to assert (send
factual data to the rule engine) in the future. You assign the required data
for the facts with a BPEL assign activity. The underlying rule session must
be stateful. Otherwise, the asserted facts are not visible to subsequent rule
engine invocations.
–
Retrieve results — Retrieve a result from the business rule engine. The
values of these results may have changed by past execution of a rule set
acting on these facts. The wizard assumes that it has a stateful rule session
in its cache from which a result can be retrieved. This is the case if the
invocation pattern Assert facts and execute rule set operation was
executed before in the BPEL process.
–
Assert facts and execute rule set — The same as Assert facts only, except
that the rule set is executed after the facts are asserted. The wizard creates
(or uses) a stateful rule session. Otherwise, the result of executing this
pattern is lost. No results are retrieved from the business rule engine.
–
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 rule 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.
–
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.
If you selected Execute function
–
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.
Click Assign Input Facts, then click Create to create mappings for the input facts.
This enables you to assign BPEL variables to the facts to be asserted or to the
function input parameters.
BPEL Process Integration with Business Rules 18-15
Integration of BPEL Processes with Business Rules
This enables you to create assignments that map BPEL input variables to
automatically created BPEL variables that correspond to the input (assert) fact
type shown in "Specifying Input and Output Facts" on page 18-12 (for this
example, Ratingrequest).
6.
If you selected an invocation pattern that retrieves results, click Assign Output
Facts, then click Create to create mappings for the output facts. This enables you to
assign values from a function return value or rule set result to a BPEL variable.
This enables you to create assignments that map automatically created BPEL
variables that correspond to the output (watch) fact type shown in "Specifying
Input and Output Facts" on page 18-12 (for this example, Rating) to BPEL input
variables.
7.
Click OK when complete.
A decide activity consisting of assign and invoke activities to the decision service
partner link is created.
18-16 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
Methodology for Rule Set Modeling and Integration with a BPEL Process
Rule sets are a group of business rules that are typically evaluated together and
generated as a single unit. This section describes two methodologies for modeling rule
sets in a rule author.
After you model a rule set, you can integrate it with a BPEL process in Oracle
JDeveloper. You must have an existing rule repository prior to creating a decision
service partner link in Oracle JDeveloper.
This section contains the following topics:
■
Recommended Methodology
■
Methodology One: Modeling Fact Types Based on an XML Schema
■
Methodology Two: Modeling Rules Based on Existing RL or JavaBeans Fact Types
■
Invoking the Sample Rule Set from a BPEL Process
■
Summary of Methodology
Recommended Methodology
Oracle recommends that you follow these steps when modeling rule sets in a rule
author.
■
Create a data model for rule authoring based on the XML schema.
■
Create a new rule repository and dictionary in the rule author.
■
Import the XML schema into the data model of the rule dictionary as XML facts.
■
Create a new rule set and model rules.
■
Use the Decision Service wizard to create a partner link.
Methodology One: Modeling Fact Types Based on an XML Schema
This section describes how to model a simple rule for a credit rating:
■
Task 1: Create a Data Model for Rule Authoring
■
Task 2: Create a New Rule Repository and Dictionary in the Rule Author
BPEL Process Integration with Business Rules 18-17
Methodology for Rule Set Modeling and Integration with a BPEL Process
■
Task 3: Import the XML Schema into the Data Model of the Rule Dictionary
■
Task 4: Create a New Rule Set and Model Rules
After completion, you use the Decision Service wizard to integrate your rule set with a
BPEL process.
See Also: "Invoking the Sample Rule Set from a BPEL Process" on
page 18-33
Task 1: Create a Data Model for Rule Authoring
The first step in rule modeling is to define a data model. Data models based on XML
schema are supported. This example begins with a simple data model for credit rating
and defines two elements:
■
ratingrequest
<xsd:element name="ratingrequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="name" type="xsd:string" maxOccurs="1"/>
<xsd:element name="age" type="xsd:int" maxOccurs="1"/>
<xsd:element name="amount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
■
rating
<xsd:element name="rating">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="rating" type="xsd:int" maxOccurs="1"/>
<xsd:element name="risk" type="xsd:string" maxOccurs="1"/>
<xsd:element name="maxAmount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
It is important to understand that rule modeling is performed
at the XML schema type level, whereas the data transfer from BPEL to
the decision service is at the element level.
Note:
An alternative model (with the same semantics) is to define the following XML
schema:
<xsd:element name="ratingrequest" type="tRatingRequest"/>
<xsd:element name="rating" type="tRating"/>
<xsd:complexType name="tRatingRequest">
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="name" type="xsd:string" maxOccurs="1"/>
<xsd:element name="age" type="xsd:int" maxOccurs="1"/>
18-18 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
<xsd:element name="amount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tRating">
<xsd:sequence>
<xsd:element name="date" type="xsd:date" maxOccurs="1"/>
<xsd:element name="SSN" type="xsd:string" maxOccurs="1"/>
<xsd:element name="rating" type="xsd:int" maxOccurs="1"/>
<xsd:element name="risk" type="xsd:string" maxOccurs="1"/>
<xsd:element name="maxAmount" type="xsd:double" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
1.
Open a text editor.
2.
Save either schema to a file named CreditRatingTypes.xsd. Ensure that you
add the appropriate opening and closing header and footer information to the
schema file.
Task 2: Create a New Rule Repository and Dictionary in the Rule Author
You now create a new rule repository and dictionary in the rule author.
1.
Copy the SOA_Oracle_Home\rules\fileRepositories\ruleRepository
file to a location within your file system. For example:
C:\CreditRatingRules\model\CreditRatingRepository
You are now ready to open a new repository in the rule author, log in to the rule
author, and connect to the new repository.
2.
Log in to the rule author and connect to the new repository.
http://hostname:8888/ruleauthor
3.
Enter oc4jadmin/password.
where password is the password you specified for the oc4jadmin user during
installation.
4.
Click Repository.
The Connect page appears.
5.
Select File from the Repository Type list.
6.
Click Browse to the right of the File Location field.
7.
Select the repository file location specified in Step 1.
8.
Click Create.
A message indicates that a repository connection has been created.
9.
Click the Create subtab.
The Create Dictionary page appears.
10. Enter SampleDictionary in the New Dictionary Name field and click Create.
BPEL Process Integration with Business Rules 18-19
Methodology for Rule Set Modeling and Integration with a BPEL Process
A message indicates that the dictionary has been imported.
You now import the XML schema data model into the rule dictionary.
Task 3: Import the XML Schema into the Data Model of the Rule Dictionary
For a given rule dictionary, you can define the underlying data model to use for rule
authoring.
1.
Click the Definitions tab.
2.
Click XMLFact in the Definitions tree on the left.
The XMLFact Summary page appears.
3.
Click Create.
The XML Schema Selector page appears.
4.
Enter the following details:
Field
Value
XML Schema
Enter the absolute path to the CreditRatingTypes.xsd file
you created in Step 2 of "Task 1: Create a Data Model for Rule
Authoring" on page 18-19. For this example, the second schema
file model described in that step was used.
JAXB Class Dictionary
Enter a directory in which to create the JAXB classes.
Target Package Name
Enter a Java package name to use for the XML fact types (for
example, creditrating).
5.
Click Add Schema.
6.
Expand the Generated JAXB Classes tree at the bottom.
18-20 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
7.
Specify the objects in the schema to import. For this example, Ratingrequest,
Rating, TRatingRequest, and TRating are selected.
8.
Click Import.
A confirmation message displays indicating that four classes or packages have
been imported.
You can now specify meaningful aliases for your data model. This action is
optional, but considered a good practice for rule modeling.
9.
Click XMLFact in the Definitions tree.
10. Select creditrating.TRatingRequest from the XML Fact Summary table.
11. Click Edit.
The Properties section appears.
12. Enter appropriate text in the Alias column for the SSN, age, amount, date, and
name properties.
13. Click OK.
BPEL Process Integration with Business Rules 18-21
Methodology for Rule Set Modeling and Integration with a BPEL Process
Notes: Oracle Business Rules use Oracle JAXB 1.0 for XML fact
types. As a result, certain limitations apply:
■
■
Use different names for elements and complex types. Although
the XML schema specification allows the same name for an
element and a type, the JAXB class generator does not support it.
Use different target package names for every XML schema
imported into the rule author. As part of JAXB class generation, a
factory class ObjectFactory is created. If you import a second
XML schema and specify the same target package name, the JAX
generator overwrites the factory class from the first import. This
results in unexpected behavior from the rule engine.
As a result of using JAXB for fact types, rule modeling needs to
happen on the XML schema type level (complexType level). This is
because for XML elements, JAXB generates marker interfaces only and
the rule author cannot introspect the attributes and methods of these
interfaces for rule modeling.
As part of the data model, RL functions can be specified. It is a convenient way to
simplify rule action handling by externalizing the logic of a rule action into a RL
function. In this case, the purpose of the rules is to accept a rating request for
which rules are applied. The result of rule execution is a new rating object
consisting of the data calculated by the rules. Therefore, it is convenient to create
an RL function that creates a new rating object and asserts it with the rule engine.
14. Click RLFunction in the Definitions tree.
The RLFunction Summary page appears.
15. Click Create.
The RLFunction page appears.
16. Enter the following details:
Field
Value
Name
DM.assertRating
Alias
assertRating
Return Type
void
The page looks as follows:
18-22 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
17. Enter the following function in the Function Body section:
// Create a new Rating object using JAXB ObjectFactory
creditrating.ObjectFactory of = new creditrating.ObjectFactory();
creditrating.Rating rating = of.createRating();
// Get a calendar instance for the current date
java.util.Calendar calendar = java.util.Calendar.getInstance();
// Set Rating object attributes
rating.setSSN(req.getSSN());
rating.setDate(calendar);
rating.setRating(cr);
rating.setRisk(crisk);
rating.setMaxAmount(cmax);
// Assert Rating object in working memory
assert (rating);
18. Click Apply.
The following confirmation message appears:
This entity has been updated successfully.
Task 4: Create a New Rule Set and Model Rules
After the data model is defined, you can create the rules for the credit rating.
1.
Click the Rulesets tab.
2.
Click Create in the RuleSet Summary page.
The Ruleset page appears.
3.
Enter SampleRuleset in the Name field.
4.
Enter an optional description in the Description field.
BPEL Process Integration with Business Rules 18-23
Methodology for Rule Set Modeling and Integration with a BPEL Process
5.
Click OK.
6.
Select SampleRuleset in the RuleSets tree on the left.
7.
Click Create in the Rules section.
8.
Enter the following details:
Field
Value
Name
YoungCustomers
Description
Rule for young customers
Priority
0
When complete, the Rule page appears as follows:
9.
Click New Pattern to define the If pattern of the rule (the rule matching part).
The Pattern Definition page appears asking for the pattern of the young customer
rule.
10. Enter an optional name for the expected fact to match in the Choose Pattern
section.
11. Select TRatingRequest from the drop-down list.
It now becomes clear what it means to model the rules on the XML schema type
level, and not on the element level.
12. Click Create in the Define Test for Pattern section.
13. Select the appropriate operands from the Field column.
18-24 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
14. Specify several matching statements for the rule. For this example, the young
customer rule is executed if the following statements are satisfied:
■
■
If the rating request comes from a customer at least 18 years of age and less
than 35 years of age.
If the requested loan amount is less than 20,000.
15. Click Apply.
16. Specify the Then section of the rule.
As part of the action, you want to retract (remove) the original rating request
object from the working memory of the rule engine and create and assert a new
rating object.
17. Click New Action in the Then section of the Rule page to retract the original
request object (the object that caused the rule to be invoked).
18. Select Retract from the Action Type list.
19. Select request from the Fact Instance list.
BPEL Process Integration with Business Rules 18-25
Methodology for Rule Set Modeling and Integration with a BPEL Process
20. Click OK.
21. Click New Action again and select Call from the Action Type list.
22. Select assertRating from the Function list. This is the function created in Step 16
on page 18-22.
23. Provide values for the function parameters. For this example, ratingrequest,
credit_rating, credit_risk, and credit_max_amount). The values for ratingrequest
and credit_max_amount cause the rule to be invoked and can be used in the rule
action part.
24. Click OK.
The rule appears as follows:
18-26 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
25. Double-check the rule and confirm by clicking OK.
It is a good practice to model a rule with no if statement pattern (simply
accepting the fact) and an action that generates a well-defined result for the case
where no other rule is invoked. For example:
■
■
■
Set the priority to -10 in the Priority field to ensure that this rule is not
invoked if other rules match the pattern of the fact instance.
Accept the fact (request is a TRatingRequest in the If section) without
specifying any additional test pattern.
Provide a dummy result that can be checked later from Oracle BPEL Process
Manager (Call assertRating(request, 0, "Unknown", 0.0) in the Then section).
26. Click Save Dictionary in the upper right corner.
27. Enter a name for the dictionary when prompted and click Save.
The rule set modeling process is now complete. The rules can now be used in a
BPEL process.
BPEL Process Integration with Business Rules 18-27
Methodology for Rule Set Modeling and Integration with a BPEL Process
See Also: "Invoking the Sample Rule Set from a BPEL Process" on
page 18-33 to integrate the rule set with a BPEL process
Methodology Two: Modeling Rules Based on Existing RL or JavaBeans Fact Types
In "Methodology One: Modeling Fact Types Based on an XML Schema", you modeled
fact types based on an XML schema for integration with Oracle BPEL Process
Manager. This methodology describes the case in which the rules are modeled already
based on RL or JavaBean fact types.
The following methodology is taken:
■
■
■
Model the contract between BPEL and the business rules using an XML schema.
Create an RL function in the rule author that accepts parameters of the modeled
XML schema. Then, perform the following procedures:
–
Convert the parameter values to RL or Java fact type objects.
–
Execute the rule set in question (rules are modeled on top of the RL or Java
data model).
–
Convert the resulting fact object (RL or Java) to an object of the RL function
return type.
Use the Call Function pattern (the invocation pattern you can select) from Oracle
JDeveloper.
This section describes how to model a rule set in which the rules are already modeled
based on RL or JavaBean fact types:
■
Task 1: Define a Contract between BPEL and Business Rules
■
Task 2: Create a New Data Model Using the RL Fact Types
■
Task 3: Create a New Rule Set and Rules
■
Task 4: Create the RL Function Contract
Task 1: Define a Contract between BPEL and Business Rules
You must define a contract between the process modeled in BPEL and the business
rules. Assume the contract is defined as follows:
■
Input — A rating request document of element ratingrequest
■
Output — A rating document of element rating
■
Rule set — Execute rules for the credit rating
The contract can be expressed in terms of an RL function calculateCreditRating
with the following signature:
creditrating.Rating calculateCreditRating(creditrating.Ratingrequest request)
Before creating the function in the rule author, you define a new data model based on
RL fact types and a new rule set based on the RL fact type data model.
Task 2: Create a New Data Model Using the RL Fact Types
You create a new data model for the credit rating using RL fact types.
1.
Load the sample dictionary from the "Methodology One: Modeling Fact Types
Based on an XML Schema" into the rule author.
18-28 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
2.
Click the Definitions tab.
3.
Select RLFact in the Definitions tree.
4.
Create a new RL fact type named MyRatingRequest.
5.
Create a new RL fact type named MyRating.
6.
Click OK.
For the function to work properly, you must create a global variable to use as a
placeholder to carry the result of rule execution.
7.
Select Variable in the Definitions tree.
8.
Select Create.
9.
Create a variable named theResult of type mr.
This is the alias of RL fact type MyRating.
BPEL Process Integration with Business Rules 18-29
Methodology for Rule Set Modeling and Integration with a BPEL Process
Task 3: Create a New Rule Set and Rules
1.
Click the Rulesets tab.
2.
Click Create in the RuleSet Summary page.
3.
Enter AlternateRuleset in the Name field.
4.
Enter an optional description in the Description field.
5.
Click OK.
6.
Select AlternateRuleset in the RuleSets tree on the left.
7.
Click Create in the Rules section.
8.
Click New Pattern to enter the If pattern of the rule (the rule matching part).
9.
Specify several matching statements for the rule. For this example:
■
■
If the rating request comes from a customer at least 18 years of age and less
than 35 years of age.
If the requested loan amount is less than 20,000.
18-30 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
As part of the action, you want to retract (remove) the original request object.
10. Click OK.
11. Click New Action in the Then section.
12. Select Retract from the Action Type list.
13. Select req from the Fact Instance list.
14. Click OK.
15. Set the global variable to an appropriate value. For an overview of how to set
global variables, see Step 7 through Step 9 on page 18-29.
Task 4: Create the RL Function Contract
You now create an RL function.
1.
Select Definitions.
2.
Select RLFunction in the Definitions tree.
The RLFunction Summary window appears.
3.
Click Create.
4.
Enter the following details:
BPEL Process Integration with Business Rules 18-31
Methodology for Rule Set Modeling and Integration with a BPEL Process
Field
Value
Name
calculatCreditRating
Alias
calculateCreditRating
Return Type
Rating
Expand
Do not select.
The page appears as follows:
5.
Add the following function to the Function Body section:
// Create JAXB object factory and result object
creditrating.ObjectFactory of = new creditrating.ObjectFactory();
creditrating.Rating result = of.createRating();
// Get current calendar
java.util.Calendar calendar = java.util.Calendar.getInstance();
// Create new RL object and convert from JAXB to RL
MyRatingRequest mrr = new MyRatingRequest();
mrr.ssn = request.getSSN();
mrr.name = request.getName();
mrr.age = request.getAge();
mrr.amount = request.getAmount();
mrr.date = request.getDate().getTimeInMillis();
// Assert the RL object and run Alternate Ruleset
assert(mrr);
run("AlternateRuleset");
// Result is in variable theResult, convert back to JAXB and return
result.setRating(theResult.rating);
result.setRisk(theResult.risk);
result.setMaxAmount(theResult.maxAmount);
result.setDate(calendar);
return result;
6.
Click OK.
This function can be used from Oracle BPEL Process Manager since it has an XML
contract, although the underlying rule data model is based on RL fact types.
See Also: "Invoking the Sample Rule Set from a BPEL Process" on
page 18-33 to integrate the rule set with a BPEL process
18-32 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
Invoking the Sample Rule Set from a BPEL Process
This section describes how to integrate the rule sets created with the Oracle Business
Rules Rule Author with a BPEL process.
This section contains the following topics:
■
Task 1: Create a Connection to the Rule Engine
■
Task 2: Create a BPEL Project
■
Task 3: Create a Decision Service Partner Link
■
Task 4: Create a Decide Activity
Task 1: Create a Connection to the Rule Engine
1.
Restart Oracle JDeveloper.
2.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
3.
Right-click Rule Engines and select New Rule Engine Connection.
4.
Click Next on the Welcome window.
5.
Enter SampleRuleRepository in the Connection Name field.
6.
Select Oracle Rules Engine File Repository as the business rule engine to which
to connect.
7.
Click Next.
The Connection window appears.
8.
Click the folder icon to select the directory in which the file repository is located.
9.
Select the CreditRatingRepository file repository from the
C:\CreditRatingRules\model\CreditRatingRepository directory. This is the
repository you created in Step 1 on page 18-19.
10. Click Open.
11. Click Next.
The Test Connection window appears.
12. Click Test.
If the connection to the business rule engine is successful, the following message
appears:
Success
13. Click Finish.
See Also:
"Create Rule Engine Connection Wizard" on page 18-7
Task 2: Create a BPEL Project
1.
Right-click your application in the Application Navigator section.
2.
Select New Project to define a new BPEL process project.
3.
Double-click BPEL Process Project in the Items window to display the BPEL
Project Creation Wizard window.
4.
Enter SampleProcess in the Name field.
5.
Select Synchronous BPEL Process from the Template list.
BPEL Process Integration with Business Rules 18-33
Methodology for Rule Set Modeling and Integration with a BPEL Process
6.
Click Next.
7.
Click the flashlight icon to the right of the Input Schema Element field.
8.
In the Select Schema window, select CreditRatingTypes.xsd from the directory in
which you saved it in Step 2 of "Task 1: Create a Data Model for Rule Authoring"
on page 18-19 and click Open.
The Type Chooser window appears.
9.
Expand and select Imported Schemas > CreditRatingTypes.xsd > ratingrequest.
10. Click OK.
11. Click the flashlight icon to the right of the Output Schema Element field.
The Type Chooser window appears.
12. Expand and select Imported Schemas > CreditRatingTypes.xsd > rating.
13. Click OK.
14. Click Finish.
This completes the BPEL project creation wizard. A new BPEL process template is
created for you with a receive activity accepting a ratingrequest element and a reply
activity sending out a rating element.
Task 3: Create a Decision Service Partner Link
1.
Ensure that Services is selected in the drop-down list of the Component Palette
section in the upper right section of Oracle JDeveloper.
2.
Drag and drop a Decision Service onto the right side of the designer window
anywhere beneath the header Services.
The Select a Ruleset or a Function window appears. This window enables you to
select an invocation pattern.
3.
Enter the following details:
Field
Value
Service Name
CreditRatingService
Note: When complete, this becomes the name of the partner link.
Namespace
http://xmlns.oracle.com/myLoanProcess/CreditRatingService
Note: This field is automatically completed with your entry in the
Service Name field.
Invocation Pattern
4.
Execute Ruleset
Click the flashlight icon next to the Ruleset field.
The Rule Explorer window appears.
This window enables you to browse and select the rule set in the dictionary of the
repository you modified in Step 3 of "Task 4: Create a New Rule Set and Model
Rules" on page 18-23.
5.
Click Show All Versions at the bottom of the window to display all versions of
rule dictionaries in the specified repository in the business rule engine. Business
rule engines can contain multiple rule dictionaries and versions.
18-34 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
6.
Expand and select SampleRuleRepository > SampleDictionary > INITIAL >
SampleRuleset.
7.
Click OK.
You are returned to the Select a Ruleset or a Function window of the Decision
Service wizard. All fact names for the SampleRuleset rule set now appear in the
fact table.
8.
Specify the details of the interaction pattern.
■
Select the Assert Fact check box for the Ratingrequest fact type.
This asserts a fact to the rule set (sends an input parameter of factual data to
the business rule engine).
■
Select the Watch Fact check box for the Rating fact type.
This returns results created by the business rule engine as part of executing the
rule set SampleRuleset.
9.
Click Next.
The Copy XSD Files window shows the directory path to the
CreditRatingTypes.xsd schema file for the wizard to import. If the wizard cannot
find this file, you must manually copy it to the rules/xsd directory of the
SampleProcess BPEL project.
10. Click Next, then Finish.
BPEL Process Integration with Business Rules 18-35
Methodology for Rule Set Modeling and Integration with a BPEL Process
A partner link of the name you specified in Step 3 on page 18-34 is created. This
partner link provides the interface between the BPEL process and the business rule
engine.
11. Select Save from the File main menu.
See Also:
■
"Decision Service Wizard" on page 18-9
■
"Decision Service Partner Link Directory Structure" on page 18-39
Task 4: Create a Decide Activity
1.
Drag and drop a Decide activity from the Process Activities list of the Component
Palette to below the receiveInput receive activity in the designer window.
The Edit Decide window appears.
2.
Enter the following values:
Field
Value
Name
GetRating
Decision Service
CreditRatingService
Operation
Assert facts, execute rule set, retrieve results, and reset the session
3.
Click Assign Input Facts.
You now map BPEL input variables to automatically created BPEL variables that
correspond to the Ratingrequest input (assert) fact type.
4.
Click Create.
The From section shows the BPEL variables of the process and the To section
shows the facts selected for the partner link interaction. Since you reused the XML
schema file of the fact types in your BPEL process, you can assign the top level
ratingrequest element from the BPEL input variable inputVariable to the fact to
assert.
5.
Enter the following details:
Field
Value
From
■
Type
Variable
18-36 Oracle BPEL Process Manager Developer’s Guide
Methodology for Rule Set Modeling and Integration with a BPEL Process
Field
■
Variables
Value
Expand and select Variables > inputVariable > payload >
ns2:ratingrequest
Note: The namespace number values (for example, ns1, ns2) can vary.
Use the namespace values that automatically appear.
To
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Ratingrequest_i >
ns2:ratingrequest
The window appears as follows:
6.
Click OK.
7.
Click Assign Output Facts.
You now assign the results of executing the rule set to a BPEL variable. For the
assignment of output facts, the From section displays the facts as modeled in the
decision service partner link interaction and the To section lists the variables of the
BPEL process.
8.
Enter the following details:
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Rating_o > ns2:rating
BPEL Process Integration with Business Rules 18-37
Methodology for Rule Set Modeling and Integration with a BPEL Process
Field
Value
To
■
Type
Variable
■
Variables
Expand and select Variables > outputVariable > payload > ns2:rating
The window appears as follows:
9.
Click OK to close the Decision Fact Map window and Edit Decide window.
This completes decide activity configuration. The BPEL process model is updated
with the GetRating decide activity and the BPEL process is ready for deployment.
18-38 Oracle BPEL Process Manager Developer’s Guide
Decision Service Deployment and Run Time
See Also:
"Decide Activity" on page 18-14
Summary of Methodology
This section provides a summary of issues to consider before designing a rule set.
■
Plan the data model before starting to model business rules.
■
Specify the data model using XML schema constructs.
■
Import the XML schema into the rule author as XML fact types.
■
■
■
Keep limitations of JAXB in mind (element and complex type naming, target
package for multiple schemata, and so on).
Specify RL functions that can be used in rule patterns and actions.
Model a rule that does not include an if statement test pattern and set it to low
priority to generate a default result in the case where no other rule starts as part of
rule set execution.
■
Model your rules on the XML schema type level.
■
Be aware that the data exchange with the BPEL world is on the XML element level.
■
Be aware that an alternative approach using RL functions can be taken in the case
of an existing data model based on RL or Java fact types.
Decision Service Deployment and Run Time
This section describes decision service partner link creation, deployment, and run time
issues.
This section contains the following topics:
■
Decision Service Partner Link Directory Structure
■
Deployment
■
Run Time
Decision Service Partner Link Directory Structure
As part of decision service partner link creation during design time, subdirectories and
files are created under the following directory:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService
■
ear — Top level directory for the J2EE enterprise archive (EAR)
■
war — Top level directory for the Web archive (WAR)
where DecisionService is the name you entered in the Service Name field of the
Decision Service wizard.
Table 18–1 shows the subdirectories and files of the ear and war directories.
BPEL Process Integration with Business Rules 18-39
Decision Service Deployment and Run Time
Table 18–1
Contents of ear and war directories
ear/
META-INF
war/public_
html
war/
war/
war/
WEB-INF/lib WEB-INF/wsdl WEB-INF/
war/
WEB-INF/classes
applicati GetDecisio No files
on.xml
nServiceIn
fo.jsp
common.xsd
web.xml
orion-app
lication.
xml
BpelProcess
.xsd
webservices Generated JAXB
.xml
classes from XML
fact types
DecisionSer
vice.xsd
oracle-webs
ervices.xml
DecisionSer
viceMessage
s.xsd
java-wsdl-m
apping.xml
war/WEB-INF/
repository
decisionservic Oracle
es.xml
Business Rules
file repository
rpi.xsd
DecisionSer
vice.wsdl
XML schema
files for fact
types
The following steps are automatically performed as part of decision service partner
link creation:
■
A new directory structure (see Table 18–1) is created in the following directory:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService
■
■
■
■
■
■
EAR deployment descriptors are generated and stored in the META-INF
subdirectory of the enterprise archive.
A Java server page file GetDecisionServiceInfo.jsp is generated and stored
in the public_html directory of the Web archive.
The decision service-dependent WSDL file DecisionService.wsdl is
generated and stored in the WEB-INF/wsdl directory of the Web archive. All
dependent XML schema files are also copied to that directory. Dependent schema
files include the definitions for the Web service messages and contract and the
XML schema files for the XML fact types of the business rule engine.
The decision service configuration file decisionservices.xml is generated
and copied to the directory WEB-INF/classes of the Web archive.
The rule repository location is resolved:
–
If the rule repository is a file repository, the repository file is copied from its
original location to the WEB-INF/repository directory of the Web archive
and the configuration file decisionservices.xml is modified to reference
the new location.
–
If the rule repository is a WebDav repository, the configuration file is not
edited.
JAXB generation steps:
–
A list of XML schema files for the XML fact types being used in the partner
link is obtained.
18-40 Oracle BPEL Process Manager Developer’s Guide
Decision Service Deployment and Run Time
–
■
Oracle JAXB generator is used to generate JAXB classes for the XML fact types
in the directory WEB-INF/classes of the Web archive.
Web service deployment descriptors and the JAX-RPC mapping file are generated
in the directory WEB-INF of the Web archive.
The decisionservices.xml decision service configuration file includes the
necessary information to generate an interaction pattern-specific WSDL.
From the following information in the configuration file:
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
you can understand the messages and operations for WSDL generation.
In the following section, the XML schema file of the XML fact types is imported into
the decisionservices.wsdl file. This enables the fact elements to be referenced:
<types>
<schema xmlns="http://www.w3.org/2001/XMLSchema" ...>
<include schemaLocation="CreditRatingAgentTypes.xsd"/>
</schema>
<schema xmlns="http://www.w3.org/2001/XMLSchema" ...>
<import namespace="http://samples.otn.com/bpel/demo"
schemaLocation="CreditRatingTypes.xsd"/>
<import namespace="http://xmlns.oracle.com/bpel"/>
. . .
. . .
In this section, the XML schema element corresponding to the fact
creditrating.Ratingrequest is shown:
. . .
. . .
<element name="assertExecuteWatchStateless">
<complexType>
<sequence>
<element name="configURL" type="string" maxOccurs="1"/>
<element name="bpelInstance" type="bpelpm:tBpelProcess"
maxOccurs="1"/>
<element name="assertList" minOccurs="1" maxOccurs="1">
<complexType>
<sequence>
<element ref="ns1:ratingrequest"/>
</sequence>
</complexType>
</element>
</sequence>
<attribute name="name" type="NCName" use="required"/>
</complexType>
</element>
. . .
. . .
In this section, the XML schema element corresponding to the fact
creditrating.Rating is shown:
. . .
BPEL Process Integration with Business Rules 18-41
Decision Service Deployment and Run Time
. . .
<element name="assertExecuteWatchStatelessDecision">
<complexType>
<sequence>
<element name="resultList" minOccurs="1" maxOccurs="1">
<complexType>
<sequence>
<element ref="ns1:rating"/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
</schema>
</types>
. . .
. . .
In this section, appropriate messages are created for the interaction pattern:
. . .
. . .
<message name="assertExecuteWatchStatelessMessage">
<part name="payload" element="tns:assertExecuteWatchStateless"/>
</message>
<message name="assertExecuteWatchStatelessDecisionMessage">
<part name="payload"
element="tns:assertExecuteWatchStatelessDecision"/>
</message>
<message name="decisionServiceError">
<part name="payload" element="tns:errorInfo"/>
</message>
. . .
. . .
In this section, an operation is created for the interaction pattern with input and
output messages corresponding to the selected fact types:
. . .
. . .
<portType name="IDecisionService">
<operation name="assertExecuteWatchStateless">
<input name="assertExecuteWatchStatelessInput"
message="tns:assertExecuteWatchStatelessMessage"/>
<output name="assertExecuteWatchStatelessOutput"
message="tns:assertExecuteWatchStatelessDecisionMessage"/>
<fault name="operationErroredFault"
message="tns:decisionServiceError"/>
</operation>
</portType>
Deployment
The decision services modeled in a BPEL project are deployed with the BPEL process.
As part of BPEL process deployment, the following steps are performed for all
decision services in the project:
■
The Java compiler (javac) is used and all Java classes are compiled in the
subdirectory WEB-INF/classes.
18-42 Oracle BPEL Process Manager Developer’s Guide
Decision Service Deployment and Run Time
■
■
■
A Web archive DecisionService.war file is created in the ear enterprise
archive subdirectory of a decision service. The Web archive consists of all files
under the war directory of a decision service.
An enterprise archive DecisionService.ear file is created in the top level
directory of a decision service. The enterprise archive consists of all files in the ear
directory of a decision service, plus the Web archive created above.
The enterprise archive DecisionService.ear is deployed to the underlying
J2EE container using the administrator tools of the specific container.
The J2EE context root of a decision service DecisionService is as follows:
http://${hostname}:${http_port}/rules/${domain_id}/${process_id}/${process_
revision}/DecisionService
The parameters for this syntax are defined as follows:
Parameter
Description
${hostname}
The name of the host that on which the application server
is installed
${http_port}
The HTTP port of the application server
${domain_id}
The BPEL domain
${process_id}
The BPEL process name
${process_revision}
The BPEL process version
The decision services for a specific BPEL process and revision can be identified using
Oracle Enterprise Manager 10g Grid Control Console.
See Also:
"Run Time" on page 18-43
Run Time
The decision service run time component is a standard J2EE JAX-RPC Web service.
This section describes how to manage the decision service from the following consoles:
■
Oracle Enterprise Manager 10g Application Server Control Console Support
■
Oracle BPEL Control Support
See Also: The AutoLoanDemo tutorial, which describes how to
design a BPEL process that integrates with business rules and uses
human workflow:
SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
Oracle Enterprise Manager 10g Application Server Control Console Support
There are several implications of deploying decision services as self-contained
enterprise archives. The most important is that every decision service can be managed
separately and independently of its invoking BPEL process using Oracle Enterprise
Manager 10g Application Server Control Console.
For example, with the AutoLoanDemo sample included as part of Oracle BPEL
Process Manager, the AutoLoanFlow BPEL process consists of two decision service
partner links:
BPEL Process Integration with Business Rules 18-43
Decision Service Deployment and Run Time
■
Loan advisor
■
Credit rating
1.
Log into Oracle Enterprise Manager 10g Application Server Control Console.
http://hostname:port/em
2.
Click Web Services.
The two decision services appear: LoanAdvisorAgent and CreditRatingAgent.
You can manage and diagnose the decision services as with any other Web service.
3.
Click CreditRatingAgentPort to receive more details for the CreditRatingAgent
decision service:
4.
Click Operations to access additional details:
18-44 Oracle BPEL Process Manager Developer’s Guide
Decision Service Deployment and Run Time
Oracle BPEL Control Support
You can monitor and diagnose decision services through Oracle BPEL Control. A
decisionServiceDetails property is added to the BPEL suitcase that refers to the
configuration information of a decision service partner link.
1.
Log into Oracle BPEL Control.
2.
Click the AutoLoanFlow BPEL process in Oracle BPEL Control.
3.
Click Descriptor.
The Descriptor tab shows the process descriptor of the AutoLoanFlow process
included with the AutoLoanDemo sample:
The process has two decision service partner links configured:
4.
■
CreditRatingAgentPL for credit rating
■
LoanAdvisorAgentPL for loan advisory
Access additional details about a decision service partner link by clicking Rule
Service Details (for example, the details for CreditRatingAgentPL).
BPEL Process Integration with Business Rules 18-45
Decision Service Deployment and Run Time
The information displayed includes the following:
■
■
5.
Rule engine information
–
The backend rule engine provider (Oracle in this case)
–
The physical location of the rule repository
–
The name of the rule catalog being used for that partner link
–
(Optional) The version of the rule catalog being used
–
(Optional) The rule set used by the partner link
Interaction information
–
The interaction patterns used by the partner link
–
The input and output fact types used per interaction pattern
If you want to open the rule author and update the rule set, click Open Rule
Author.
Decide activity details are also available in the Flow window.
6.
Click the Instances tab.
7.
Click a specific instance in the Instance list.
8.
Click Flow.
9.
Click a decide activity in the process instance flow to access the same information
(for this example, named LoanAdvisorAgent).
18-46 Oracle BPEL Process Manager Developer’s Guide
Advanced Decision Service Features
This displays the following information:
Advanced Decision Service Features
This section describes advanced decision service features for which limited or no user
interface support is provided. Instead, you manually edit deployment description and
configuration files to use these features.
This section contains the following topics:
■
Using WSIF Bindings
■
Enabling Logging of Oracle Business Rules Rule Session Events
■
Customizing assertXPath
Using WSIF Bindings
As described in "Decision Service Components" on page 18-4, decision services are
JAX-RPC Web services. Therefore, SOAP is the protocol to use with a decision service.
However, you can configure the BPEL process to use the decision service in a WSIF
context.
Perform the following procedures:
BPEL Process Integration with Business Rules 18-47
Advanced Decision Service Features
1.
Remove the wsdlRuntimeLocation property for a decision service partner link
from the bpel.xml deployment descriptor file of the BPEL process.
2.
Add fact type Java classes to the classpath of Oracle BPEL Process Manager.
a.
If the decision service partner link was deployed before, you can copy all the
files from:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService\war\WEB-INF\classes
to
SOA_Oracle_Home\bpel\system\classes
b.
Otherwise, you must compile the Java classes located in the following
directory:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService\war\WEB-INF\classes
to
SOA_Oracle_Home\bpel\system\classes
3.
Deploy the BPEL process.
Enabling Logging of Oracle Business Rules Rule Session Events
The Oracle Business Rules Rules Engine defines several rule session events for
monitoring. (See Oracle Business Rules Language Reference Guide for additional details.)
The decision service provides the option to enable these events and log the output to
the Oracle BPEL Process Manager log file.
The events are enabled through properties in the decision service configuration file
(decisionservices.xml). Table 18–2 describes the properties that can be set.
Table 18–2
Decision Service Configuration File Parameters
Property
Description
watchRules
Information about rule invocations (execution of activations)
watchActivations
Addition or removal of activations from the agenda
watchFacts
Assertion, retraction, or modification of facts in working memory
watchFocus
Pushing or popping of the rule set stack
watchCompilations When a rule’s conditions are added to the network, information about
how the condition parts are shared with existing rules is printed. “=”
indicates sharing.
watchAll
1.
Includes information from all of the above events
Open the file:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService\war\WEB-INF\classes\decisionservices.xml
2.
Add the properties after the repository element in the ruleEngineProvider
section.
<?xml version = '1.0' encoding = 'UTF-8'?>
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
18-48 Oracle BPEL Process Manager Developer’s Guide
Advanced Decision Service Features
<ruleEngineProvider name="CreditRatingRuleRepository"
provider="Oracle">
<repository type="File">
<file>repositoryresource:CreditRatingRepository</file>
</repository>
<properties>
<property name="watchRules">true</property>
<property name="watchActivations">true</property>
<property name="watchFacts">true</property>
<property name="watchCompilations">true</property>
</properties>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
targetNamespace="http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert>creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
</decisionServices>
3.
Redeploy the decision service. The following is a sample output taken from the
credit rating agent of the AutoLoanFlow process.
<2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> Execution plan for AutoLoanFlow:202
<2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> assert fact creditrating.Ratingrequest
<2006-07-05 10:18:13,710> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> f-1
creditrating.RatingrequestImpl(SSN : "12345", age : 41, amount : 60000.0, date
: null, name : "Irving Stone", DOMNode : <ratingrequest
xmlns="http://samples.otn.com/bpel/demo">
.....
<2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__
xpath.retractDeadRatingrequest : f-1,
<2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__
xpath.retractDeadRatingrequestType : f-1,
<2006-07-05 10:18:13,750> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation:
PrivateCustomerRatingRules.Default : f-1
<2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation:
PrivateCustomerRatingRules.YoungCustomers : f-1
<2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation:
PrivateCustomerRatingRules.HighRiskCustomers : f-1
<2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> Execute rule set
PrivateCustomerRatingRules
<2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> Fire 1
BPEL Process Integration with Business Rules 18-49
Advanced Decision Service Features
PrivateCustomerRatingRules.YoungCustomers f-1
<2006-07-05 10:18:13,790> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> <== f-1
creditrating.RatingrequestImpl(SSN : "12345", age : 41, amount : 60000.0, date
: null, name : "Irving Stone", DOMNode : <ratingrequest
xmlns="http://samples.otn.com/bpel/demo">
....
<2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> <== Activation: creditrating.__
xpath.retractDeadRatingrequest : f-1,
<2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> <== Activation: creditrating.__
xpath.retractDeadRatingrequestType : f-1,
<2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> <== Activation:
PrivateCustomerRatingRules.Default : f-1
<2006-07-05 10:18:13,820> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> <== Activation:
PrivateCustomerRatingRules.HighRiskCustomers : f-1
<2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> f-2
creditrating.RatingImpl(DOMNode : oracle.xml.parser.v2.XMLElement@1b1d896)
<2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__
xpath.retractDeadRating : f-2,
<2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> ==> Activation: creditrating.__
xpath.retractDeadRatingType : f-2,
<2006-07-05 10:18:13,830> <DEBUG> <default.collaxa.cube.services>
<OracleRuleSession::executeUnitOfWork> Ruleset PrivateCustomerRatingRules
executed, 1 rules fired.
Customizing assertXPath
Oracle Business Rules can specify an XPath expression when asserting facts. This
reduces the number of assertions and provides a convenient mechanism to assert
multiple facts with a single assert statement.
This functionality is available in Oracle JDeveloper. Select Check here to assert all
descendants from the top level element on the Select a Ruleset or a Function window
in the Decision Service wizard. When you select this option, a default XPath "//*" is
created for the fact to assert. This causes all descendants of the fact element to assert
during run time.
You can customize the XPath expression manually by modifying the decision service
configuration located in the following file:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\decisionservices\DecisionService\war\WEB-INF\classes\decisionservices.xml
The following example shows this option enabled for a fact type.
<?xml version = '1.0' encoding = 'UTF-8'?>
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules">
<ruleEngineProvider name="CreditRatingRuleRepository"
provider="Oracle">
<repository type="File">
<file>repositoryresource:CreditRatingRepository</file>
</repository>
</ruleEngineProvider>
<decisionService name="CreditRatingAgent"
18-50 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
targetNamespace="http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent"
ruleEngineProviderReference="CreditRatingRuleRepository">
<catalog>RatingFY06</catalog>
<catalogVersion>Approved_060205</catalogVersion>
<ruleset>PrivateCustomerRatingRules</ruleset>
<pattern name="AssertExecuteWatchStateless">
<arguments>
<assert xpath="//*">creditrating.Ratingrequest</assert>
<watch>creditrating.Rating</watch>
</arguments>
</pattern>
</decisionService>
</decisionServices>
You can customize the attribute xpath="//*" before deploying the decision service.
Example of BPEL Process Integration with Business Rules
The section describes how to design and integrate a BPEL process with the business
rules of a business rule engine. This example is part of a larger tutorial that also
describes how to design this BPEL process to use human workflow. Only the part
describing BPEL process integration with business rules is included in this section.
This section contains the following topics:
■
Task 1: Update a Rule Using Oracle Business Rules Rule Author
■
Task 2: Create a Connection to the Business Rule Repository
■
Task 3: Create a BPEL Process and Import the Schema
■
Task 4: Create a Decision Service Partner Link
■
Task 5: Create a Decide Activity
See Also: The complete AutoLoanDemo tutorial, which describes
how to design a BPEL process that integrates with business rules and
uses human workflow:
SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo
Task 1: Update a Rule Using Oracle Business Rules Rule Author
This section describes how to access the Oracle Business Rules Rule Author and
modify a business rule that you later integrate with your BPEL process.
1.
Log into the Oracle Business Rules Rule Author.
http://hostname:port/ruleauthor
The Oracle Business Rules Rule Author is automatically installed with the SOA
Suite Basic Install type.
2.
Log in as oc4jadmin/password.
where password is the oc4jadmin password you entered during installation.
3.
Click the Repository tab at the top.
4.
Select File from the Repository Type list.
BPEL Process Integration with Business Rules 18-51
Example of BPEL Process Integration with Business Rules
5.
Click Browse and select the CreditRatingRepository file repository from the
SOA_Oracle_Home\bpel\samples\demos\AutoLoanDemo\repository
directory.
This page displays the following details:
6.
Click Connect.
A message displays indicating that a connection has been made to the repository.
7.
Click the Customization tab at the top.
8.
Enter the following details to load the rule dictionary and its versions from the
repository selected in Step 5:
Field
Value
Existing Dictionaries RatingFY06
Version
Approved_060205
This page displays the following details:
9.
Click Load.
A confirmation message appears:
Dictionary 'RatingFY06 (Approved_060205)' has been loaded
10. Click the Customization tab at the top. You now modify a rule in the rule set.
11. Click the YoungCustomers rule and change request.customer age < from 40 to
45.
This page displays the following details:
18-52 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
12. Click Apply.
A message displays indicating that the customization has been applied.
13. Click the HighRiskCustomers rule and change request.customer age >= from 40
to 45.
14. Click Apply.
15. Click Save Dictionary at the top.
16. Click Save.
This saves the current dictionary contents (including your updates) in the
CreditRatingRepository repository.
17. Click Logout.
Task 2: Create a Connection to the Business Rule Repository
This section describes how to create a connection to the business rule repository.
1.
Select Connection Navigator from the View main menu in Oracle JDeveloper.
2.
Right-click Rule Engines and select New Rule Engine Connection.
3.
Click Next on the Welcome window.
4.
Enter CreditRatingRuleRepository in the Connection Name field.
5.
Select Oracle Rules Engine File Repository as the type of business rule engine to
which to connect.
BPEL Process Integration with Business Rules 18-53
Example of BPEL Process Integration with Business Rules
6.
Click Next.
The Connection window appears.
7.
Click the folder icon to select the directory in which the file repository is located.
8.
Select the CreditRatingRepository file repository from the SOA_Oracle_
Home\bpel\samples\demos\AutoLoanDemo\repository directory. This is the
repository you loaded in Step 5 on page 18-52.
9.
Click Open.
10. Click Next.
The Test Connection window appears.
11. Click Test.
If the connection to the business rule repository is successful, the following
message appears:
Success
18-54 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
12. Click Finish.
Task 3: Create a BPEL Process and Import the Schema
You now create a BPEL process in which to integrate the business rules of the business
rule engine you modified in "Task 1: Update a Rule Using Oracle Business Rules Rule
Author" on page 18-51.
1.
Right-click your application in the Application Navigator section.
2.
Select New Project to define a new BPEL process project.
3.
Double-click BPEL Process Project in the Items window to display the BPEL
Project Creation Wizard window.
4.
Enter AutoLoanFlow in the Name field. All other fields default to the correct
values for creating an asynchronous BPEL process.
5.
Click Next.
6.
Click the flashlight icon to the right of the Input Schema Element field.
7.
In the Select Schema window, select AutoLoanTypes.xsd from the SOA_Oracle_
Home\bpel\samples\demos\AutoLoanDemo\AutoLoanFlow\bpel directory
and click Open.
The Type Chooser window appears.
8.
Expand and select Imported Schemas > AutoLoanTypes.xsd > loanApplication.
9.
Click OK.
10. Click the flashlight icon to the right of the Output Schema Element field.
The Type Chooser window appears.
11. Expand and select Imported Schemas > AutoLoanTypes.xsd > loanOffer.
12. Click OK.
13. Click Finish.
Task 4: Create a Decision Service Partner Link
You now use the Decision Service Wizard to connect to the business rule engine and
convert the rule set you modified in "Task 1: Update a Rule Using Oracle Business
Rules Rule Author" into a Web service to use in the BPEL process. When complete, a
decision service partner link is created.
1.
Ensure that Services is selected in the drop-down list of the Component Palette
section in the upper right section of Oracle JDeveloper.
2.
Drag and drop a Decision Service onto the right side of the designer window
anywhere beneath the header Services.
The Select a Ruleset or a Function window appears.
This window enables you to select an invocation pattern.
3.
Enter the following details:
Field
Value
Service Name
CreditRatingAgent
Note: When complete, this becomes the name of the partner link.
BPEL Process Integration with Business Rules 18-55
Example of BPEL Process Integration with Business Rules
Field
Value
Namespace
http://xmlns.oracle.com/myLoanProcess/CreditRatingAgent
Note: This field is automatically completed with your entry in the
Service Name field.
Invocation Pattern
Execute Ruleset
The window now appears as follows:
4.
Click the flashlight icon next to the Ruleset field.
The Rule Explorer window appears.
This window enables you to browse and select the rule set in the dictionary of the
repository you modified in "Task 1: Update a Rule Using Oracle Business Rules
Rule Author" on page 18-51.
5.
Click Show All Versions at the bottom of the window to display all catalog
versions of rule dictionaries in the specified repository. Business rule repositories
can contain multiple rule dictionaries and versions.
6.
Expand and select CreditRatingRuleRepository > RatingFY06 > Approved_
060205 > PrivateCustomerRatingRules.
18-56 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
7.
Click OK.
You are returned to the Select a Ruleset or a Function window of the Decision
Service wizard. Note that all fact names for the PrivateCustomerRatingRules rule
set now appear in the fact table.
8.
Select the input (Assert Fact) and output (Watch Fact) fact types:
■
Select the Assert Fact check box for the Ratingrequest fact type.
This asserts a fact to the rule set (sends factual data to the business rule
engine).
■
Select the Watch Fact check box for the Rating fact type.
This returns results from the rule set. This table column only appears because
you selected an invocation pattern that retrieves results in Step 3 on
page 18-55.
BPEL Process Integration with Business Rules 18-57
Example of BPEL Process Integration with Business Rules
9.
Click Next.
This window shows the schema file for the wizard to import.
10. Click Next, then Finish.
A partner link of the name you specified in Step 3 on page 18-55 is created. This
partner link provides the interface between the BPEL process and the business rule
engine.
18-58 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
11. Select Save from the File main menu.
Task 5: Create a Decide Activity
You now create a decide activity to invoke the decision service partner link you
created with the Decision Service wizard. The decide activity enables you to create
copy operation assignments between the fact types in your rule set (now included in
the partner link) and BPEL variables. You provide an input fact to the rule set and then
retrieve the results. This enables you to invoke rules from the BPEL process.
When complete, a decide activity consisting of assign and invoke activities to the
decision service partner link is created.
1.
Drag and drop a Decide activity below the receiveInput receive activity in the
designer window.
2.
Enter the following values:
Field
Value
Name
GetCreditRating
Decision Service
CreditRatingAgent
Operation
Assert facts, execute rule set, retrieve results, and reset the session
3.
Click Assign Input Facts.
You now map BPEL input variables to automatically created BPEL variables that
correspond to the Ratingrequest input (assert) fact type.
4.
Click Create.
5.
Enter the following details:
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > inputVariable > payload >
ns1:loanApplication > ns1:SSN
Note: The namespace number values (for example, ns1, ns2) can vary.
Use the namespace values that automatically appear.
To
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Ratingrequest_i >
ns3:ratingrequest > ns3:SSN
The window appears as follows:
BPEL Process Integration with Business Rules 18-59
Example of BPEL Process Integration with Business Rules
6.
Click OK.
7.
Click Create again to create a second copy operation.
8.
Enter the following details:
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > inputVariable > payload >
ns1:loanApplication > ns1:customerName
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Ratingrequest_i >
ns3:ratingrequest > ns3:name
9.
Click OK.
To
10. Click Create again to create a third copy operation.
11. Enter the following details:
Field
Value
From
■
Type
Variable
18-60 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
Field
Value
Variables
Expand and select Variables > inputVariable > payload >
ns1:loanApplication > ns1:loanAmount
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Ratingrequest_i >
ns3:ratingrequest > ns3:amount
■
To
12. Click Apply.
The Edit Decide window displays the following input fact mappings:
13. Click Assign Output Facts.
You now map the automatically created BPEL variables that correspond to the
Rating output fact type to BPEL input variables.
14. Click Create.
15. Enter the following details to create the output facts:
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Rating_o > ns2:rating >
ns2:rating
Note: The namespace number values (for example, ns1, ns2) can vary.
Use the namespace values that automatically appear.
To
■
Type
Variable
BPEL Process Integration with Business Rules 18-61
Example of BPEL Process Integration with Business Rules
Field
■
Variables
Value
Expand and select Variables > inputVariable > payload >
ns3:loanApplication > ns3:creditRating
The window appears as follows:
16. Click OK.
17. Click Create again to create a second copy operation.
18. Enter the following details:
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Rating_o > ns2:rating >
ns2:risk
■
Type
Variable
■
Variables
Expand and select Variables > inputVariable > payload >
ns3:loanApplication > ns3:creditRisk
To
19. Click OK.
20. Click Create again to create a third copy operation.
21. Enter the following details:
18-62 Oracle BPEL Process Manager Developer’s Guide
Example of BPEL Process Integration with Business Rules
Field
Value
From
■
Type
Variable
■
Variables
Expand and select Variables > creditrating_Rating_o > ns2:rating >
ns2:maxAmount
■
Type
Variable
■
Variables
Expand and select Variables > inputVariable > payload >
ns3:loanApplication > ns3:creditMaxAmount
To
22. Click OK.
The Edit Decide window displays the following output fact mappings:
23. Click OK.
When complete, a decide activity consisting of assign and invoke activities to the
decision service partner link is created.
BPEL Process Integration with Business Rules 18-63
Example of BPEL Process Integration with Business Rules
24. Click the + sign to expand the GetCreditRating decide activity and view the
assign and invoke activities.
The BPEL process is now integrated with the business rules of the business rule
engine. If you later modify the contents of the business rule, you do not need to
redesign your BPEL process.
25. Select Save from the File main menu.
18-64 Oracle BPEL Process Manager Developer’s Guide
Part IV
Development and Deployment Life Cycle
This part describes how to run and manage BPEL processes from Oracle BPEL Control.
This part contains the following chapters:
■
Chapter 19, "BPEL Process Deployment and Domain Management"
■
Chapter 20, "Testing BPEL Processes"
■
Chapter 21, "Oracle BPEL Portlets"
■
Chapter 22, "Oracle BPEL Control Reports"
19
BPEL Process Deployment and
Domain Management
This chapter provides an overview of key BPEL process deployment and domain
management concepts. An overview of Oracle BPEL Control from which you can
manage processes and domains is also provided. In addition, an overview of several
build and command line tools is also provided.
This chapter contains the following topics:
■
Compiling and Deploying a BPEL Process
■
Creating and Managing a BPEL Domain
■
Managing Processes in Oracle BPEL Control
■
Build and Command Line Tools
■
Summary
See Also: The following documentation for tutorials in which you
deploy BPEL processes:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
Compiling and Deploying a BPEL Process
After you complete the design of your BPEL process, you compile and deploy the
process to Oracle BPEL Server. If compilation and deployment are successful, you can
run and manage the BPEL process from Oracle BPEL Control.
Deployment sends the Oracle BPEL Process Manager archive (a set of files in a JAR file
with a directory structure similar to the project directory structure) to Oracle BPEL
Server. The deployment operation automatically validates and compiles the project
directory into the BPEL archive. Therefore, you do not need to explicitly validate,
compile, and recompile a project before deployment. Use Oracle BPEL Control to view
any currently running BPEL processes before compiling and deploying additional
processes.
BPEL processes can be compiled and deployed in Oracle JDeveloper.
You must wait for deployment of one BPEL process to
complete before attempting to deploy another process. Attempting to
deploy a second process while the first process is still deploying can
cause problems.
Note:
BPEL Process Deployment and Domain Management 19-1
Compiling and Deploying a BPEL Process
Compiling and Deploying in Oracle JDeveloper
To compile and deploy a BPEL process in Oracle JDeveloper, right-click the BPEL
project (for this example, named OrderBooking) in the Application Navigator and
select Deploy:
You have two deployment methods from which to choose:
■
You can deploy directly to the default domain or any other domain you have
created by using an integration server connection.
Domains enable you to partition and manage instances of your processes. A
discussion on the importance of domains is provided later in this chapter.
If this is the first time you have deployed this BPEL process to Oracle BPEL Server,
a default version label of 1.0 is automatically created. A version identifies a
specific deployed instance of a BPEL process. The version label is appended to the
end of the JAR file name created when you deploy the BPEL process.
If this label version is already deployed and the server mode is production, you
are prompted to either overwrite the existing version or enter a different version
label:
If you overwrite the version, the old process definition on the server is replaced by
the new definition. You cannot revert to the old definition. In addition, any process
instances that ran under the old definition are marked as stale. The stale instances
cannot be examined, and all flow and audit information is lost. If you enter a
different version label for the new process definition (for example, 2.0), it is
deployed to Oracle BPEL Server, while the older, deployed process definition
(1.0) also continues to run simultaneously on Oracle BPEL Server. The instances
that ran under the old definition are retained, and not marked as stale. You can
still examine the flow and audit information for these instances.
If the server mode is development, you are not prompted and the version is
automatically overwritten.
19-2 Oracle BPEL Process Manager Developer’s Guide
Compiling and Deploying a BPEL Process
This is a key benefit of versioning. For example, you may have an older instance of
a BPEL process running with one customer that is still valid. You then begin a
partnership with a different customer that requires a slight modification to the
design of this BPEL process. At some point you plan to migrate the old customer
to the newer version of the BPEL process, but for now that is not necessary.
Versioning enables you to run both processes.
If you want to use a more descriptive version name for a process, right-click the
process again in the Application Navigator and select Deploy > connection_name
> Deploy to domain_name domain. Provide a more descriptive name when
prompted in the Your version field of the Deployment Properties window (for
example, sales_div_1.0). You can then retire the other process version on Oracle
BPEL Control.
■
If you select BPEL Process Deployer, the BPEL Process Deployer window opens.
This window enables you to customize your settings by selecting a different or
creating a new Oracle BPEL Server connection and deploying to domains other
than default. If this process version is already deployed, you can also select to
overwrite the existing version or enter a different version label to enable both to
run simultaneously.
After you select a deployment method, the Log Window at the bottom of Oracle
JDeveloper displays messages about the status of the deployment. For example, the
following message under the Messages tab indicates that deployment was successful.
The following message under the Apache Ant tab also indicates that deployment was
successful.
Caution: Use caution when reusing version labels in a production
environment, due to the potential loss of data. In a development
environment, it can be useful to reuse version numbers to avoid
creating unnecessary revisions of the process on Oracle BPEL Server.
If deployment is unsuccessful, errors display in the Log Window. Click the error to
display the line of code that caused deployment to fail.
BPEL Process Deployment and Domain Management 19-3
Compiling and Deploying a BPEL Process
Make corrections and redeploy.
See Also:
■
"Creating a BPEL Domain" on page 19-7
■
"Changing Oracle BPEL Server Mode" on page 19-7
■
Oracle BPEL Process Manager Order Booking Tutorial and Oracle
BPEL Process Manager Quick Start Guide for instructions on
creating integration server connections
Compiling Without Deploying in Oracle JDeveloper
You can also compile without immediately deploying an Oracle BPEL Process
Manager archive to Oracle BPEL Server. Perform this action by right-clicking the BPEL
process and selecting Make or Rebuild. This places the Oracle BPEL Process Manager
archive in the following directory:
JDev_Oracle_Home\jdev\mywork\my_application\project_name\output
From this directory, you can deploy the process in either of two ways:
1.
Copy the archive to the appropriate domain directory (for this example, default)
SOA_Oracle_Home\bpel\domains\default\deploy
or
1.
Log into Oracle BPEL Control by selecting Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process Manager > BPEL Control.
2.
Click BPEL Processes.
19-4 Oracle BPEL Process Manager Developer’s Guide
Creating and Managing a BPEL Domain
3.
Click Deploy New Process in the Related Tasks section.
4.
Click Browse to select the BPEL suitcase JAR file for the process, then click Open.
5.
Click Deploy.
6.
Click the Dashboard tab to view the newly deployed process.
BPEL Suitcase JAR File
During compilation and deployment, the BPEL process archive and its components are
compiled and packaged into a JAR file known as a BPEL suitcase. This JAR file
includes the following files:
■
project_name.bpel file implementation of the process
■
project_name.wsdl file
■
bpel.xml deployment descriptor file
■
Any other local resources that are required, such as XML schemas, Java classes or
libraries, and so on
The suitcase JAR file is deployed to the JDev_Oracle_
Home\jdev\mywork\application_name\process_name\output directory. The
suitcase JAR file name follows the convention of bpel_projectname_
versionnumber.jar. For example:
bpel_LoanProcess_1.0.jar
See Also:
■
"Creating and Managing a BPEL Domain" on page 19-5
■
"Deploying a BPEL Suitcase to a Specific Domain" on page 19-8
Creating and Managing a BPEL Domain
BPEL processes (specifically, the suitcase JAR file) are deployed to domains. A BPEL
domain allows a developer or administrator to partition a single instance of Oracle
BPEL Process Manager into multiple virtual BPEL sections.
Here are some examples of how to use BPEL domains:
■
■
■
Partition a single Oracle BPEL Process Manager instance into a multideveloper
environment. In this case, the domain ID typically identifies the developer owning
that domain.
Partition a single Oracle BPEL Process Manager instance into both a development
and QA environment. In this case, the domain IDs can be test and qa.
Partition a single Oracle BPEL Process Manager instance into an environment used
by multiple departments or partners. In these cases, the domain IDs are the names
of the departments or partners.
The following sections describe key BPEL domain issues:
■
Logging into Domains
■
Changing Domain Passwords
■
Creating a BPEL Domain
■
Changing Oracle BPEL Server Mode
■
Deploying a BPEL Suitcase to a Specific Domain
BPEL Process Deployment and Domain Management 19-5
Creating and Managing a BPEL Domain
■
Undeploying a BPEL Process from a Specific Domain
Logging into Domains
Oracle BPEL Process Manager domain management and administration is performed
from Oracle BPEL Control and Oracle BPEL Admin Console.
Beginning with this release, Oracle BPEL Control and Oracle BPEL Admin Console are
secured with Oracle Application Server J2EE and JAAS security features. Access to
BPEL domains is now protected through user IDs and passwords. In previous releases,
only a password was required.
When Oracle BPEL Process Manager is installed, an initial domain named default is
created. The initial password for accessing the default domain through Oracle BPEL
Control or any domain you create is the same as that specified for the oc4jadmin user
during installation. The procedural instructions described in this chapter for
performing tasks use the oc4jadmin user.
You can also use the bpeladmin user or default user and their default password of
welcome1 to access domains. The bpeladmin user provides access to all domains
and the default user provides access to only the default domain.
The oc4jadmin, bpeladmin, and default users enable you to access Oracle BPEL
Control through the following methods:
■
■
Selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process
Manager > BPEL Control
Going to the following URL:
http://localhost:port/BPELConsole
where port is:
–
8888 if you installed Oracle BPEL Process Manager from the Oracle
Application Server SOA software CD.
–
9700 if you installed the Oracle BPEL Process Manager for Developers or
Oracle BPEL Process Manager for OracleAS Middle Tier install type from the
Oracle BPEL Process Manager software CD.
The oc4jadmin and bpeladmin users enable you to access Oracle BPEL Admin
Console through the following URL:
http://localhost:port/BPELAdmin
You cannot access Oracle BPEL Admin Console with the default user. Both Oracle
BPEL Control and Oracle BPEL Admin Console are described further in subsequent
sections of this chapter.
See Also:
■
■
Security chapter of the Oracle BPEL Process Manager
Administrator’s Guide for additional details about Oracle BPEL
Control and Oracle BPEL Admin Console users and the roles that
provide access to domains
Oracle BPEL Process Manager Installation Guide for information
about supported Web browsers
19-6 Oracle BPEL Process Manager Developer’s Guide
Creating and Managing a BPEL Domain
Changing Domain Passwords
Passwords for the oc4jadmin, bpeladmin, and default users can be changed
through Oracle Enterprise Manager 10g Application Server Control Console. Oracle
recommends that you change the passwords for the bpeladmin and default users
after installation.
See Also:
■
■
Oracle Application Server Administrator’s Guide for instructions on
changing the oc4jadmin, bpeladmin, and default passwords
Oracle BPEL Process Manager Administrator’s Guide for additional
details about Oracle BPEL Process Manager security
Creating a BPEL Domain
You can create additional domains by performing the following procedures.
1.
Access Oracle BPEL Admin Console:
http://localhost:port/BPELAdmin
2.
Enter the oc4jadmin username and password.
3.
Click the BPEL Domains tab.
4.
Click Create New BPEL Domain.
The Create New BPEL Domain window appears.
5.
Follow the on-screen instructions to create a new domain with an ID.
6.
Return to Oracle JDeveloper.
7.
Right-click a process.
8.
Select Deploy > connection_name > Refresh.
9.
Select Deploy > connection_name > Deploy to domain_name domain.
where domain_name is the ID you entered in Step 5.
10. Log in to Oracle BPEL Control.
11. Select the new domain name from the drop-down list in the upper right corner of
Oracle BPEL Control.
The process you deployed in Step 9 displays in the Dashboard tab.
Changing Oracle BPEL Server Mode
Oracle BPEL Server is automatically installed in production mode. If you attempt to
deploy a process in production mode and a label version of that process is already
deployed, you are prompted to either overwrite the existing version or enter a
different version label.
Follow these instructions to see the current mode of your server in Oracle JDeveloper.
1.
Right-click the BPEL process in the Application Navigator.
2.
Select Deploy > BPEL Process Deployer.
The Server Mode field of the BPEL Process Deployer window displays the mode.
BPEL Process Deployment and Domain Management 19-7
Creating and Managing a BPEL Domain
You can change this mode to development. When you attempt to deploy a process in
development mode and a label version of that process is already deployed, it is
automatically overwritten and you are not prompted to make a decision.
Follow these instructions to change the current mode of your server.
1.
Access Oracle BPEL Admin Console:
http://localhost:port/BPELAdmin
2.
Enter the oc4jadmin username and password.
3.
Click the Server tab.
4.
Change the productionServer property value to false.
5.
Click Apply.
6.
Return to the BPEL Process Deployer window. The Server Mode field now
displays as Development.
Deploying a BPEL Suitcase to a Specific Domain
In addition to the domain deployment methods described in "Compiling and
Deploying a BPEL Process" on page 19-1, there are other methods for deploying a
BPEL suitcase into a domain:
1.
If the domain is local, configure the deploy option of the bpelc ant task to
perform local deployment to a specific domain. The following example shows an
ant build script deploying the BPEL suitcase to a domain named qa:
<?xml version="1.0"?>
<project name="LoanFlow" default="main" basedir=".">
<property name="deploy" value="qa"/>
<property name="rev" value="1.0"/>
<target name="main">
<bpelc orabpelhome="${orabpelHome}" rev="${rev}" deploy="${deploy}"/>
</target>
</project>
2.
If the domain is not local to the environment in which to compile the BPEL
suitcase, use the Deploy New Process link under the Dashboard tab in Oracle
BPEL Control to remotely upload and deploy a BPEL JAR file. Links to this task
are located in the bottom-left portion of the Dashboard tab and bottom-left
portion of the BPEL Processes tab. You can simply run the bpelc task without the
deploy option to create the BPEL suitcase JAR in the current directory. If you have
19-8 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
already deployed the BPEL suitcase locally, you can upload it from your local
deployment directory. See "BPEL Suitcase JAR File" on page 19-5 for more
information on where deployed BPEL suitcases can be found.
3.
Deploying a BPEL process is equivalent to copying the BPEL suitcase JAR file into
the deploy directory of the appropriate BPEL domain. Even if you are accessing
the domain remotely, all you need is disk sharing, FTP, secure copy (SCP), or some
other access to the server hosting the domain. You can add this to your ant
build.xml script to remove the deploy option as described above and then add
your own task to perform the remote copy of the generated JAR file into the
appropriate location.
See Also: "Build and Command Line Tools" on page 19-23 for
additional details about ant and bpelc
Undeploying a BPEL Process from a Specific Domain
Oracle BPEL Control enables you to manage the life cycle and state of a deployed
BPEL process. Select the name of the BPEL process on the Dashboard tab and then
select the Manage tab on the left. On this page you can first retire and then undeploy
the selected BPEL process. Retiring a process prevents any new instances of that
process from being created. If a specific version of a BPEL process is undeployed
before all pending in-flight instances are completed, those instances are marked as
stale and their execution is cancelled. Note that every task that can be performed in
Oracle BPEL Control can also be performed programmatically.
Managing Processes in Oracle BPEL Control
If compilation and deployment are successful, you can run and manage the BPEL
process from Oracle BPEL Control. This section provides an overview of the main
pages of Oracle BPEL Control.
1.
Log into Oracle BPEL Control by selecting Start > All Programs > Oracle Oracle_Home > Oracle BPEL Process Manager > BPEL Control.
2.
Enter the oc4jadmin username and password.
3.
See the following sections for an overview of Oracle BPEL Control:
■
Dashboard Tab: Viewing Deployed, Running, and Completed Processes
■
BPEL Processes Tab: Managing the Process Life Cycle
■
Instances Tab: Viewing Process Instances
■
Activities Tab: Viewing Process Activities
Dashboard Tab: Viewing Deployed, Running, and Completed Processes
When you log into Oracle BPEL Control, the Dashboard tab displays by default. This
page displays the currently deployed BPEL processes and instances of BPEL processes
that are currently running (in-flight) and that have recently completed. Click a
deployed BPEL process in the Name column to access a page for creating an instance
and testing your process. Use Oracle BPEL Control to view any currently running
BPEL processes before compiling and deploying additional processes. An asterisk
identifies the version that is the default process. Default processes are described later
in this chapter.
BPEL Process Deployment and Domain Management 19-9
Managing Processes in Oracle BPEL Control
Viewing and Changing Domains
Each Oracle BPEL Control window includes links in the upper right corner for
managing BPEL domains, accessing the BPEL site on the Oracle Technology Network,
and switching to another domain. The domain into which you are currently logged is
always displayed. When Oracle BPEL Process Manager is installed, an initial domain
named default is created. You can create additional domains. A drop-down list
enables you to access any of these domains.
1.
Click the Domain list to display a list of available domains.
2.
Select an appropriate domain to access (for this example, sales).
The Dashboard tab of the selected domain appears without prompting you to
enter the password.
BPEL Processes Tab: Managing the Process Life Cycle
1.
Click the BPEL Processes tab to view BPEL process life cycles and states. Note that
different version labels of OrderBooking are currently active. A process identified
with an asterisk (for this example, OrderBooking version 1.5) is the default
process.
19-10 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
Instructions for using the sections of the BPEL Processes tab are listed in Table 19–1.
Table 19–1
BPEL Processes Tab
For This Section...
See...
Clear WSDL Cache
"Clearing the WSDL Cache" on page 19-11
Deploy New Process
"Deploying New Processes" on page 19-11
Perform Manual Recovery
"Performing Manual Recovery" on page 19-11
Refresh Alarm Table
"Refreshing the Alarm Table" on page 19-12
View Process Log
"Viewing the Process Logs" on page 19-12
Deployed Processes
"Managing the Process Life Cycle" on page 19-12
Clearing the WSDL Cache
Click Clear WSDL Cache to clear the cache for all WSDLs of the selected domain.
Deploying New Processes
Click Deploy New Process to deploy BPEL processes from Oracle BPEL Control
instead of using Oracle JDeveloper.
See Also: "Compiling Without Deploying in Oracle JDeveloper" on
page 19-4
Performing Manual Recovery
Click Perform Manual Recovery to perform a manual recovery of messages. For
example, if you are using the file adapter and your system server crashes while
inbound messages are being processed, you can manually perform recovery when the
server restarts to ensure that all message records are recovered. For example, a file has
ten messages and the server crashes after three messages have been processed. This
causes the fourth message to go undelivered. When the server restarts and begins
BPEL Process Deployment and Domain Management 19-11
Managing Processes in Oracle BPEL Control
processing with message five (the offset of the last successfully rejected message), you
can manually recover message four to ensure that all messages are preserved.
Refreshing the Alarm Table
Click Refresh Alarm Table to refresh the alarm table for the selected domain. This
registers all pending wait/onAlarm activities with the system.
Viewing the Process Logs
Click View Process Log to view the events of all BPEL processes in the selected
domain (for example, when a process was compiled, undeployed, marked as the
default instance, and so on).
Managing the Process Life Cycle
This section describes how to manage the life cycle of a process.
1.
Click a specific process in the BPEL Process list.
The Manage window appears. This window enables you to manage the life cycle
and state of the BPEL process.
Instructions for using the sections of this window are listed in Table 19–2.
19-12 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
Table 19–2
Managing the Process Life Cycle
For This Section...
See...
Manage
"Status Indicators for BPEL Processes" on page 19-13
"Process Life Cycle Recommendations for a Development
Environment" on page 19-14
"Process Life Cycle Recommendations for a Production
Environment" on page 19-14
"Example: Life Cycle of Processes" on page 19-15
Initiate
"Initiating Processes" on page 19-21
Descriptor
"Viewing and Setting Deployment Descriptors" on page 19-21
WSDL
"Viewing WSDL File Contents" on page 19-21
Sensors
"Viewing Sensor Data" on page 19-21
Source
"Viewing BPEL File Contents" on page 19-21
Test Suites
"Running Test Suites" on page 19-21
Reports
"Creating Reports" on page 19-21
Status Indicators for BPEL Processes For each BPEL process, Oracle BPEL Control shows
the following status indicators:
Life cycle
■
A process life cycle can be active or retired. If the process life cycle is retired, you
cannot create a new instance.
State
■
A process state can be on or off. If the process state is off, you cannot access
instances or create new ones.
Open Instances
■
The number of open instances. An open instance is an instance that is currently
being processed.
Completed Instances
■
The number of completed instances. A completed instance is an instance that has
completed processing, either successfully or due to an error.
1.
2.
Process
Perform the following process management tasks from this window:
■
Manage the process life cycle (either Active or Retired)
■
Manage the process state (either On or Off)
■
Explicitly change the default process
■
Undeploy the process
Ensure that you understand the following process life cycle and state concepts:
Description
Process Life Cycles
■
Active
All processes when deployed are automatically active (that is, existing versions are not
automatically retired). You must explicitly retire processes.
BPEL Process Deployment and Domain Management 19-13
Managing Processes in Oracle BPEL Control
Process
■
Description
Retired
A process that is no longer used. When a process is retired, all currently executing instances
complete normally. You can view previously completed instances.
Process States
■
On
Process instances can be instantiated and accessed.
■
Off
Process instances cannot be instantiated and accessed. Access to existing instances and
activities of the process is not allowed.
Default Revision
A designated process and revision that is instantiated when a new request comes in. The
default process is identified by an asterisk next to its name in Oracle BPEL Control. There can
be only one default process.
If you retire a default process, the default does not change to another process. The retired
process remains the default. You must explicitly select a new default process.
Designating a process as the default works as follows from Oracle JDeveloper:
■
■
■
Undeployed
Deploy version 1.0 of the CreditRatingService process; it displays as the default process
in Oracle BPEL Control.
Deploy version 2.0 of the CreditRatingService process; it now displays as the default
process in Oracle BPEL Control.
Redeploy version 1.0 of the CreditRatingService process; it again displays as the default
process in Oracle BPEL Control.
A process with all traces removed from the system. You cannot view previously completed
processes. Instances belonging to this process are usually purged before undeploying a
process. Undeploying the only version of a process (which is also the default) results in the
complete removal of this process.
If you cannot successfully undeploy a BPEL process from the Manage window of the BPEL
Processes tab of Oracle BPEL Control, then manually delete its JAR files. For example, if the
process is named OrderBooking, perform the following steps:
1.
Delete the following files and directories:
JDev_Oracle_Home\jdev\mywork\application_name\process_
name\output\bpel_OrderBooking_*.jar files (for example, bpel_
OrderBooking_1.0.jar, bpel_OrderBooking_2.0.jar, and so on)
SOA_Oracle_Home\bpel\domains\domain_name\tmp\.bpel_OrderBooking_
*.jar directories (for example, bpel_OrderBooking_1.0.jar, bpel_
OrderBooking_2.0.jar, and so on)
2.
Restart Oracle BPEL Server.
Process Life Cycle Recommendations for a Development Environment In a development
environment, Oracle recommends that you always deploy processes to the same
version on Oracle BPEL Server. This way, you do not need to be concerned about
marking processes explicitly as default. The life cycle to follow for this environment is
as follows:
■
■
■
■
Design your process.
Deploy the process to Oracle BPEL Server (version is 1.0). This becomes the
default process for any new instances.
Redesign the process as needed.
Redeploy the process as version 1.0 (this is a newer version that overwrites the
older version, but version 1.0 remains the default process).
Process Life Cycle Recommendations for a Production Environment In a production
environment, Oracle recommends that you increment version numbers as you deploy
newer versions. For example, if OrderBooking version 1.0 is running in a production
19-14 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
environment, then deploy the newer version of OrderBooking to version 2.0. It is your
decision as to when to mark a process as default; new instances are started using this
definition. When you are certain that you have adequately tested and verified your
process, select Mark as Default on the Manage window shown in Step 1 on page 19-12.
All version 1.0 instances switch seamlessly to version 2.0. This enables you to decide
when a process is ready for production mode. The life cycle to follow for this scenario
is as follows:
■
■
Design your process.
Deploy the process to Oracle BPEL Server with a different version number (for
example, use version 2.0 if the older default version is 1.0).
■
Test version 2.0 of the process.
■
Activate version 2.0 by marking it as the default process.
WARNING: Do not overwrite existing versions of a process with
newer versions in a production environment. This marks all
existing instances of the overwritten process as stale. Stale instances
cannot be examined, and all flow and audit information is lost.
Instead, create a separate version as described in this section and
mark the newer version as the default.
Example: Life Cycle of Processes This section provides a brief example of the various life
cycle states of two process versions. In the first stage, two instances of the same
process version are created, as shown in Table 19–3. CreditRatingService version 1.0
receives two messages, which results in the creation of two instances.
Table 19–3
Stage 1: Two Instances Created
Stage
Action
Life Cycle State
Default Process
1
Deploy
CreditRatingS
ervice version
1.0
Active=1.0 On=1.0
Version 1.0
(automatically set
as default version
in Oracle
JDeveloper)
On Arrival of New
Message Request
Create two instances for
CreditRatingService
version 1.0
The life cycle and state of the CreditRatingService version displays in the BPEL
Processes tab shown in Figure 19–1. Because CreditRatingService version 1.0 was the
first deployed version of this process, it automatically became the default process. The
two messages that resulted in the creation of two CreditRatingService version 1.0
instances have both completed.
Figure 19–1 Stage 1: Two Instances Created
BPEL Process Deployment and Domain Management 19-15
Managing Processes in Oracle BPEL Control
The two completed instances of CreditRatingService version 1.0 display in the
Instances tab shown in Figure 19–2.
Figure 19–2 Stage 1: Two Instances Created
In stage 2, you deploy CreditRatingService again, but this time with a new version
number of 2.0, as shown in Table 19–4.
Table 19–4
Stage 2: Multiple Process Versions Created
Stage
Action
Life Cycle State
Default Process
2
Deploy
CreditRatingS
ervice version
2.0
Active=1.0 On=1.0
Version 2.0
(automatically set
as default version
in Oracle
JDeveloper)
On Arrival of New
Message Request
--
This causes CreditRatingService version 2.0 to become the default version, as
indicated by the asterisk in Figure 19–3. CreditRatingService version 1.0 continues to
be deployed. This is the convention followed by Oracle JDeveloper.
Figure 19–3 Stage 2: Multiple Process Versions Created
If you again deploy CreditRatingService in Oracle JDeveloper, and select version 1.0
in the Your version field of the Deployment Properties window, CreditRatingService
version 1.0 again becomes the default version, as shown in Table 19–5 and Figure 19–4.
Table 19–5
Stage 2: Multiple Process Versions Created
Stage
Action
Life Cycle State
Default Process
2
Redeploy
CreditRatingS
ervice version
1.0
Active=1.0 On=1.0
Version 1.0
(automatically set
as default version
in Oracle
JDeveloper)
19-16 Oracle BPEL Process Manager Developer’s Guide
On Arrival of New
Message Request
--
Managing Processes in Oracle BPEL Control
Figure 19–4 Stage 2: Multiple Process Versions Created
In stage 3, you explicitly change CreditRatingService version 2.0 in Oracle BPEL
Control to be the default version and retire CreditRatingService version 1.0, as shown
in Table 19–6.
Table 19–6
Stage 3: Change Default Process and Retire Instance
Life Cycle State
Action
3
Change default Active=1.0 On=1.0
process to
OrderBooking
version 2.0
Version 2.0
(explicitly set in
Oracle BPEL
Control)
Create an instance for
OrderBooking version
2.0
3
Retire
OrderBooking
version 1.0
Version 2.0
No action
Retired=2.
0
On=2.0
Default Process
On Arrival of New
Message Request
Stage
Figure 19–5 shows Mark as Default being selected for CreditRatingService version
2.0. This makes it the default process.
Figure 19–5 Stage 3: Change Default Process and Retire Instance
Figure 19–6 shows CreditRatingService version 1.0 being retired.
BPEL Process Deployment and Domain Management 19-17
Managing Processes in Oracle BPEL Control
Figure 19–6 Stage 3: Change Default Process and Retire Instance
The modified life cycle and state of the two CreditRatingService versions displays in
the BPEL Processes tab shown in Figure 19–7. Because CreditRatingService version
2.0 was explicitly selected as the default process, it now displays the asterisk. The
message that resulted in the creation of an CreditRatingService version 1.0 instance
has completed. CreditRatingService version 1.0 displays as Retired.
Figure 19–7 Stage 3: Change Default Process and Retire Instance
The completed instance of CreditRatingService version 2.0 displays in the Instances
tab shown in Figure 19–8.
Figure 19–8 Stage 3: Change Default Process and Retire Instance
19-18 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
If you click the Dashboard tab, the retired CreditRatingService version 1.0 no longer
appears. This means you can no longer create an instance for this version.
In stage 4, you make CreditRatingService version 1.0 inactive and then undeploy it, as
shown in Table 19–7.
Table 19–7
Stage 4: Deactivate and Undeploy a Process
Stage
Action
Life Cycle State
Default Process
On Arrival of New
Message Request
4
Make
CreditRatingS
ervice version
1.0 inactive
Retired=2.
0
Off=2.0
Version 2.0
No action
4
Undeploy
CreditRatingS
ervice version
1.0
Retired=2.
0
Off=2.0
Version 2.0
No action
The state of CreditRatingService version 1.0 is changed to Off (inactive) in
Figure 19–9.
Figure 19–9 Stage 4: Deactivate and Undeploy a Process
The state of CreditRatingService version 1.0 displays as Off in the BPEL Processes tab
shown in Figure 19–10. Because you initially retired this process, any live instances
had already completed normally. If you had instead made this version inactive before
retiring it, any live instances would have faulted and been aborted.
BPEL Process Deployment and Domain Management 19-19
Managing Processes in Oracle BPEL Control
Figure 19–10 Stage 4: Deactivate and Undeploy a Process
CreditRatingService version 1.0 is then undeployed, as shown in Figure 19–11.
Figure 19–11 Stage 4: Deactivate and Undeploy a Process
The BPEL Processes tab in Figure 19–12 no longer displays CreditRatingService
version 1.0. The asterisk also no longer displays for CreditRatingService version 2.0.
However, this version is still the default. If you click this instance in the BPEL Process
list, you see that no Mark as Default button displays in the Manage window. Instead,
the following message appears.
This revision is currently selected as the default revision.
Figure 19–12 Stage 4: Deactivate and Undeploy a Process
The two completed instances of the undeployed CreditRatingService version 1.0
display as disabled in the Instances tab shown in Figure 19–13.
Figure 19–13 Stage 4: Deactivate and Undeploy a Process
Clicking one of the completed instances displays the status as Stale in Figure 19–14.
19-20 Oracle BPEL Process Manager Developer’s Guide
Managing Processes in Oracle BPEL Control
Figure 19–14
Stage 4: Deactivate and Undeploy a Process
Initiating Processes Click Initiate to run processes from the BPEL Processes tab. This is
the same window that displays when you click a process in the Deployed BPEL
Processes list of the Dashboard tab.
Viewing and Setting Deployment Descriptors Click Descriptor to view and change
deployment descriptor bpel.xml file properties of a BPEL process at run time. This
prevents you from having to reset these properties during design time and redeploy
the BPEL process.
See Also:
Appendix C, "Deployment Descriptor Properties"
Viewing WSDL File Contents Click WSDL to view the WSDL file contents for a process.
Viewing Sensor Data Click Sensors to view the fault, activity, and variable sensor data of
a process.
See Also: "Viewing Sensor and Sensor Action Definitions" on
page 17-11
Viewing BPEL File Contents Click Source to view the BPEL file contents of a process.
Running Test Suites Test suites enable you to simulate the interaction between a BPEL
process 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. Click
Test Suites to run the test cases of a deployed test suite for a BPEL process instance
and view XML document reports. By default, report results are formatted as JUnit
XML test results.
See Also:
Chapter 20, "Testing BPEL Processes"
Creating Reports Click Reports to create reports in Oracle BPEL Control that enable you
to:
■
Receive an overall view of business process instance performance
■
Analyze data for the BPEL process instances and make critical decisions
■
Analyze data of the activities that constitute a business process
■
Identify and debug faults and take appropriate corrective actions
See Also:
Chapter 22, "Oracle BPEL Control Reports"
BPEL Process Deployment and Domain Management 19-21
Managing Processes in Oracle BPEL Control
Instances Tab: Viewing Process Instances
1.
Click the Instances tab to view BPEL process instances.
2.
Click an instance in the Instance column (for example, Instance #30 of
OrderBooking). From the window that appears, you can perform the following
tasks:
■
View the state of the instance (for example, Completed, Active, or Faulted)
■
Delete the instance.
■
■
■
■
■
■
Click Flow to view a visual representation of the history of the activities in this
instance.
Click Audit to view an audit trail of this instance.
Click Debug to view the BPEL Debugger, which takes the BPEL source code
that implements this process and matches it against the state of this particular
instance. Points in the code where execution is currently paused are
highlighted in yellow (for example, the process is currently waiting for a loan
service to call back with a loan offer).
Click Interactions to view details about the activities in this instance.
Click Sensor Values to view the results of any activity, fault, or variable
sensors