Oracle BPEL Process Manager Developer'

Oracle® BPEL Process Manager
Developer’s Guide
10g Release 2 (10.1.2)
B14448-02
November 2005
Oracle BPEL Process Manager Developer’s Guide, 10g Release 2 (10.1.2)
B14448-02
Copyright © 2005, Oracle. All rights reserved.
Primary Author:
Contributor:
teams
Deanna Bradshaw, Pat Huey, Mark Kennedy, Craig West
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 Corporation, 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 Retek 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 ............................................................................................................................................................... xxi
Audience..................................................................................................................................................... xxi
Documentation Accessibility ................................................................................................................... xxi
Related Documents .................................................................................................................................. xxii
Conventions .............................................................................................................................................. xxii
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 the BPEL Designer?................................................................................................................... 1-3
JDeveloper BPEL Designer ............................................................................................................... 1-3
Eclipse BPEL Designer ...................................................................................................................... 1-5
How to Use This Guide........................................................................................................................... 1-6
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials..... 1-7
What Demonstrations Are Available? ............................................................................................ 1-8
What Activity and Conceptual References Are Available? ...................................................... 1-10
What Tutorials Are Available?...................................................................................................... 1-12
Summary ................................................................................................................................................. 1-16
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 BPEL Designer Environments........................................................................................ 2-3
Overview of JDeveloper BPEL Designer ........................................................................................ 2-3
Applications Navigator.............................................................................................................. 2-5
Diagram View Window ............................................................................................................. 2-6
Source Window ........................................................................................................................... 2-8
Component Palette ..................................................................................................................... 2-9
Property Inspector ................................................................................................................... 2-10
Structure Window.................................................................................................................... 2-11
Log Window ............................................................................................................................. 2-12
Editing Project Files in JDeveloper BPEL Designer ............................................................ 2-13
Overview of Eclipse BPEL Designer ............................................................................................ 2-13
iii
Navigator ..................................................................................................................................
Process Map and Overview Windows..................................................................................
BPEL Source Window .............................................................................................................
BPEL Inspector .........................................................................................................................
Log Window .............................................................................................................................
BPEL Palette..............................................................................................................................
Overview of Activities..........................................................................................................................
Overview of Partner Links ..................................................................................................................
Overview of Oracle BPEL Server .......................................................................................................
Overview of Oracle BPEL Console ....................................................................................................
Overview of Oracle BPEL Process Manager Services ....................................................................
Overview of Oracle BPEL Process Manager Technology Adapters.............................................
Summary .................................................................................................................................................
3
2-15
2-15
2-17
2-17
2-17
2-18
2-19
2-20
2-21
2-21
2-22
2-24
2-25
Building a Simple BPEL Process
Overview of Building a Simple BPEL Process ................................................................................... 3-1
Creating a New BPEL Project Using Eclipse BPEL Designer .......................................................... 3-2
Browsing a New Project .......................................................................................................................... 3-4
Viewing the WSDL Interface of a BPEL Process................................................................................ 3-6
Switching Between the Overview, Process Map, and Source Code ............................................... 3-7
Viewing an Overview of a BPEL Process ....................................................................................... 3-7
Viewing a Detailed Process Map ..................................................................................................... 3-8
Viewing BPEL Source Code.............................................................................................................. 3-8
Reviewing the BPEL Source Code ........................................................................................................ 3-9
Using the Sequence Activity to Performs Actions Sequentially .............................................. 3-10
Using the Assign Activity to Assign Values to Variables ......................................................... 3-11
Adding an Assign Activity to the Process Map............................................................................... 3-11
Step 1: Viewing the Process Map .................................................................................................. 3-12
Step 2: Inserting an Assign Activity ............................................................................................. 3-12
Step 3: Adding a Copy Rule .......................................................................................................... 3-13
Step 4: Defining the From Part (Source) of the Copy Rule........................................................ 3-14
Step 5: Defining the To Part (Destination) of the Copy Rule.................................................... 3-15
Compiling and Deploying the BPEL Process .................................................................................. 3-16
Testing the BPEL Process ..................................................................................................................... 3-16
Summary ................................................................................................................................................. 3-18
Part II
4
Reviewing Key BPEL Development Concepts and Code Samples
Manipulating XML Data in BPEL
Use Cases for Manipulating XML Data in BPEL ...............................................................................
Overview of Manipulating XML Data in BPEL Concepts ...............................................................
How XML Data Works in BPEL.......................................................................................................
About Data Manipulation and XPath Standards ..........................................................................
Initializing a Variable with Expression Constants or Literal XML ................................................
Copying Between Variables ...................................................................................................................
Accessing Fields within Complex Type Variables.............................................................................
iv
4-1
4-2
4-2
4-2
4-5
4-5
4-6
Assigning Numeric Values ..................................................................................................................... 4-7
Mathematical Calculations with XPath Standards ............................................................................ 4-7
Assigning String Literals ........................................................................................................................ 4-8
Concatenating Strings ............................................................................................................................. 4-8
Assigning Boolean Values ...................................................................................................................... 4-9
Assigning Date or Time .......................................................................................................................... 4-9
Manipulating Attributes...................................................................................................................... 4-10
Manipulating XML Data Sequences that Use Arrays .................................................................... 4-11
Statically Indexing into an XML Data Sequence that Uses Arrays.......................................... 4-11
Determining Sequence Size ........................................................................................................... 4-12
Dynamically Indexing by Applying a Trailing XPath to an Expression................................. 4-12
Dynamic Indexing Example ................................................................................................... 4-13
Using the bpel:append Extension to Append New Items to a Sequence ........................ 4-13
Merging Data Sequences......................................................................................................... 4-14
Dynamically Indexing with the BPEL getElement Function............................................. 4-15
Merging Data Sequences that Use Arrays............................................................................ 4-15
Appending New Items to a Sequence that Uses an Array ................................................ 4-16
SOAP-Encoded Arrays Not Supported ....................................................................................... 4-16
Converting from a String to an XML Element................................................................................. 4-16
Differences Between Document-Style and RPC-Style WSDL Files ........................................... 4-17
Enclosing the Operation Name with RPC-Style WSDL Messages .......................................... 4-18
Using Binary Attachments in SOAP Messages ............................................................................... 4-19
Use Case: SOAP Message with Binary Attachment Using MIME........................................... 4-20
WSDL File Contents ................................................................................................................ 4-21
BPEL File Contents .................................................................................................................. 4-23
Java Client Using SAAJ ........................................................................................................... 4-24
Summary ................................................................................................................................................. 4-26
5
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 ....................................................................................................................................................
6
5-1
5-2
5-2
5-3
5-3
5-4
5-5
5-5
5-6
5-7
Invoking an Asynchronous Web Service
Use Case for Asynchronous Web Services ..........................................................................................
Overview of Asynchronous Callback Concepts.................................................................................
partnerLinkTypes for Asynchronous Services ..............................................................................
Calling the Service from BPEL .........................................................................................................
How the Invoke and Receive Activities Work...............................................................................
6-1
6-3
6-3
6-5
6-6
v
Managing Multiple Active BPEL Process Instances Using Correlation Methods .................... 6-7
WS-Addressing ........................................................................................................................... 6-7
Using Correlation Sets to Coordinate Asynchronous Message Body Contents ................ 6-9
Using the Reply Activity to Send Messages in Response to a Receive Activity ...................... 6-9
Using Dehydration Points to Maintain Long-Running Asynchronous Processes ................ 6-10
Calling an Asynchronous Service ...................................................................................................... 6-10
Step 1: Adding a Partner Link for an Asynchronous Service ................................................... 6-10
Step 2: Adding an Invoke Activity ............................................................................................... 6-11
Step 3: Adding a Receive Activity ................................................................................................ 6-13
Step 4: Performing Additional Activities..................................................................................... 6-14
Using Correlation Sets in an Asynchronous Service...................................................................... 6-14
Step 1: Creating a Project ............................................................................................................... 6-15
Step 2: Configuring Partner Links and File Adapter Services.................................................. 6-15
Creating an Initial Partner Link and File Adapter Service ................................................ 6-15
Creating a Second Partner Link and File Adapter Service ................................................ 6-17
Creating a Third Partner Link and File Adapter Service ................................................... 6-18
Step 3: Creating Three Receive Activities .................................................................................... 6-19
Creating an Initial Receive Activity ...................................................................................... 6-19
Creating a Second Receive Activity ...................................................................................... 6-20
Creating a Third Receive Activity ......................................................................................... 6-20
Step 4: Creating Correlation Sets .................................................................................................. 6-21
Creating an Initial Correlation Set......................................................................................... 6-21
Creating a Second Correlation Set......................................................................................... 6-21
Step 5: Associating Correlation Sets with Receive Activities ................................................... 6-22
Associating the First Correlation Set with a Receive Activity........................................... 6-22
Associating the Second Correlation Set with a Receive Activity ...................................... 6-23
Associating the Third Correlation Set with a Receive Activity......................................... 6-23
Step 6: Creating Property Aliases ................................................................................................. 6-24
Creating Property Aliases for NameCorr............................................................................. 6-24
Creating Property Aliases for IDCorr ................................................................................... 6-25
Step 7: Reviewing WSDL File Content......................................................................................... 6-25
Summary ................................................................................................................................................. 6-26
7
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 ....................................................................................................................................................
8
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 ....................................................................................................................................................
vi
7-1
7-1
7-2
7-4
7-7
7-8
8-1
8-1
8-2
8-4
8-5
9
Fault Handling
Use Case for Fault Handling .................................................................................................................. 9-1
Overview of Fault Handling Concepts ................................................................................................ 9-2
Defining a Fault Handler........................................................................................................................ 9-2
Types of BPEL Faults ............................................................................................................................... 9-4
Using the Scope Activity to Manage a Group of Activities ............................................................. 9-4
Throwing Internal Faults........................................................................................................................ 9-6
Returning External Faults ....................................................................................................................... 9-7
Returning a Fault in a Synchronous Interaction............................................................................ 9-7
Returning a Fault in an Asynchronous Interaction....................................................................... 9-7
Using a Fault Handler within a Scope ................................................................................................. 9-8
Using the Empty Activity to Insert No-Op Instructions into a Business Process..................... 9-8
Using Compensation after Undoing a Series of Operations ........................................................... 9-9
Using the Terminate Activity to Stop a Business Process Instance ............................................. 9-10
Catching Run-Time Faults Example .................................................................................................. 9-11
Eclipse BPEL Designer Example ........................................................................................................ 9-11
Summary ................................................................................................................................................. 9-15
10
Incorporating Java and J2EE Code in BPEL Processes
Use Case for Incorporating Java and J2EE Code 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 ...................................................................................................
Using Java Embedding in JDeveloper BPEL Designer..................................................................
Summary .................................................................................................................................................
11
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 in JDeveloper BPEL Designer........................................................................
Summary .................................................................................................................................................
12
10-1
10-1
10-2
10-2
10-2
10-3
10-4
10-5
10-6
10-7
11-1
11-1
11-2
11-4
11-4
11-4
11-6
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.............................
12-1
12-1
12-2
12-2
12-2
vii
Passing XML Messages through Java ...................................................................................
Invoking a Two-Way Operation through the Java API .....................................................
Invoking a One-Way Operation through 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 .................................................................................................................................................
13
12-3
12-3
12-4
12-5
12-6
12-6
12-7
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 ...............................................................................................................................................
13-1
13-2
13-3
13-4
13-5
13-6
13-7
13-8
13-9
13-10
13-11
Part III Oracle BPEL Process Manager Services
14
XSLT Mapper and Transformations
Use Case for Transformation...............................................................................................................
Creating a Transform Activity.............................................................................................................
The XSLT Mapper .................................................................................................................................
Notes on the Mapper ......................................................................................................................
Creating an XSL Map............................................................................................................................
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 ...............................................................................................................
viii
14-1
14-1
14-3
14-5
14-5
14-6
14-6
14-7
14-7
14-9
14-9
14-10
14-10
14-10
14-12
14-12
14-13
14-14
14-15
14-17
14-19
14-20
Ignoring Elements in the XSLT Document................................................................................
Replacing a Schema in the XSLT Mapper..................................................................................
Testing the Map ...................................................................................................................................
Test Window..................................................................................................................................
Generating Reports .......................................................................................................................
Correcting Memory Errors When Generating Reports ....................................................
Sample XML Generation ..............................................................................................................
Summary ...............................................................................................................................................
15
Oracle BPEL Process Manager Notification Service
Use Cases for Notification Service.....................................................................................................
Overview of Notification Service Concepts.....................................................................................
Configuring Notification Service in JDeveloper BPEL Designer................................................
The E-mail Notification Channel ..................................................................................................
Setting E-mail Attachments ....................................................................................................
Configuring the E-mail Server ...............................................................................................
Example ns_emails.xml File ...................................................................................................
The Voice Notification Channel ..................................................................................................
Configuring the Wireless Service Provider for Voice.......................................................
Example ns_iaswconfig.xml File .........................................................................................
The SMS Notification Channel....................................................................................................
Configuring the Wireless Service Provider for SMS.........................................................
The Fax Notification Channel......................................................................................................
Configuring the Fax Cover Page..........................................................................................
Configuring the Wireless Service Provider for Fax ..........................................................
The Pager Notification Channel..................................................................................................
Configuring the Wireless Service Provider for Pager.......................................................
Setting E-mail Addresses and Telephone Numbers Dynamically ........................................
Selecting Notification Recipients by Browsing the User Directory .......................................
Starting Business Processes with the E-mail Activation Agent..............................................
XML Validation Failure with the Notification Service ............................................................
Summary ...............................................................................................................................................
16
14-20
14-21
14-21
14-22
14-22
14-23
14-23
14-24
15-1
15-1
15-2
15-4
15-6
15-8
15-9
15-10
15-11
15-11
15-12
15-13
15-13
15-14
15-14
15-14
15-15
15-15
15-16
15-16
15-18
15-18
Oracle BPEL Process Manager Workflow Services
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 Flow Patterns ..................................................................................................
Escalation, Expiration, and Delegation ........................................................................................
The Worklist Application...............................................................................................................
Workflow Patterns.................................................................................................................................
The Modeling Process...................................................................................................................
Editing or Deleting a Workflow..................................................................................................
Task Details and Configurations ................................................................................................
16-1
16-3
16-4
16-6
16-6
16-7
16-7
16-8
16-8
16-10
16-11
16-11
ix
Task Attributes .......................................................................................................................
Task Outcomes .......................................................................................................................
Advanced Task Configurations ...........................................................................................
Task Assignment ...........................................................................................................................
Task Assignment Evaluation................................................................................................
Task Assignment Based on External Services....................................................................
Assigning a Task to a Specific User of a Role and Marking It As Acquired .................
Setting Task Assignees from a Dynamic Delimited String..............................................
Selecting Users or Groups by Browsing the User Directory ...........................................
Adding a Task Attachment from a Business Process ..............................................................
Actions Performed on a Task ......................................................................................................
XML Validation .............................................................................................................................
Simple Workflow ..........................................................................................................................
Use Case ..................................................................................................................................
Customizations for Simple Workflow ................................................................................
Simple Workflow with Automatic Escalation ..........................................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Simple Workflow with Automatic Escalation ................................
Simple Workflow with Automatic Renewal .............................................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Simple Workflow with Automatic Renewal ...................................
Sequential Workflow ....................................................................................................................
Use Cases.................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Sequential Workflow ..........................................................................
Sequential Workflow with Escalation ........................................................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Sequential Workflow with Escalation..............................................
Parallel Workflow .........................................................................................................................
Assigning Parallel Tasks to Each User in a Group............................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Parallel Workflow ...............................................................................
Parallel Workflow with Final Reviewer ....................................................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customizations for Parallel Workflow with Final Reviewer ..........................................
Adhoc Workflow...........................................................................................................................
Use Case ..................................................................................................................................
Customizations for Adhoc Workflow.................................................................................
FYI Tasks ........................................................................................................................................
Use Case ..................................................................................................................................
Customization for FYI Tasks ................................................................................................
The User Task 2.0 Macro ..............................................................................................................
x
16-11
16-13
16-14
16-19
16-20
16-21
16-21
16-22
16-23
16-26
16-29
16-31
16-31
16-32
16-32
16-33
16-35
16-35
16-36
16-37
16-39
16-39
16-39
16-40
16-43
16-43
16-45
16-47
16-48
16-48
16-48
16-49
16-51
16-51
16-52
16-52
16-52
16-53
16-53
16-54
16-54
16-55
16-55
16-56
16-56
16-56
16-57
Task Continuations .......................................................................................................................
Use Case ..................................................................................................................................
Pattern-Specific Parameters..................................................................................................
Customization for Task Continuations...............................................................................
Outcome-Based Modeling ...........................................................................................................
Payload Updates ....................................................................................................................
Case Statements for Other Task Conclusions ....................................................................
Task Notifications ...............................................................................................................................
Channels Used for Notification...................................................................................................
Notification Messages...................................................................................................................
E-mail Approval ............................................................................................................................
Reminders ......................................................................................................................................
Payload Display...................................................................................................................................
Autogenerated JSP ........................................................................................................................
Customizing the Autogenerated JSP...................................................................................
Customizing the Mapping File ............................................................................................
Customizing the Default JSP ................................................................................................
Multibyte Payload in the Task Detail JSP...........................................................................
Deploying the Autogenerated JSP ..............................................................................................
XSL ..................................................................................................................................................
The Custom JSP URL ....................................................................................................................
APIs ..........................................................................................................................................
Customizing the Complete Task JSP...................................................................................
Configuration for Task Service.........................................................................................................
Autorelease Duration ...................................................................................................................
Actionable E-mail Accounts ........................................................................................................
Worklist Application URL ...........................................................................................................
Identity Service ....................................................................................................................................
Identity Service Providers............................................................................................................
The JAZN Provider................................................................................................................
Third-Party LDAP Server .....................................................................................................
Custom User Repository Plug-ins .......................................................................................
Creating Users and Groups .........................................................................................................
User and Role Properties .............................................................................................................
Configuring Identity Service .......................................................................................................
Structure of the Identity Service Configuration File.........................................................
Configuration for the XML-Based JAZN Provider ...........................................................
Configuration for the LDAP-Based JAZN Provider (OID)..............................................
Configuration for a Third-Party LDAP Server ..................................................................
Configuration for CUSTOM User Repository Plug-ins....................................................
Creating a Custom Identity Service Plug-in..............................................................................
Requirements..........................................................................................................................
Description of Oracle BPEL Process Manager Interfaces.................................................
Implementing the Identity Service Plug-in ........................................................................
Deploying the Identity Service Plug-in ..............................................................................
Registering and Configuring Identity Service for the Custom Plug-in .........................
Creating Users and Groups ..................................................................................................
16-57
16-59
16-59
16-60
16-60
16-60
16-60
16-61
16-62
16-63
16-64
16-64
16-66
16-66
16-69
16-69
16-71
16-73
16-73
16-73
16-74
16-75
16-75
16-75
16-75
16-76
16-76
16-77
16-78
16-78
16-79
16-79
16-79
16-80
16-81
16-81
16-85
16-85
16-89
16-92
16-93
16-93
16-93
16-94
16-98
16-98
16-99
xi
Using the Plug-in with Installed Samples ..........................................................................
Workflow-Related XPath Extension Functions ...........................................................................
Approver Functions ..........................................................................................................................
Approver Function Syntax ........................................................................................................
Approver Function Examples ...................................................................................................
Vacation Request Example ..............................................................................................................
Prerequisites.................................................................................................................................
Getting Started: Modeling the Vacation Request Process .....................................................
Running the Example .................................................................................................................
Summary .............................................................................................................................................
17
16-99
16-100
16-105
16-105
16-107
16-108
16-108
16-109
16-115
16-116
Worklist Application
Use Cases for the Worklist Application ............................................................................................
Overview of Worklist Application Concepts...................................................................................
Logging In to the Worklist Application.......................................................................................
Features of the Sample Worklist Application .............................................................................
Task Actions............................................................................................................................
Routing ....................................................................................................................................
Requesting More Information..............................................................................................
Task History and Sequence (Version) Numbers ...............................................................
The Payload ............................................................................................................................
Comments ...............................................................................................................................
Attachments............................................................................................................................
Reassignment..........................................................................................................................
Parallel Tasks ..........................................................................................................................
Flex Fields and Task Fields Updates...................................................................................
Request Status.........................................................................................................................
Error Information...................................................................................................................
User and Group Information ...............................................................................................
Advanced Search ...................................................................................................................
Determining Action Permissions.........................................................................................
How Changes to a Workflow Appear in the Worklist Application ......................................
Accessing the Worklist Application in Local Languages ............................................................
Customizing the Worklist Application ...........................................................................................
Worklist Application Architecture .............................................................................................
Login Page...............................................................................................................................
Header Info .............................................................................................................................
Task Home (Listing) Page.....................................................................................................
Task Details Page ...................................................................................................................
Additional Pages ....................................................................................................................
Configuration Parameters ....................................................................................................
Controlling Access to Information and Actions for Different Users .....................................
Building a Worklist Application Using the Worklist Service APIs...........................................
Worklist Service APIs ...................................................................................................................
Example: Reassigning a Task in a Worklist Application.........................................................
Building a Worklist Application Using the Worklist Service Remote APIs............................
Summary ...............................................................................................................................................
xii
17-1
17-2
17-4
17-4
17-10
17-12
17-13
17-14
17-17
17-19
17-20
17-22
17-23
17-24
17-26
17-28
17-30
17-31
17-32
17-33
17-33
17-34
17-34
17-35
17-36
17-37
17-37
17-38
17-38
17-39
17-40
17-41
17-45
17-45
17-47
18
Sensors
Use Cases for Sensors ...........................................................................................................................
Overview of Sensor Concepts.............................................................................................................
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer ..............................
Configuring Sensors .......................................................................................................................
Configuring Sensor Actions...........................................................................................................
Creating a Custom Data Publisher ...............................................................................................
Registering the Sensors and Sensor Actions in bpel.xml ........................................................
Sensors and Oracle BPEL Console ...................................................................................................
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 ...........................................................................................................................
BPEL Reporting Schema ..............................................................................................................
Sensor Actions XSD File ....................................................................................................................
Summary ...............................................................................................................................................
Part IV
19
18-1
18-1
18-2
18-3
18-6
18-9
18-13
18-13
18-13
18-14
18-15
18-16
18-17
18-17
18-19
18-19
18-26
18-34
Development and Deployment Life Cycle
BPEL Process Deployment and Domain Management
Compiling and Deploying a BPEL Process ......................................................................................
Compiling and Deploying on JDeveloper BPEL Designer .......................................................
Compiling Without Deploying on JDeveloper BPEL Designer ........................................
Compiling and Deploying on Eclipse BPEL Designer ..............................................................
BPEL Suitcase JAR File ...................................................................................................................
Creating and Managing a BPEL Domain..........................................................................................
Changing the Default Domain Password....................................................................................
Changing Oracle BPEL Admin Console Password....................................................................
Creating a BPEL Domain ...............................................................................................................
Changing Oracle BPEL Server Mode ...........................................................................................
Deploying a BPEL Suitcase to a Specific Domain ......................................................................
Location of BPEL JAR Suitcase Files in a Specific Domain .....................................................
Undeploying a BPEL Process from a Specific Domain............................................................
Viewing BPEL Processes in Oracle BPEL Console .......................................................................
Dashboard Tab: Viewing Processes............................................................................................
BPEL Processes Tab: Managing the Process Life Cycle...........................................................
Process Life Cycle Recommendations for a Development Environment ......................
Process Life Cycle Recommendations for a Production Environment ..........................
Example: Life Cycle of Processes.........................................................................................
Instances Tab: Viewing Process Instances .................................................................................
Activities Tab: Viewing Process Activities ................................................................................
Build and Command Line Tools.......................................................................................................
Apache Ant ....................................................................................................................................
19-1
19-2
19-4
19-5
19-6
19-7
19-7
19-7
19-8
19-8
19-9
19-10
19-10
19-11
19-11
19-12
19-14
19-14
19-15
19-19
19-20
19-21
19-21
xiii
bpelc ................................................................................................................................................
Examples .................................................................................................................................
schemac...........................................................................................................................................
Examples .................................................................................................................................
Summary ...............................................................................................................................................
20
Oracle BPEL Portlets
OracleAS Portal Introduction .............................................................................................................
Step 1: Installing the Required Oracle Application Server Components ..................................
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 Console Report Portlet Parameters and Accessing Portlet Data
Sources ..............................................................................................................................................
Instance State ..........................................................................................................................
Instance Execution Time .......................................................................................................
Performance............................................................................................................................
Activity Sensor .......................................................................................................................
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 ...............................................................................................................................................
21
20-1
20-3
20-3
20-3
20-4
20-5
20-8
20-9
20-10
20-10
20-11
20-12
20-12
20-12
20-13
20-15
20-16
20-18
20-19
20-22
Oracle BPEL Console Reports
Creating Oracle BPEL Console Reports ............................................................................................
Creating Process Reports ...............................................................................................................
Creating Performance Reports ......................................................................................................
Creating Activity Sensor Reports .................................................................................................
Creating Fault Sensor Reports.......................................................................................................
Creating Process Time Distribution Reports.............................................................................
Summary ...............................................................................................................................................
Part V
A
19-22
19-22
19-23
19-24
19-24
21-1
21-3
21-5
21-7
21-9
21-10
21-11
Reference Information
Troubleshooting and Workarounds
Troubleshooting General Issues........................................................................................................... A-1
Correcting Validation Errors in Complex Processes.................................................................... A-1
Handling Long-Running Processes................................................................................................ A-1
xiv
Creating an Empty BPEL Process and Importing a Schema.......................................................
Troubleshooting Sensors—The Custom Data Publisher.................................................................
Poor JMS Performance When Creating or Destroying Connections .........................................
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 ...................................................................................................................................................
B
Workflow and Notification Reference
Task Manager Service WSDL Operations ..........................................................................................
Task Routing Service WSDL Operations............................................................................................
Notification WSDL Operations ............................................................................................................
Identify Service Operations ..................................................................................................................
Task Action Handler Business Process ...............................................................................................
Summary ...................................................................................................................................................
C
A-2
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
B-1
B-2
B-2
B-3
B-3
B-3
JDeveloper BPEL Designer Activities
Validating when Loading a Process Diagram....................................................................................
Activities Overview ................................................................................................................................
Tabs Common to Many Activities ..................................................................................................
Assign Activity ..................................................................................................................................
Catch Activity ....................................................................................................................................
Compensate Activity ........................................................................................................................
Empty Activity ..................................................................................................................................
Flow Activity .....................................................................................................................................
FlowN Activity ..................................................................................................................................
Invoke Activity ..................................................................................................................................
Java Embedding Activity ...............................................................................................................
Notification Activity .......................................................................................................................
PartnerLink Activity .......................................................................................................................
Pick Activity.....................................................................................................................................
Receive Activity...............................................................................................................................
Reply Activity ..................................................................................................................................
Scope Activity ..................................................................................................................................
Sequence Activity............................................................................................................................
Switch Activity ................................................................................................................................
Terminate Activity ..........................................................................................................................
Throw Activity ................................................................................................................................
C-1
C-2
C-3
C-3
C-4
C-5
C-6
C-7
C-8
C-9
C-10
C-11
C-12
C-13
C-14
C-15
C-16
C-17
C-18
C-19
C-19
xv
Transform Activity..........................................................................................................................
User Task ..........................................................................................................................................
Wait Activity....................................................................................................................................
While Activity..................................................................................................................................
Summary .................................................................................................................................................
D
User Task 2.0 Macro
Introduction to User Task 2.0 Macro....................................................................................................
BPEL User Task Use Case ......................................................................................................................
The TaskManager Service......................................................................................................................
Integrating the TaskManager Service into a BPEL Process.........................................................
Defining a Partner Link for the TaskManager Service .........................................................
Declare and Initialize the Task Document .............................................................................
Initiate the Task ..........................................................................................................................
Task Completion ........................................................................................................................
Using Eclipse BPEL Designer to Integrate the TaskManager Service .......................................
Creating a User Interface for the Task..........................................................................................
List the Assigned Tasks...........................................................................................................
Display the Payload Data for a Task.....................................................................................
Update the Payload Data and Complete the Task ..............................................................
Additional Capabilities of the TaskManager Service ....................................................................
Enabling Expiration/Timeouts for Tasks ....................................................................................
Sending Notifications ..............................................................................................................
Reassigning Tasks ....................................................................................................................
Assigning Tasks to Groups and Resolving Roles................................................................
Summary .................................................................................................................................................
E
E-1
E-1
E-2
E-3
E-3
E-4
E-4
E-4
E-8
Demo User Community
Setting Up JAZN Demo Users ..............................................................................................................
Demo Users and Roles......................................................................................................................
Using the Demo User Community in the Order Booking Tutorial ...........................................
Summary ...................................................................................................................................................
G
D-1
D-1
D-2
D-5
D-5
D-6
D-6
D-7
D-7
D-11
D-11
D-13
D-14
D-15
D-15
D-16
D-17
D-17
D-17
Deployment Descriptor Properties
Deployment Descriptor Preference Properties..................................................................................
Defining a Preference Property.......................................................................................................
Updating a Preference at Run Time ...............................................................................................
Getting the Value of a Preference within a BPEL Process...........................................................
Encrypting a Preference Value........................................................................................................
Use Case for Preference Properties.................................................................................................
Deployment Descriptor Configuration Properties ...........................................................................
Defining a Configuration Property ................................................................................................
Summary ...................................................................................................................................................
F
C-20
C-21
C-22
C-23
C-24
F-1
F-1
F-4
F-5
XPath Extension Functions
XPath Extension Functions Available to BPEL Processes................................................................ G-1
xvi
abs........................................................................................................................................................ G-1
add-dayTimeDuration-to-dateTime............................................................................................... G-1
addChildNode ................................................................................................................................... G-2
addQuotes .......................................................................................................................................... G-2
appendToList ..................................................................................................................................... G-3
authenticate ........................................................................................................................................ G-3
batchProcessActive ........................................................................................................................... G-3
batchProcessCompleted ................................................................................................................... G-4
clearTaskAssignees ........................................................................................................................... G-4
compare .............................................................................................................................................. G-4
compare-ignore-case......................................................................................................................... G-5
copyList .............................................................................................................................................. G-5
countNodes ........................................................................................................................................ G-6
create-delimited-string ..................................................................................................................... G-6
create-nodeset-from-deliminated-string........................................................................................ G-6
createDeliminatedString .................................................................................................................. G-7
current-date........................................................................................................................................ G-7
current-dateTime............................................................................................................................... G-8
current-time........................................................................................................................................ G-8
day-from-dateTime ........................................................................................................................... G-8
doc ....................................................................................................................................................... G-8
ends-with............................................................................................................................................ G-9
format.................................................................................................................................................. G-9
format-dateTime................................................................................................................................ G-9
format-string .................................................................................................................................... G-10
formatDate ....................................................................................................................................... G-10
genEmptyElem ................................................................................................................................ G-10
generate-guid ................................................................................................................................... G-11
generateGUID .................................................................................................................................. G-11
get-content-as-string ....................................................................................................................... G-11
get-localized-string ......................................................................................................................... G-12
getChildElement.............................................................................................................................. G-12
getContentAsString......................................................................................................................... G-13
getConversationId........................................................................................................................... G-13
getCreator......................................................................................................................................... G-13
getCurrentDate ................................................................................................................................ G-13
getCurrentDateTime....................................................................................................................... G-14
getCurrentTime ............................................................................................................................... G-14
getDomainId .................................................................................................................................... G-14
getElement........................................................................................................................................ G-14
getGroupIdsFromGroupAlias....................................................................................................... G-15
getGroupProperty ........................................................................................................................... G-15
getInstanceId.................................................................................................................................... G-15
getLinkStatus ................................................................................................................................... G-16
getManager ...................................................................................................................................... G-16
getMessage ....................................................................................................................................... G-16
getNodeValue .................................................................................................................................. G-17
xvii
getNodes...........................................................................................................................................
getNumberOfTaskApprovals........................................................................................................
getPreference....................................................................................................................................
getPreviousTaskApprover.............................................................................................................
getProcessId .....................................................................................................................................
getProcessOwnerId.........................................................................................................................
getProcessURL.................................................................................................................................
getProcessVersion ...........................................................................................................................
getReportees.....................................................................................................................................
getTaskAttachmentByIndex ..........................................................................................................
getTaskAttachmentByName..........................................................................................................
getTaskAttachmentContents .........................................................................................................
getTaskAttachmentsCount ............................................................................................................
getTaskAutoReleaseDuration........................................................................................................
getTaskReminderDuration ............................................................................................................
getUserAliasId .................................................................................................................................
getUserIdsFromGroupAlias ..........................................................................................................
getUserProperty ..............................................................................................................................
getUserRoles ....................................................................................................................................
getUsersInGroup .............................................................................................................................
getVariableData ...............................................................................................................................
getVariableProperty........................................................................................................................
hours-from-dateTime .....................................................................................................................
implicit-timezone ............................................................................................................................
index-within-string .........................................................................................................................
integer ...............................................................................................................................................
isUserInRole .....................................................................................................................................
last-index-within-string..................................................................................................................
lookupUser.......................................................................................................................................
left-trim .............................................................................................................................................
listUsers ............................................................................................................................................
lookup-table .....................................................................................................................................
lookup-xml .......................................................................................................................................
lookupUser.......................................................................................................................................
lookupGroup ...................................................................................................................................
lower-case.........................................................................................................................................
matches .............................................................................................................................................
max-value-among-nodeset ............................................................................................................
mergeChildNodes ...........................................................................................................................
min-value-among-nodeset.............................................................................................................
minutes-from-dateTime .................................................................................................................
month-from-dateTime ....................................................................................................................
parseEscapedXML...........................................................................................................................
processXSLT.....................................................................................................................................
processXSLT.....................................................................................................................................
processXSQL ....................................................................................................................................
query-database ................................................................................................................................
xviii
G-17
G-17
G-17
G-18
G-18
G-18
G-18
G-19
G-19
G-19
G-19
G-20
G-20
G-20
G-21
G-21
G-21
G-21
G-22
G-23
G-23
G-23
G-24
G-24
G-24
G-25
G-25
G-25
G-26
G-26
G-27
G-27
G-28
G-28
G-28
G-29
G-29
G-29
G-30
G-30
G-31
G-31
G-31
G-31
G-32
G-32
G-33
readFile .............................................................................................................................................
right-trim ..........................................................................................................................................
search ................................................................................................................................................
seconds-from-dateTime..................................................................................................................
sequence-next-val............................................................................................................................
setNodeValue...................................................................................................................................
square-root .......................................................................................................................................
subtract-dayTimeDuration-from-dateTime ................................................................................
timezone-from-dateTime ...............................................................................................................
translateFromNative.......................................................................................................................
translateToNative............................................................................................................................
upper-case ........................................................................................................................................
year-from-dateTime ........................................................................................................................
Summary .................................................................................................................................................
G-33
G-33
G-34
G-34
G-34
G-35
G-35
G-36
G-36
G-36
G-37
G-37
G-37
G-38
H Oracle BPEL Process Manager and Oracle Workflow Integration
Use Cases for Oracle Workflow Bridge...............................................................................................
Introduction to Oracle Workflow Bridge............................................................................................
Locating Oracle Workflow Databases .................................................................................................
Installing Oracle Workflow Bridge......................................................................................................
Designing a BPEL Process to Interact with Oracle Workflow Bridge...........................................
Creating an Oracle Workflow Partner Link ..................................................................................
Creating Invoke and Receive Activities.........................................................................................
Creating an Assign Activity with Multiple Statements...............................................................
Correlating the Actions of the Invoke and Receive Activities..................................................
Monitoring Oracle Workflow Processes ...........................................................................................
Summary .................................................................................................................................................
H-1
H-2
H-3
H-3
H-4
H-5
H-6
H-7
H-11
H-14
H-14
Index
xix
xx
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.
xxi
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 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:
xxii
Convention
Meaning
boldface
Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
Convention
Meaning
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.
xxiii
xxiv
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"
■
Chapter 3, "Building a Simple BPEL Process"
1
Introduction to
Oracle BPEL Process Manager
This chapter provides a brief introduction to the Business Process Execution Language
(BPEL), how Oracle BPEL Process Manager supports BPEL, and the types of BPEL
designers available with Oracle BPEL Process Manager that enable you to design BPEL
processes (JDeveloper BPEL Designer and Eclipse BPEL Designer). 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 the BPEL Designer?
■
How to Use This Guide
■
■
Getting Started with Demonstrations, Activity and Conceptual References, and
Tutorials
Summary
Note: 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.
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 4, "Manipulating XML Data in BPEL" through
Chapter 13, "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 JDeveloper BPEL Designer:
■
■
■
Transformations, workflows, worklists, notifications, and sensors
Technology adapters (file, FTP, database, advanced queuing (AQ), Java Messaging
Service (JMS), 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 Workflow, Oracle Application
Server Integration B2B, and Oracle Application Server Integration InterConnect.
1-2
Oracle BPEL Process Manager Developer’s Guide
What Is the BPEL Designer?
See Also:
■
■
■
■
■
■
■
"Sensor Integration with Oracle Business Activity Monitoring" on
page 18-15 for details about integrating Oracle BPEL Process
Manager with Oracle Business Activity Monitoring
Chapter 20, "Oracle BPEL Portlets" for details about integrating
Oracle BPEL Process Manager with OracleAS Portal
Appendix H, "Oracle BPEL Process Manager and
Oracle Workflow Integration" for details about integrating Oracle
BPEL Process Manager with Oracle Workflow
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 with 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 technology adapters
■
Oracle Application Server Adapter for Oracle Applications User’s Guide
■
Oracle Application Server Adapter Concepts
■
■
Oracle Application Server Integration 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 the BPEL Designer?
Oracle BPEL Process Manager provides support for two types of BPEL designer
environments for graphically designing BPEL processes:
■
JDeveloper BPEL Designer
■
Eclipse BPEL Designer
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 use wizards to integrate adapters and services such as workflows,
transformations, notifications, sensors, and worklist task management with the
process. Both BPEL designers can deploy the developed processes directly to Oracle
BPEL Console. This facilitates the development and maintenance of BPEL processes.
JDeveloper BPEL Designer
JDeveloper BPEL Designer is integrated with Oracle JDeveloper. 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
Introduction to Oracle BPEL Process Manager 1-3
What Is the BPEL Designer?
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.
JDeveloper BPEL Designer uses BPEL as its native format. This means that processes
built with JDeveloper BPEL Designer are 100% portable. JDeveloper BPEL Designer
also enables you to view and modify the BPEL source without decreasing the
usefulness of the tool.
Oracle BPEL Process Manager provides support for the following services and
adapters in JDeveloper BPEL Designer:
■
Transformations, workflows, worklists, notifications, and sensors
■
Technology adapters (file, FTP, database, AQ, JMS, and Oracle Applications)
Figure 1–1 shows JDeveloper BPEL Designer with a BPEL process being designed.
Figure 1–1 JDeveloper BPEL Designer
See Also:
■
■
■
1-4
"Overview of JDeveloper BPEL Designer" on page 2-3 for a
description of the sections of JDeveloper BPEL Designer shown in
Figure 1–1
Oracle BPEL Process Manager Quick Start Guide and Oracle BPEL
Process Manager Order Booking Tutorial for tutorials that use
JDeveloper BPEL Designer
Online Help available from the Help main menu for additional
details about Oracle JDeveloper
Oracle BPEL Process Manager Developer’s Guide
What Is the BPEL Designer?
Eclipse BPEL Designer
Eclipse BPEL Designer is integrated with the Eclipse platform. Eclipse is designed for
building integrated development environments (IDEs) to create applications such as
Web sites, embedded Java programs, C++ programs, and Enterprise JavaBeans. Eclipse
provides you with mechanisms to use and rules to follow that lead to seamlessly
integrated tools. These mechanisms are exposed through API interfaces, classes, and
methods. Eclipse also provides useful building blocks and frameworks that facilitate
developing new tools.
Eclipse BPEL Designer is a plug-in for the Eclipse 3.0 platform. Eclipse BPEL Designer
uses standard BPEL, meaning that processes you design can be used with other BPEL
servers (and vice versa).
The JDeveloper BPEL Designer services and adapters described in "JDeveloper BPEL
Designer" on page 1-3 are not currently available on Eclipse BPEL Designer.
Figure 1–2 shows Eclipse BPEL Designer with a BPEL process being designed.
Figure 1–2 Eclipse BPEL Designer
Notes: Throughout this guide, the Eclipse BPEL Designer
installation directory is referred to as c:\orabpel. If you have
installed Eclipse BPEL Designer into a different directory, make the
appropriate substitution throughout this guide.
Introduction to Oracle BPEL Process Manager 1-5
How to Use This Guide
See Also:
■
■
■
■
"Overview of Eclipse BPEL Designer" on page 2-13 for a
description of the sections of Eclipse BPEL Designer shown in
Figure 1–2
Chapter 3, "Building a Simple BPEL Process" for a tutorial that
enables you to design and deploy a simple Hello World BPEL
process
http://www.eclipse.org for specific details about Eclipse
http://www.oracle.com/technology/bpel for software
download instructions and for details about running Oracle BPEL
Process Manager and Eclipse BPEL Designer on Eclipse (including
tutorials)
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.
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:
■
■
■
■
■
■
1-6
BPEL specifications, Oracle BPEL Process Manager, and
BPEL designers (JDeveloper BPEL Designer and Eclipse
BPEL Designer)
Starting and stopping key Oracle BPEL Process Manager
components
Demonstrations, tutorials, and activity and conceptual
references provided with Oracle BPEL Process Manager
An introduction to JDeveloper BPEL Designer and Eclipse
BPEL Designer, 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 Console for running deployed BPEL processes
A Hello World BPEL process that you can design and
deploy in both JDeveloper BPEL Designer and Eclipse BPEL
Designer
Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–1 (Cont.) Developer’s Guide Contents
Part
Description
Part II, "Reviewing Key
BPEL Development
Concepts and Code
Samples"
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:
Part III, "Oracle BPEL
Process Manager Services"
■
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
Part IV, "Development and
Deployment Life Cycle"
Chapters in this part describe how to run and manage deployed
BPEL processes from Oracle BPEL Console, 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, user accounts, XPath
expression functions, Oracle Workflow support, and other
features.
See Also:
■
■
■
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide for specific details about configuring the file, FTP,
database, AQ, 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
Introduction to Oracle BPEL Process Manager 1-7
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
BPEL Process Manager. These materials are installed with Oracle BPEL Process
Manager in the Oracle_Home\integration\orabpel\samples directory for
JDeveloper BPEL Designer and the c:\orabpel\samples directory for Eclipse BPEL
Designer.
Table 1–2 describes the contents of the samples directory. If you are using JDeveloper
BPEL Designer, you can also access details about this directory from the Start Menu by
selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL
Process Manager 10.1.2, and then Getting Started with Samples.
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-8 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:
■
Microsoft .Net
■
Apache Axis
■
BEA WebLogic
references
Contains a BPEL project for activities and concepts defined in the BPEL
language. Table 1–4 on page 1-11 provides descriptions of the available
activities and concepts.
tutorials
Contains a set of BPEL processes targeting the various BPEL tasks to which
you are exposed. Table 1–5 on page 1-12 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. You can also click the .jpr files in these directories to
automatically create the demonstrations.
Table 1–3
1-8
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.
Oracle BPEL Process Manager Developer’s Guide
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–3 (Cont.) demos Directory Contents
Directory
Description
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
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 parallel reviewers. A worklist application views and acts on
the tasks. This example highlights the use of the following features:
■
■
Modeling parallel workflow with final reviewer in the
JDeveloper BPEL Designer environment.
Using Oracle BPEL Worklist Application to view and act on
tasks.
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 a workflow 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. Parts of
this demonstration also appear in the Oracle BPEL Process Manager
Quick Start Guide.
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
LoanDemoPlusWithWo
rkflow
Describes how to extend the LoanDemo sample to use a worklist
application to approve or reject a loan application
OrderApproval
Describes how to approve or reject an order. The approval or
rejection is a two-step process involving an initial approver and the
manager of the initial approver. OrderApproval also illustrates the
use of workflow for multiple approvals.
OWFBridge
Describes how to invoke and receive a response from an Oracle
Workflow process.
Introduction to Oracle BPEL Process Manager 1-9
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
Table 1–3 (Cont.) demos Directory Contents
Directory
Description
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.
PaymentProcessor
Describes how to use the following key concepts and features:
■
■
Use a pick activity to control a process flow based on the
outcome of another process (including a timeout for the
process).
Modify a process so that a parameter can be updated at run
time without having to redeploy it.
This process also illustrates the use of workflow for simple
approvals, and the use of a deployment descriptor preference to
replace a hard-coded value in the BPEL logic.
PriorityDemo
Describes how to invoke a service n times using a While loop
activity. This sample illustrates the ability of the process priorities.
Oracle BPEL Server uses the priorities for scheduling work such
that higher priority processes get executed in advance of lower
priority processes when there is contention for engine execution
threads.
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.
TimeOffRequestDemo
Describes how to design user interactions and workflow tasks
within a BPEL process. This sample illustrates use of the User Task
and e-mail notification service.
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-10
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
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.
XPathFunction
Shows how to define and use custom XPath functions within BPEL
assign activities
Introduction to Oracle BPEL Process Manager 1-11
Getting Started with Demonstrations, Activity and Conceptual References, and Tutorials
See Also:
Chapter 4, "Manipulating XML Data in BPEL" through
Chapter 13, "Interaction Patterns" for activity development
concepts and code samples
■
Appendix C, "JDeveloper BPEL Designer Activities" for specific
details about activities that you drag and drop in the BPEL
designer
■
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. You can also click the .jpr files in these directories to automatically create
the tutorials.
Table 1–5
1-12
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.InvokingProces
ses
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.SyncQuoteConsu
mer
This sample shows how to use the invoke activity to invoke a
synchronous stock quote service.
105.AsyncComposite
LoanBroker
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.CorrelationSet
s
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.
110.UserTasks
This sample shows how to integrate a user task within a process.
111.CallingSession
Beans
This sample shows how to use the BPEL exec extension to invoke a
session bean from within a BPEL process.
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 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.
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.XSLTTransforma
tions
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.CorrelatedHell
oWorld
This sample illustrates how to use correlations.
116.SendEmails
This sample shows how to send an e-mail in a BPEL process.
117.ReceiveEmails
This sample shows how to receive an e-mail in a BPEL process.
118.JMSService
This sample shows how to use Java Message Service (JMS) to select
a JMS buyer process at Oracle BPEL Console and initiate a buyer
flow. This sends a JMS message that is retrieved by a listener that
outputs a message and sends a JMS response to the seller.
119.JMSTopics
This sample provides JMS samples for use with JBoss, OC4J, and
BEA WebLogic.
120.XSQLExecution
This sample shows how to execute XSQL.
121.FileAdapter
These samples show how to use the file adapter. The following
tutorials are provided:
■
COBOL Copybook
■
Complex structures
■
Debatching
■
Flat structure
■
Opaque with headers
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
122.DBAdapter
The following samples show how to use the database adapter:
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
■
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 is inserted
into the database as relational data.
InsertWithCatch—Adds fault handling to an insert operation.
JPublisherWrapper—JPublisher creates a corresponding
OBJECT type whose attributes match the fields of the PL/SQL
RECORD and conversion APIs that convert from RECORD to
OBJECT, and vice versa.
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 been already 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 runtime to filter out
processed rows.
PureSQLPolling—Polls a table based on a date field.
PureSQLSelect—Bypasses JDeveloper BPEL Designer’s WHERE
clause to specify arbitrarily complex SQL strings.
QueryByExample—An outbound query-by-example operation.
ResultSetConverter—A workaround for use with REF
CURSORs.
SelectAll—An outbound Select All operation.
SelectAllByTitle—An outbound Select All By Title
operation.
Update—A record is passed to the operation and the database
row with the same primary key is updated.
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
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
1-14
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
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.
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.
See Also: Oracle Adapters for Files, FTP, Databases, and Enterprise
Messaging User’s Guide
125.ReportsSchema
This sample shows how to build custom reports using the BPEL
Process Manager reports schema.
126.DataAggregator
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.OrderBookingTu
torial
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.
Introduction to Oracle BPEL Process Manager 1-15
Summary
Table 1–5 (Cont.) tutorials Directory Contents
Directory
Description
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
This debatching 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.
130.SendEmailWithA
ttachments
This sample shows how to send an e-mail with attachments through
the Notification Service wizard.
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.SecureInvoking
Processes
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
701.LargeProcesses
This sample shows how support is provided for processes with a
large number of work items (10,000 or more).
702.Bindings
This sample shows how to:
■
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
See Also: 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
the types of BPEL designers available with Oracle BPEL Process Manager that enable
you to design BPEL processes (JDeveloper BPEL Designer and Eclipse BPEL
Designer). 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.
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 JDeveloper BPEL Designer, Eclipse BPEL Designer, Oracle BPEL Server, and
Oracle BPEL Console. An overview of the main sections of JDeveloper BPEL Designer
and Eclipse BPEL Designer 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 BPEL Designer Environments
■
Overview of Activities
■
Overview of Partner Links
■
Overview of Oracle BPEL Server
■
Overview of Oracle BPEL Console
■
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.
Getting Started with Oracle BPEL Process Manager 2-1
Starting Oracle BPEL Process Manager Components
Figure 2–1 Oracle BPEL Process Manager Components
Design
Deployment
Management
BPEL
Server
Oracle
BPEL
Console
JDeveloper
BPEL
Designer
Designer
Eclipse
BPEL
Designer
Each component enables you to perform a specific set of tasks:
■
■
■
The design environment (JDeveloper BPEL Designer or Eclipse BPEL Designer)
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 use wizards to integrate
technology adapters and services such as workflows, worklists, transformations,
notifications, and sensors 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 Console.
This chapter provides an overview of getting started with these components.
Starting Oracle BPEL Process Manager Components
As described in Chapter 1, "Introduction to Oracle BPEL Process Manager", Oracle
BPEL Process Manager provides support for two types of BPEL designer
environments for graphically designing and deploying BPEL processes:
■
JDeveloper BPEL Designer
■
Eclipse BPEL Designer
Follow these instructions to start Oracle BPEL Process Manager components on
JDeveloper BPEL Designer and Eclipse BPEL Designer.
2-2
1.
Select Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL
Process Manager version_number, and then Start BPEL PM Server to start Oracle
BPEL Server, which enables you to use the BPEL designer.
2.
For JDeveloper BPEL Designer only, select Start, then All Programs, then Oracle Oracle_Home, then Oracle BPEL Process Manager version_number, and then
JDeveloper BPEL Designer. The designer enables you to design and deploy BPEL
processes graphically.
3.
For Eclipse BPEL Designer only, select Start, then All Programs, then Oracle Oracle_Home, then Oracle BPEL Process Manager version_number, and then
BPEL Designer. The designer enables you to design and deploy BPEL processes
graphically.
4.
Select Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL
Process Manager version_number, and then Developer Prompt to open up a
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
command prompt at the Oracle_Home\integration\orabpel\samples
directory. This enables you to access tutorials, demonstrations, and reference
materials and start any required tutorial Web services.
5.
Select Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL
Process Manager version_number, and then BPEL Console to start Oracle BPEL
Console from which to run, monitor, and administer BPEL processes.
6.
For JDeveloper BPEL Designer only, select Start, then All Programs, then Oracle Oracle_Home, then Oracle BPEL Process Manager 10.1.2, and then Sample
Worklist Application to start the sample Oracle BPEL Worklist Application.
7.
For JDeveloper BPEL Designer only, select Start, then All Programs, then Oracle Oracle_Home, then Oracle BPEL Process Manager 10.1.2, and then Getting
Started with Samples for an overview of available tutorials, demonstrations, and
reference materials in the Oracle_Home\integration\orabpel\samples
directory.
Note: The version number that appears after Oracle BPEL Process
Manager in the Start Menu sequence is determined by whether you
are using JDeveloper BPEL Designer or Eclipse BPEL Designer.
See Also:
■
■
http://www.oracle.com/technology/bpel for software
download instructions and for details about running Oracle BPEL
Process Manager and Eclipse BPEL Designer on Eclipse (including
tutorials)
Oracle BPEL Process Manager Quick Start Guide for instructions on
starting Oracle BPEL Process Manager components on UNIX
operating systems.
Overview of BPEL Designer Environments
This section provides an overview of the two types of BPEL designer environments for
which Oracle BPEL Process Manager provides support:
■
Overview of JDeveloper BPEL Designer
■
Overview of Eclipse BPEL Designer
Notes: Always use completely unique names when creating BPEL
projects. Do not create:
■
A project name that begins with a number
■
Two projects with the same name, but with different capitalization
Overview of JDeveloper BPEL Designer
This section provides an overview of JDeveloper BPEL Designer. In this overview, you
first create a workspace and a project. A workspace is a container in which to place
projects. A project contains the BPEL process.
Getting Started with Oracle BPEL Process Manager 2-3
Overview of BPEL Designer Environments
1.
Create a workspace by selecting File, then New, and then Application Workspace
and providing the required details in the Create Application Workspace window
(including selecting not to add a new empty project).
2.
Right-click the newly created workspace and select New Project.
3.
Double-click BPEL Process Project and provide the required details (including
BPEL process name) in the BPEL Process Project window. A single project can
contain only one BPEL process.
Note: You can also import existing projects into JDeveloper BPEL
Designer by selecting Import, then BPEL Process from the File main
menu.
After you create the workspace and project, JDeveloper BPEL Designer displays the
sections shown in Figure 2–2. You can also access this view by selecting View, and
then Applications 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 JDeveloper BPEL Designer Sections
Each section of this view enables you to perform specific design and deployment
tasks. Table 2–1 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 BPEL Designer Environments
Table 2–1
JDeveloper BPEL Designer Sections
Section
Location in Figure 2–2
See Section
Applications Navigator
Upper left
"Applications Navigator" on
page 2-5
Diagram View window and
Source window
Middle
"Diagram View Window" on
page 2-6 and "Source Window"
on page 2-8
Process Activities selection of Upper right
the Component Palette
"Component Palette" on page 2-9
Property Inspector section
Lower right
"Property Inspector" on
page 2-10
Structure Window
Lower left
"Structure Window" on page 2-11
Log Window
Bottom
"Log Window" on page 2-12
See Also: Oracle BPEL Process Manager Quick Start Guide and Oracle
BPEL Process Manager Order Booking Tutorial for tutorials in which you
create workspaces and projects
Applications 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 FulfillOrder 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 JDeveloper BPEL Designer (in this example, named
FulfillOrder inside a workspace named OrderBookworkspace).
Figure 2–3 Applications Navigator
Table 2–2 describes these initial project files.
Table 2–2
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 E, "Deployment Descriptor Properties"
Getting Started with Oracle BPEL Process Manager 2-5
Overview of BPEL Designer Environments
Table 2–2 (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
Applications Navigator. For example, Figure 2–4 shows the files that appear for a
project in which you imported a schema (OrderBookingPO.xsd), configured the
database adapter (under the Application Sources node), and created a transform
activity (Transformation_1.xsl under the Miscellaneous Files folder of the Web
Content node). 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 Applications Navigator (Expanded)
Note: If you want to learn more about the Application Navigator,
place the cursor in this section and press F1 to display online Help.
Diagram View Window
The Diagram View 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:
■
■
2-6
Double-click the .bpel file name in the Applications Navigator
Click the Diagram View tab at the bottom of the window with the .bpel file
selected
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
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
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 View (After Creation of an Asynchronous Project)
As you design the project by dragging and dropping activities, creating partner links,
and so on, the Diagram View changes. Figure 2–6 shows the Diagram View later in
the design phase after adding a partner link (in this example, named DBInsert) and
the necessary activities (invoke, receive, assign, transform, and others).
Getting Started with Oracle BPEL Process Manager 2-7
Overview of BPEL Designer Environments
Figure 2–6 Diagram View (After Design Phase)
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 CreditRatingService partner link icon and property sheet that
have just been created.
Figure 2–7 CreditRatingService Partner Link Icon and Property Sheet
2-8
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
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.
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 4, "Manipulating XML Data in BPEL" through
Chapter 13, "Interaction Patterns"
Oracle_Home\integration\orabpel\samples directory
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 View of the BPEL process. The
Component Palette displays only those pages relevant to the state of the Diagram
View. Process Activities is 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–9 shows the Process Activities selection of the Component Palette.
Getting Started with Oracle BPEL Process Manager 2-9
Overview of BPEL Designer Environments
Figure 2–9 Component Palette - Process Activities
Figure 2–10 shows the String Functions category of the Component Palette that
displays when you work in the transformation window of a transform activity.
Figure 2–10
Component Palette - Functions
Note: If you want to learn more about the Component Palette, place
the cursor in this section and press F1 to display online Help.
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 View. For
example, single-clicking the receiveInput receive activity shown in Figure 2–2 on
page 2-4 displays the information shown in Figure 2–11.
2-10
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
Figure 2–11
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 View. 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
View
Figure 2–12 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 View for the FulfillOrder project shown in Figure 2–6 on page 2-8.
Figure 2–12
Structure Window (Expanded)
Getting Started with Oracle BPEL Process Manager 2-11
Overview of BPEL Designer Environments
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
Applications 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–13 shows a successful deployment message for a BPEL process. You can then
run, monitor, and administer the process from Oracle BPEL Console.
Figure 2–13
Successful Deployment Message
If deployment is unsuccessful, messages appear that describe the type and location of
the error, as shown in Figure 2–14. Double-click the error to navigate directly to the
offending line in the source file referenced.
Figure 2–14
2-12
Unsuccessful Deployment Message
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
Note: If you want to learn more about the Log Window, place the
cursor in this section and press F1 to display online Help.
See Also:
■
■
"Overview of Oracle BPEL Console" on page 2-21
Chapter 19, "BPEL Process Deployment and
Domain Management" for specific details about deploying and
running BPEL processes
Editing Project Files in JDeveloper BPEL Designer
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 JDeveloper BPEL
Designer and a text editor such as Notepad or Wordpad. Use only a single editing
environment such as JDeveloper BPEL Designer.
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 JDeveloper BPEL Designer.
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.
Overview of Eclipse BPEL Designer
This section provides an overview of Eclipse BPEL Designer. Eclipse BPEL Designer is
similar to JDeveloper BPEL Designer. Differences between the two BPEL designers are
described. In this overview, you first create a project for the BPEL process.
1.
Select File, then New, and then Project to display the New Project window.
2.
Select Oracle BPEL Project (the default selection) and click Next to display the
Create a BPEL Project window.
3.
Provide the required details (including BPEL process name) and click Finish. A
single project can contain only one BPEL process.
After you create the project, Eclipse BPEL Designer displays the sections shown in
Figure 2–15. You can also access this view by double-clicking the .bpel file of the
project and selecting Process Map. In this example, the project is named
myCreditFlow.
Getting Started with Oracle BPEL Process Manager 2-13
Overview of BPEL Designer Environments
Figure 2–15
Eclipse BPEL Designer Sections
In addition, the BPEL Palette of activities displays on this page. If the BPEL Palette
does not currently display, perform the following steps:
1.
Select Show View, and then Other from the Windows main menu
2.
Select BPEL, and then BPEL Palette on the Show View window, and click OK to
display the BPEL Palette in Eclipse BPEL Designer.
Figure 2–16
2-14
BPEL Palette
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
Each section of this view enables you to perform specific design and deployment
tasks. Table 2–3 identifies the sections listed in Figure 2–15 and Figure 2–16 and
provides references to sections that describe their capabilities.
Table 2–3
Eclipse BPEL Designer Sections
Section
Location
See Section
Navigator
Upper left of Figure 2–15
"Navigator" on page 2-15
Process Map window,
Middle of Figure 2–15
Overview window, and BPEL
Source window
"Process Map and Overview
Windows" on page 2-15 and
"BPEL Source Window" on
page 2-17
BPEL Inspector
Right side of Figure 2–15
"BPEL Inspector" on page 2-17
Log Window
Bottom of Figure 2–15
"Log Window" on page 2-17
BPEL Palette
Figure 2–16
"BPEL Palette" on page 2-18
See Also:
■
■
■
Chapter 3, "Building a Simple BPEL Process" for a tutorial that
enables you to design and deploy a simple Hello World BPEL
process
http://www.eclipse.org for complete details about
graphically designing processes in the Eclipse environment
http://www.oracle.com/technology/bpel for details
about software downloads and running Oracle BPEL Process
Manager and Eclipse BPEL Designer on Eclipse (including
tutorials)
Navigator
The Navigator shown in the upper left part of Figure 2–15 displays the project files in
Eclipse BPEL Designer. See Table 2–2 on page 2-5 for descriptions of the files that
initially appear when you first create a project. Eclipse BPEL Designer also includes an
additional project file: build.xml. This is an Apache Ant file used for compiling and
deploying processes in Eclipse BPEL Designer.
Figure 2–17
Navigator
Process Map and Overview Windows
The Process Map shown in the middle of Figure 2–15 provides a visual view of the
BPEL process that you design. The Process Map is similar to the Diagram View
window in JDeveloper BPEL Designer. This view displays when you perform one of
the following actions:
■
Double-click the .bpel file name in the Navigator
Getting Started with Oracle BPEL Process Manager 2-15
Overview of BPEL Designer Environments
■
Click the BPEL Designer tab; then click the Process Map tab
Figure 2–18 shows the activities automatically created with an asynchronous project.
You add to the process by dragging and dropping activities, creating variables,
creating partner links, and so on.
Figure 2–18
Process Map Window
Click Overview to display an overview on the BPEL process, as shown in Figure 2–19.
You can perform tasks such as adding partner links and creating variables in the
Overview window.
Figure 2–19
2-16
Overview Window
Oracle BPEL Process Manager Developer’s Guide
Overview of BPEL Designer Environments
See Also: The following tutorials that use Eclipse BPEL Designer to
design BPEL processes:
■
■
Chapter 3, "Building a Simple BPEL Process" for instructions on
building a Hello World tutorial
http://www.oracle.com/technology/bpel for links to
tutorials that introduce key BPEL concepts
BPEL Source Window
The BPEL Source window is similar to that in JDeveloper BPEL Designer. Click
Source Window to view the syntax inside the project files, which is similar to that
shown for JDeveloper BPEL Designer in Figure 2–8 on page 2-9.
BPEL Inspector
The BPEL Inspector enables you to perform tasks such as editing existing activities,
adding copy rules to an assign activity, creating global variables, creating partner
links, and so on. Figure 2–20 shows the BPEL Inspector.
Figure 2–20
BPEL Inspector
Log Window
You validate, compile, and deploy a process by clicking the Build BPEL Project icon in
the tool bar.
The Log Window at the bottom of Eclipse BPEL Designer then displays messages
about the status of the deployment. Figure 2–21 shows a successful deployment
message for a BPEL process. You can then run, monitor, and administer the process
from Oracle BPEL Console.
Getting Started with Oracle BPEL Process Manager 2-17
Overview of BPEL Designer Environments
Figure 2–21
Log Window
See Also:
■
■
"Overview of Oracle BPEL Console" on page 2-21
Chapter 19, "BPEL Process Deployment and
Domain Management" for specific details about deploying and
running BPEL processes
BPEL Palette
The BPEL Palette is similar to the Process Activities selection of the Component
Palette in JDeveloper BPEL Designer. The BPEL Palette displays a set of activities that
you drag and drop into the Process Map of the BPEL process. The set of activities
available with Eclipse BPEL Designer differs slightly from those available with
JDeveloper BPEL Designer. For example, unlike JDeveloper BPEL Designer, a partner
link is not listed as a BPEL Palette activity in Eclipse BPEL Designer. JDeveloper BPEL
Designer also includes additional activities for transformations, user tasks
(workflows), and notifications.
Figure 2–22
BPEL Palette
See Also: "Overview of Oracle BPEL Process Manager Services" on
page 2-22
2-18
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. JDeveloper BPEL Designer and Eclipse BPEL Designer both include 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-8 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–23 shows an example of a property window (for this example, an invoke
activity). In this example, you invoke a partner link named CreditRatingService and
define its attributes.
Figure 2–23
Invoke Activity Example
Getting Started with Oracle BPEL Process Manager 2-19
Overview of Partner Links
See Also:
■
■
■
■
Appendix C, "JDeveloper BPEL Designer Activities" for
descriptions of available activities
Part II, "Reviewing Key BPEL Development Concepts and Code
Samples" for activity concepts and code examples
Oracle_
Home\integration\orabpel\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–24 shows the partner link icon (in this example, named CreditRatingService).
Figure 2–24
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-8 shows an example of a partner link named
DBInsert being invoked by a BPEL process.
Figure 2–25 shows an example of the attributes of a partner link for a service named
RapidDistributors.
Figure 2–25
2-20
PartnerLink Window
Oracle BPEL Process Manager Developer’s Guide
Overview of Oracle BPEL Console
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 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.
My Role
The role performed by the BPEL process. In this case, the BPEL process
is the requester.
Partner Type
The role performed by the partner link (in this example, the
RapidDistributors service). In this case, RapidDistributors is the
provider.
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 Console.
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 Console
Oracle BPEL Console enables you to run, monitor, and administer BPEL processes
designed and deployed with either JDeveloper BPEL Designer or Eclipse BPEL
Designer. You can also manage BPEL domains from Oracle BPEL Console. Access
Oracle BPEL Console by selecting Start, then All Programs, then Oracle - Oracle_
Home, then Oracle BPEL Process Manager version_number, and then BPEL Console.
Figure 2–26 shows the main page of Oracle BPEL Console. In this example, a number
of deployed BPEL processes and external services appear in the Dashboard tab.
Getting Started with Oracle BPEL Process Manager 2-21
Overview of Oracle BPEL Process Manager Services
Figure 2–26
Oracle BPEL Console
See Also:
■
■
■
"Testing the BPEL Process" on page 3-16 for an Eclipse BPEL
Designer tutorial in which you run a deployed process from
Oracle BPEL Console
Chapter 19, "BPEL Process Deployment and
Domain Management" for specific details about running a
deployed process from Oracle BPEL Console
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 JDeveloper BPEL Designer 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-22
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 14, "XSLT
Mapper and
Transformations"
A notification activity enables you to send
notification 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 15,
"Oracle BPEL
Process Manager
Notification Servic
e"
Notifications
"Transform
Activity" on
page C-20
"Notification
Activity" on
page C-11
Workflows
Workflow enables you to integrate systems and
services with human workflow into a single
process flow.
A user task activity is provided that invokes the
Workflow wizard. This enables you to:
■
Select a workflow pattern to use
■
Specify workflow details
■
■
■
Chapter 16,
"Oracle BPEL
Process Manager
Workflow
Services"
"User Task" on
page C-21
Specify a task outcome (such as accept or
reject)
Specify the notification types (for example, if
a task completes, errors out, or expires, and
which recipients are notified of this action)
Specify the initial assignee for a task
The criteria that you define with the Workflow
wizard 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 17,
"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 18,
"Sensors"
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-7
Getting Started with Oracle BPEL Process Manager 2-23
Overview of Oracle BPEL Process Manager Technology Adapters
Overview of Oracle BPEL Process Manager Technology Adapters
The Partner Link Window shown in Figure 2–25 on page 2-20 also enables you to take
advantage of another key feature that Oracle BPEL Process Manager and JDeveloper
BPEL Designer provide. Click the Define Adapter Service icon shown in Figure 2–27
to access the Adapter Configuration wizard.
Figure 2–27
Defining an Adapter
Adapters enable you to integrate the BPEL processes with access to file systems,
database tables, database queues, Java Message Services (JMS), and Oracle E-Business
Suite. This wizard enables you to configure the types of adapters shown in Figure 2–28
for use with the BPEL process:
Figure 2–28
Adapter Types
When you select an adapter type, the Service Name window shown in Figure 2–29
prompts you to enter a name. For this example, File Adapter was selected in
Figure 2–28. When the wizard completes, a WSDL file by this service name appears in
the Applications 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 Applications Navigator.
2-24
Oracle BPEL Process Manager Developer’s Guide
Summary
Figure 2–29
Adapter Service Name
The Adapter Configuration wizard windows that appear after the Service Name
window are based on the adapter type you selected. These configuration windows and
the information you must provide are described in later chapters of this guide.
See Also:
■
■
■
■
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide for specific details about configuring the file, FTP,
database, AQ, 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 for
Oracle E-Business Suite
"PartnerLink Activity" on page C-12
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 JDeveloper BPEL Designer, Eclipse BPEL Designer, Oracle BPEL Server, and
Oracle BPEL Console. An overview of the main sections of JDeveloper BPEL Designer
and Eclipse BPEL Designer 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-25
Summary
2-26
Oracle BPEL Process Manager Developer’s Guide
3
Building a Simple BPEL Process
In this chapter, you create, build, deploy, and test a simple BPEL process: a
synchronous Hello World application. It accepts a name as an input message and
returns the message Hello followed by the name through a synchronous reply. You
design the process in Eclipse BPEL Designer, but alternatively, you can use JDeveloper
BPEL Designer, which provides similar functionality.
This chapter contains the following topics:
■
Overview of Building a Simple BPEL Process
■
Creating a New BPEL Project Using Eclipse BPEL Designer
■
Browsing a New Project
■
Viewing the WSDL Interface of a BPEL Process
■
Switching Between the Overview, Process Map, and Source Code
■
Reviewing the BPEL Source Code
■
Adding an Assign Activity to the Process Map
■
Compiling and Deploying the BPEL Process
■
Testing the BPEL Process
■
Summary
Overview of Building a Simple BPEL Process
The Hello World application is familiar to anyone who has taken an introductory
programming class. Here it is given as an example of a BPEL process that accepts
input, manipulates the input, and returns an output through a synchronous reply.
The BPEL process you create uses the following components:
■
■
A client application: The input for the BPEL process comes from a client
application. In this chapter, you use Oracle BPEL Console as the client application.
BPEL processes also can use a Java interface, a JSP interface, or a SOAP client as
the client application.
A partner link: The partner link connects the client application to the BPEL
process. It defines the role of each party, the types of data each accepts and returns,
and so on. The WSDL file contains the definition of the partner links.
Figure 3–1 provides an overview of how the Hello World process works.
Building a Simple BPEL Process
3-1
Creating a New BPEL Project Using Eclipse BPEL Designer
Figure 3–1 The Hello World BPEL Process
Deployment Descriptor
(bpel.xml)
Client
Application
WSDL
Client
PartnerLink
BPEL Process HelloWorld.bpel
<receive>
BPEL
Console
Or
Java / JSP
Or
Input
Message
<variable>
set
greeting
<assign>
SOAP
Client
Output
Message
<variable>
<reply>
The following actions take place:
1.
The Hello World BPEL process accepts the input from the WSDL client partner
link by using a receive activity.
2.
The receive activity repackages the input into a variable.
3.
The Hello World BPEL process adds the greeting using an assign activity, and then
sends the result back to the client application through the partner link as output by
using the reply activity.
See Also:
■
■
■
See "Reviewing the BPEL Source Code" on page 3-9 for more
information on these activities
C:\orabpel\samples\tutorials\101.HelloWorld (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\101.He
lloWorld (for JDeveloper BPEL Designer)
Creating a New BPEL Project Using Eclipse BPEL Designer
You can use the New Project wizard in Eclipse BPEL Designer to generate
automatically the skeleton of a BPEL project. This skeleton contains the BPEL source, a
WSDL interface, a BPEL deployment descriptor, and an Ant script for compiling and
deploying the BPEL process.
To create a new BPEL project:
3-2
Oracle BPEL Process Manager Developer’s Guide
Creating a New BPEL Project Using Eclipse BPEL Designer
1.
Open Eclipse BPEL Designer by selecting Start, then All Programs, then Oracle Oracle_Home, then Oracle BPEL Process Manager version_number, and then
BPEL Designer.
2.
Start the BPEL Server by selecting Start, then All Programs, then Oracle - Oracle_
Home, then Oracle BPEL Process Manager version_number, and then Start BPEL
Server.
3.
From the File menu, click New, then Project.
4.
Select Oracle BPEL Project.
5.
Click Next.
6.
Enter SyncHelloWorld as the BPEL process name.
Do not create a project name that begins with a number.
7.
(Optional) Enter http://tutorial.oracle.com as the namespace (replacing the one
provided by default).
8.
Change the template to Synchronous BPEL Process.
9.
Leave the Use default check box selected, and click Finish.
Building a Simple BPEL Process
3-3
Browsing a New Project
Browsing a New Project
The New Project wizard creates an initial set of project files for a new synchronous
BPEL process, with all the necessary source files. Figure 3–2 provides an overview of
how a new project appears in Eclipse BPEL Designer.
3-4
Oracle BPEL Process Manager Developer’s Guide
Browsing a New Project
Figure 3–2 A New BPEL Process
Table 3–1 describes the initial project files that are created:
Table 3–1
BPEL Process Files
File
Description
.project
Eclipse BPEL Designer format project file.
bpel.xml
The deployment descriptor for the process. This file defines the
locations of the WSDL files for services this process flow calls,
along with other project-specific parameters.
See Also: Appendix E, "Deployment Descriptor Properties"
build.xml
Apache Ant script for compiling and deploying this process.
SyncHelloWorld.bpel
The BPEL source code for the process. The New Project wizard
creates an empty flow, with just the minimum activities and
definitions for the selected flow type. For a synchronous BPEL
process, the only activities are a receive activity to initiate the
flow from a synchronous client request, and a reply activity to
return the output.
Building a Simple BPEL Process
3-5
Viewing the WSDL Interface of a BPEL Process
Table 3–1 (Cont.) BPEL Process Files
File
Description
SyncHelloWorld.wsdl
The WSDL (client) interface for this process. This file defines the
input and output messages for this flow, the client interface and
operations supported, and the BPEL partnerLinkTypes, so
the flow can be incorporated into other processes. The New
Project wizard generates a document-literal style WSDL that
takes a string input message and returns a string response
message.
Viewing the WSDL Interface of a BPEL Process
After you create a new BPEL process, you can view and, if necessary, edit its WSDL
file. WSDL files define the interface to the process flow, messages that it accepts and
returns, operations that are supported, and so on. You can edit the WSDL file for the
BPEL process in text mode in Eclipse BPEL Designer or in any other text editor. If you
edit the WSDL file, you must refresh the client interface for the flow, if it is currently
open in Eclipse BPEL Designer. In this tutorial, you do not edit the WSDL file; you
only view it.
To view the input and output messages of the BPEL process:
1.
In the Navigator, expand SyncHelloWorld and double-click the
SyncHelloWorld.wsdl file.
2.
Scroll through the WSDL file.
The New Project wizard created the SyncHelloWorldRequest complexType
element, which the flow accepts as input (in a document-literal style WSDL
message), and a SyncHelloWorldResponse element that it returns.
3-6
Oracle BPEL Process Manager Developer’s Guide
Switching Between the Overview, Process Map, and Source Code
3.
Close the (unmodified) SyncHelloWorld.wsdl window in the designer by clicking
its Close button on the SyncHelloWorld.wsdl tab.
Switching Between the Overview, Process Map, and Source Code
This section describes how to view the BPEL file in three different ways.
■
Viewing an Overview of a BPEL Process
■
Viewing a Detailed Process Map
■
Viewing BPEL Source Code
Viewing an Overview of a BPEL Process
To display a visual overview of a BPEL process, double-click SyncHelloWorld.bpel in
the Navigator, if it is not already open. Whenever you create a new BPEL project, the
visual overview automatically opens.
On the left side of the overview is the client interface, which displays operations
exposed by the process and any asynchronous callback operations (there are none for
this process). Eclipse BPEL Designer automatically puts any partner link named client
on the left side of the window. All other partner links are displayed in a list on the
right.
Figure 3–3 Overview of the SyncHelloWorld Process
Building a Simple BPEL Process
3-7
Switching Between the Overview, Process Map, and Source Code
Viewing a Detailed Process Map
The detailed process map provides a visual representation of the flow logic used for
the process, from start to end. To display and edit the process map, click Process Map
in the visual overview window. Alternatively, you can click the Edit Process Map link.
An Inspector pane appears on the right after you drill down into the Process Map
view.
At the top of the window, the Overview and Process Map links allow you to shift
from the current view (which is the Process Map view) to the Overview view, and
back.
Figure 3–4 Detailed Process Map of the SyncHelloWorld Process
Viewing BPEL Source Code
At the bottom of the window, you can use the BPEL Designer and BPEL Source tabs
to switch between graphical editing mode (BPEL Designer) and text-editing mode for
the source code of the BPEL process (BPEL Source). Two-way editing is enabled; that
is, changes you make in one mode are reflected in the other mode.
Click the BPEL Source tab of the editor window to display the syntax.
3-8
Oracle BPEL Process Manager Developer’s Guide
Reviewing the BPEL Source Code
Figure 3–5 Source Code of SyncHelloWorld Process
Reviewing the BPEL Source Code
You can use BPEL Source mode to view and edit the BPEL code generated by Eclipse
BPEL Designer. This helps you to understand what the designer does, because
everything you do in the designer is saved in standard BPEL source code. This also
helps you to learn how BPEL generates code if you are not already familiar with it.
The source code has the following main components:
■
Process Element: Defining the Name and Target Space
■
Partner Links: Defining Services This Service Uses
■
Global Variables: Variables Accessible Throughout the Process
■
Main Body of the Process: Defining the BPEL Activity
Process Element: Defining the Name and Target Space
The process element, which appears first, defines the name and target namespace
you specified.
<process name="SyncHelloWorld"
targetNamespace="http://tutorial.oracle.com"
suppressJoinFailure="yes" xmlns:tns="http://tutorial.oracle.com"
xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:bpelx="http://schemas.oracle.com/bpel/extension">
Partner Links: Defining Services This Service Uses
After the process element are the partner links, which define the other services or
processes with which the process interacts. In this case, the only partner link created
automatically by the wizard is the one for the client interface to this BPEL process.
<partnerLinks>
Building a Simple BPEL Process
3-9
Reviewing the BPEL Source Code
<partnerLink name="client"
<!-- comments... -->
partnerLinkType="tns:SyncHelloWorld"
</partnerLinks>
myRole="SyncHelloWorldProvider"/>
Global Variables: Variables Accessible Throughout the Process
After the partner links is where you define any global variables that are accessible
throughout the process. The New Project wizard automatically creates global variables
for the input and output messages for the process. As you saw previously, the types
for these two variables are defined in the WSDL for the process.
<variables>
<!-- Reference to the message passed as input during initiation -->
<variable name="input"
messageType="tns:SyncHelloWorldRequestMessage"/>
<!-- Reference to the message that will be returned to the
requester
-->
<variable name="output"
messageType="tns:SyncHelloWorldResponseMessage"/>
</variables>
Main Body of the Process: Defining the BPEL Activity
After the global variables is the main body of the process, which is any single BPEL
activity. This is typically a compound activity that contains subactivities. When you
create a new synchronous process, the New Project wizard creates a sequence (which
in BPEL is a set of activities executed sequentially) that contains a receive activity to
obtain the input message from the client to start the process. This is followed by a
reply activity to return the result synchronously to the client.
<sequence name="main">
<!-- Receive input from requester.
Note: This maps to operation defined in SyncHelloWorld.wsdl
-->
<receive name="receiveInput" partnerLink="client"
portType="tns:SyncHelloWorld"
operation="process" variable="input"
createInstance="yes"/>
<reply name="replyOutput"
partnerLink="client"
portType="tns:SyncHelloWorld"
operation="process"
variable="output"/>
</sequence>
Finally, the process is closed:
</process>
In the next section, you can begin to edit this BPEL process to add logic to convert the
input into a greeting.
Using the Sequence Activity to Performs Actions Sequentially
A sequence activity contains one or more activities that perform sequentially in the
order in which they are listed within the sequence element; that is, in lexical order. The
3-10
Oracle BPEL Process Manager Developer’s Guide
Adding an Assign Activity to the Process Map
sequence activity completes when the final activity in the sequence has completed.
The sequence activity uses the following syntax:
<sequence standard-attributes>
standard-elements
activity+
</sequence>
For example, the structure for a sequence activity that has a flow activity, scope
activity, and pick activity is as follows:
<sequence>
<flow>
...
</flow>
<scope>
...
</scope>
<pick>
...
</pick>
</sequence>
See Also: "Sequence Activity" on page C-17
Using the Assign Activity to Assign Values to Variables
The assign activity assigns values to variables. You need to add copy rules to the
assign activity to specify which data is being copied into which variable. The source
code for an assign activity with copy rules is as follows:
<assign>
<copy>
<from expression="concat('Hello ',bpws:getVariableData('input',
'payload','/tns:name'))"/>
<to variable="output" part="payload" query="/result"/>
</copy>
</assign>
If you are using JDeveloper BPEL Designer, this sample is available in Oracle_
Home\integration\orabpel\samples\tutorials\101.HelloWorld.
See Also:
■
■
■
"Assign Activity" on page C-3
C:\orabpel\samples\references\Assign (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\Assign (for
JDeveloper BPEL Designer)
Adding an Assign Activity to the Process Map
In this section, you learn how to add a new activity to the BPEL process. You follow
these steps:
1.
Step 1: Viewing the Process Map
2.
Step 2: Inserting an Assign Activity
Building a Simple BPEL Process 3-11
Adding an Assign Activity to the Process Map
3.
Step 3: Adding a Copy Rule
4.
Step 4: Defining the From Part (Source) of the Copy Rule
5.
Step 5: Defining the To Part (Destination) of the Copy Rule
Step 1: Viewing the Process Map
Return to BPEL Designer mode and click the Process Map button to ensure that you
are in Process Map view. You now see a graphical representation of the flow for the
BPEL process. As described previously, the initial process created by the New Project
wizard for a synchronous process just receives the input for the process operation from
the client and returns the response with a synchronous reply.
Step 2: Inserting an Assign Activity
Now insert an assign activity into the process. A BPEL assign activity provides a
mechanism for doing simple data manipulation using XPath expressions.
You use the assign activity to concatenate the string "Hello " with the string name
input message and copy the resulting string into the output message.
To insert a new activity into the process, find it in the BPEL Palette (you can click the
More Activities link to see additional activities supported in BPEL Designer mode)
and drag it to the location in the flow in which you want to insert it.
1.
3-12
From the BPEL Palette, drag an assign activity and drop it between the process
receive activity and the reply response activity:
Oracle BPEL Process Manager Developer’s Guide
Adding an Assign Activity to the Process Map
The new assign activity is initially selected. You can edit attributes for it in the
BPEL Inspector window on the right.
2.
Click in the assign activity’s name field (below its icon) and enter a value for the
optional name attribute, such as createReturnStr.
3.
Press Enter.
Step 3: Adding a Copy Rule
Next, you are ready to add a copy rule. In the tasks list (the down arrow to the right of
the assign activity heading), click Add Copy Rule.
This displays the Copy Rule window, which you use to perform data manipulation. In
BPEL, an assign activity can have many copy rules, each using variable data, XPath
queries, XPath expressions, and literals to do simple data manipulation and
transformation.
Building a Simple BPEL Process 3-13
Adding an Assign Activity to the Process Map
Each Copy Rule window for an assign activity has a From part, which specifies the
source data, and a To part, which specifies a variable or element part as the destination
for the data.
Figure 3–6 Adding a Copy Rule
Note: If you want to perform more complex data transformations
using XQuery, XSLT, Java, commercial toolkits, or Web services, see
the following Web site for more information:
http://www.oracle.com/technology/bpel
See Also: Chapter 14, "XSLT Mapper and Transformations"
Step 4: Defining the From Part (Source) of the Copy Rule
After you have added the copy rule, you are ready to define its From (source) part.
Follow these steps:
1.
Click Expression in the From part. Enter the following expression in the text field:
concat( ’Hello ’, bpws:getVariableData( 'input', 'payload',
'/SyncHelloWorldRequest/input’))
Alternatively, use the XPath function wizard to complete this with the following
steps:
3-14
2.
Click the ... context-sensitive BPEL assistant button to start the BPEL Function
Wizard.
3.
Select the contact function and click Next.
Oracle BPEL Process Manager Developer’s Guide
Adding an Assign Activity to the Process Map
4.
Enter "Hello " for the firstString (include quotes and add a trailing space after
the o).
5.
For the nextString, click the drop-down arrow to use the XPath picker and choose
the Variable input, the Part payload, and the XPath Query input.
6.
Click Finish.
A concat expression similar to the previous one appears, except that the wizard
includes the name prefix tns: for the XPath expression.
Whether you enter it directly or use the wizard, this expression says to concatenate the
literal string Hello with the string element that is accessed by the XPath query
/SyncHelloWorldRequest/input within the part payload of the variable input.
See Also: The following documentation for more information on
XPath expressions and queries:
■
■
■
■
Appendix G, "XPath Extension Functions"
The XML Path Language (XPath) Specification at
http://www.w3.org/TR/1999/REC-xpath-19991116
The Business Process Execution Language for Web Services
Specification at
http://www.ibm.com/developerworks/webservices/lib
rary/ws-bpel, which describes the bpws:getVariableData
XPath function in Section 14.1
The BPEL Tutorials link at
http://www.oracle.com/technology/bpel, for tutorials 2
(Developing a Credit Flow BPEL Process) and 3 (Manipulating
XML Documents in BPEL)
Step 5: Defining the To Part (Destination) of the Copy Rule
Next, you complete the To section of the Copy Rule window to copy the concatenated
string into the helloString element in the reply message.
Follow these steps:
1.
In the To section, click the down arrow after the field.
2.
Select output, then payload, then SyncHelloWorldResponse, and then result
string:
Eclipse BPEL Designer generates the XPath query string
$output/payload/tns:SyncHelloWorldResponse/tns:result and enters it in the
field.
Again, you can always enter queries directly into the field if you choose. The
wizard uses fully qualified names (including the namespaces) in the query string,
but in both of these examples the namespaces are actually optional.
Building a Simple BPEL Process 3-15
Compiling and Deploying the BPEL Process
3.
Click Done.
Next, you are ready to compile and deploy the BPEL process, and then test it.
Compiling and Deploying the BPEL Process
To compile and deploy the BPEL process:
1.
Save the process.
2.
Click the Build BPEL Project button on the Workbench toolbar to compile and
deploy the process.
This compiles the flow and packages its components into a BPEL suitcase JAR file. You
then can deploy this JAR file to Oracle BPEL Server by copying it into the appropriate
deployment directory. The build.xml file also deploys the suitcase to the local
server’s default domain, in this case C:\orabpel\domains\default\deploy.
(Note that this action is the same as running obant from the command line.)
Note: To see the contents of the BPEL suitcase JAR file, open the file
C:\orabpel\domains\default\deploy\bpel_
SyncHelloWorld_1.0.jar with any tool for opening JAR files (for
example, WinZip).
Testing the BPEL Process
After you have compiled and deployed the BPEL process, you can test it by using the
automatically generated test interface in Oracle BPEL Console.
To test the SyncHelloWorld BPEL process:
1.
Access the console at http://localhost:9700/BPELConsole or by selecting
Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process
Manager version_number, and then BPEL Console.
Alternatively, you can click the Open BPEL Console button on the Workbench
toolbar to open a browser window that points to the console.
2.
3-16
Log in to the default domain to access the Dashboard tab:
Oracle BPEL Process Manager Developer’s Guide
Testing the BPEL Process
3.
Click the SyncHelloWorld BPEL process link.
4.
Complete the HTML test form interface.
5.
Enter your name (this example uses Jane Doe) in the input field and click Post
XML Message to initiate the process:
Building a Simple BPEL Process 3-17
Summary
You now see the results, because it is a synchronous operation.
6.
To see the visual audit trail for this completed instance, click the Visual Flow link.
The visual audit trail displays a representation of the current state and history of
execution of the instance (which in this case, has completed), with the same look
and feel as Eclipse BPEL Designer. You can select activities in the audit trail to
view their details. You can also click the Audit tab to see the text audit trail or the
Debug tab to see the debugger for this instance.
7.
Click the reply client activity at the bottom of the audit trail to see the returned
XML message for the process, as shown previously.
Summary
This chapter discusses some of the basic concepts of a BPEL process, and shows the
steps necessary to create a BPEL process for a simple Hello World application. These
steps are shown in Eclipse BPEL Designer, but you can also use JDeveloper BPEL
Designer. This process runs from Oracle BPEL Console. It is a synchronous Web
service that can be used as a building block for other BPEL processes or invoked using
standard Web services interfaces.
3-18
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 4, "Manipulating XML Data in BPEL"
■
Chapter 5, "Invoking a Synchronous Web Service"
■
Chapter 6, "Invoking an Asynchronous Web Service"
■
Chapter 7, "Parallel Flow"
■
Chapter 8, "Conditional Branching"
■
Chapter 9, "Fault Handling"
■
Chapter 10, "Incorporating Java and J2EE Code in BPEL Processes"
■
Chapter 11, "Events and Timeouts"
■
Chapter 12, "Invoking a BPEL Process"
■
Chapter 13, "Interaction Patterns"
4
Manipulating XML Data in BPEL
This chapter describes how to manipulate XML data in BPEL, including the large role
that XPath expressions play in manipulating XML data.
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 how you can manipulate XML data in
BPEL. The use cases include topics such as how to work with variables, perform tasks
such as mathematical calculations, and work with sequences and arrays. This chapter
reviews the simplest to the most advanced methods for manipulating XML data in
BPEL. The explanations are largely by example, and provide an introduction to the
supporting specifications without repeating their details.
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
Manipulating XML Data in BPEL
4-1
Overview of Manipulating XML Data in BPEL Concepts
working with a type defined in an RPC WSDL file, see "Differences Between
Document-Style and RPC-Style WSDL Files" on page 4-17.
See Also: The sample files located at
■
■
C:\orabpel\samples\tutorials\103.XMLDocuments (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\103.XM
LDocuments (for JDeveloper BPEL Designer)
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>
4-2
Oracle BPEL Process Manager Developer’s Guide
Overview of Manipulating XML Data in BPEL Concepts
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"/>
</copy>
</assign>
Rather than repeating all syntax details, this chapter shows and describes excerpts
taken primarily from sample projects provided in the
C:\orabpel\samples\references directory for Eclipse BPEL Designer and
Oracle_Home\integration\orabpel\samples\references directory for
JDeveloper BPEL Designer.
Note: If you used the tutorials with either BPEL designer
(JDeveloper BPEL Designer or Eclipse BPEL Designer) to add an
assign activity to the process, you supplied details about the activity
in a Copy Rule window that included a From section and a To section.
This reflects the underlying BPEL source code syntax shown
previously in this section.
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')"/>
Manipulating XML Data in BPEL
4-3
Overview of Manipulating XML Data in BPEL Concepts
For a complete list of the functions built into XPath standards, see section 4 of the
XML Path Language (XPath) Specification.
■
BPEL XPath extension functions: BPEL adds several extension functions to the
core XPath core functions, enabling XPath expressions to access information from
a process. The extensions are defined in the standard BPEL namespace
http://schemas.xmlsoap.org/ws/2003/03/business-process/ and
indicated by the prefix bpws:
<from expression= “bpws:getVariableData('input', 'payload', '/p:value') + 1"/>
For more information, see sections 9.1 and 14.1 of the Business Process Execution
Language for Web Services Specification.
■
Oracle BPEL Extension XPath 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:. If you have Oracle BPEL Process Manager installed locally, Oracle
BPEL Console lists and describes all available XPath functions through the
following URL:
See Also: The XPath extension documentation available at either of
the following locations:
■
■
■
Appendix G, "XPath Extension Functions"
http://localhost:9700/BPELConsole/default/domain.js
p?mode=xpath
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:
–
C:\orabpel\domains\default\config\xpath-functions.xml file
(for Eclipse BPEL Designer)
–
Oracle_
Home\integration\orabpel\domains\default\config\xpath-func
tions.xml file (for JDeveloper BPEL Designer)
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.
4-4
Oracle BPEL Process Manager Developer’s Guide
Copying Between Variables
See Also: The following XPath and XQuery transformation code
examples:
■
C:\orabpel\samples\tutorials\114.XSLTTransformations
(for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\114.XSLTTr
ansformations (for JDeveloper BPEL Designer)
■
Chapter 14, "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/>
<message/>
</result>
</from>
<to variable="output" part="payload"/>
</copy>
</assign>
See Also: The following samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
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.
Manipulating XML Data in BPEL
4-5
Accessing Fields within Complex Type Variables
<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>
See Also: Section 9.3.2 of the Business Process Execution Language for
Web Services Specification for this code example
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"/>
<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:
4-6
Oracle BPEL Process Manager Developer’s Guide
Mathematical Calculations with XPath Standards
<message name="CreditRatingServiceRequestMessage">
<part name="payload" element="tns:ssn"/>
</message>
See Also: The following samples:
■
■
■
C:\bpelz\workspace\CreditFlow (for Eclipse BPEL
Designer)
C:\orabpel\samples\utils\CreditRatingService (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\utils\CreditRati
ngService (for JDeveloper BPEL Designer)
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 samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
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',
'/p:value') + 1"/>
<to variable="output" part="payload" query="/p:result"/>
</copy>
</assign>
Manipulating XML Data in BPEL
4-7
Assigning String Literals
See Also: The following samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
Assigning String Literals
This example copies an expression evaluating to 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 samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
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. In Chapter 3, "Building a Simple BPEL Process", you concatenated the string
'Hello ' with a name supplied in an input message. A similar example from the
assign reference sample 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.
4-8
Oracle BPEL Process Manager Developer’s Guide
Assigning Date or Time
See Also: The following samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
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>
See Also: The following samples:
■
■
C:\orabpel\samples\references\Assign (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Assig
n (for JDeveloper BPEL Designer)
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')"/>
Manipulating XML Data in BPEL
4-9
Manipulating Attributes
<to variable="output" part="payload"
query="/invoice/formattedDate"/>
</copy>
</assign>
See Also: The following samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
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>
4-10
Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences that Use Arrays
See Also: The following samples:
■
■
C:\orabpel\samples\references\XPath (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
(for JDeveloper BPEL Designer)
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
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:
■
■
C:\orabpel\samples\tutorials\112.Arrays (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\112.Ar
rays (for JDeveloper BPEL Designer)
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
Manipulating XML Data in BPEL 4-11
Manipulating XML Data Sequences that Use Arrays
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.
See Also: The following samples:
■
■
C:\orabpel\samples\references\XPath (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
(for JDeveloper BPEL Designer)
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 samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
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:
4-12
Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences that Use Arrays
■
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
■
Merging Data Sequences that Use Arrays
■
Appending New Items to a Sequence that Uses an Array
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" />
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:
Manipulating XML Data in BPEL 4-13
Manipulating XML Data Sequences that Use Arrays
<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 C-3 for details about using multiple
copies of this extension in a single assign activity
■
C:\orabpel\samples\tutorials\126.DataAggregator\Agg
regationTutorial (for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\126.Da
taAggregator\AggregationTutorial (for JDeveloper BPEL
Designer)
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).
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>
4-14
Oracle BPEL Process Manager Developer’s Guide
Manipulating XML Data Sequences that Use Arrays
See Also: The ArraySample.bpel sample file located at:
■
■
C:\orabpel\samples\tutorials\112.Arrays (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\112.Ar
rays (for JDeveloper BPEL Designer)
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 samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
Merging Data Sequences that Use Arrays
You can merge two sequences of compatible types into a single sequence. To do so, use
the XPath function mergeChildNodes.
<!-- execute the XPath extension function mergeChildNodes(e1, e2) and assign to a
variable -->
<assign>
<copy>
<from expression="ora:mergeChildNodes(
bpws:getVariableData('input', 'payload', '/invoice/lineItems'),
bpws:getVariableData('literalLineItems'))"/>
<to variable="mergedLineItems"/>
</copy>
</assign>
Manipulating XML Data in BPEL 4-15
Converting from a String to an XML Element
See Also: The following samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
Appending New Items to a Sequence that Uses an Array
The BPEL XPath function addChildNode enables BPEL processes to append new
elements to an existing sequence.
<!-- execute the XPath extension function addChildNode(Element e, Node childNode)
-->
<assign>
<copy>
<from expression="ora:addChildNode(bpws:getVariableData('output',
'payload', '/invoice/lineItems'),
bpws:getVariableData('escapedLineItem'))"/>
<to variable="output" part="payload" query="/invoice/lineItems"/>
</copy>
</assign>
See Also: The following samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
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.
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
4-16
Oracle BPEL Process Manager Developer’s Guide
Differences Between Document-Style and RPC-Style WSDL Files
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 samples:
■
■
C:\orabpel\samples\references\XPathFunction (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\XPath
Function (for JDeveloper BPEL Designer)
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:
<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.
Manipulating XML Data in BPEL 4-17
Differences Between Document-Style and RPC-Style WSDL Files
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:
■
■
C:\orabpel\samples\utils\AsyncLoanService
(LoanServices for Eclipse BPEL Designer)
C:\orabpel\samples\demos\LoanDemo\LoanFlow (BPEL
demo application for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\utils\AsyncLoanS
ervice (LoanServices for JDeveloper BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\demos\LoanDemo\L
oanFlow (BPEL demo application for JDeveloper BPEL Designer)
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
>
<input1
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">boo</input
1>
<input2
xmlns="http://xmlns.oracle.com/MessageParts_referingToComplexTypes">woo</input
2>
<input3
4-18
Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
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 Console.
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
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>
Manipulating XML Data in BPEL 4-19
Using Binary Attachments in SOAP Messages
<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.
See Also:
■
Oracle_
Home\integration\orabpel\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 either BPEL
designer (JDeveloper BPEL Designer or Eclipse BPEL Designer). 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:
■
■
4-20
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.
Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
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>
</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"/>
Manipulating XML Data in BPEL 4-21
Using Binary Attachments in SOAP Messages
<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>
<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>
4-22
Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
<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"
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>
Manipulating XML Data in BPEL 4-23
Using Binary Attachments in SOAP Messages
<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 4–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 4–2 on page 4-26.
Example 4–1
SAAJ Example
public boolean initiateUsingSAAJ(String filename) throws Exception {
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 =
4-24
Oracle BPEL Process Manager Developer’s Guide
Using Binary Attachments in SOAP Messages
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
// 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);
Manipulating XML Data in BPEL 4-25
Summary
receivedFile.delete();
return retv;
}
}
Example 4–2 shows the sample request sent by the SAAJ program:
Example 4–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>
.....................
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
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.
4-26
Oracle BPEL Process Manager Developer’s Guide
5
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.
Invoking a Synchronous Web Service
5-1
Overview of Synchronous Service Concepts
See Also: The following files used as examples in this chapter:
If you are using Eclipse BPEL Designer:
■
C:\orabpel\samples\tutorials\104.SyncQuoteConsumer\
QuoteConsumer.bpel
■
C:\orabpel\samples\tutorials\104.SyncQuoteConsumer\
bpel.xml
■
C:\orabpel\samples\tutorials\104.SyncQuoteConsumer\
QuoteConsumer.wsdl
■
C:\orabpel\samples\utils\StockQuoteService\StockQuo
teService.wsdl
If you are using JDeveloper BPEL Designer:
■
Oracle_
Home\integration\orabpel\samples\tutorials\104.Sy
ncQuoteConsumer.bpel
■
Oracle_
Home\integration\orabpel\samples\tutorials\104.Sy
ncQuoteConsumer\bpel.xml
■
Oracle_
Home\integration\orabpel\samples\tutorials\104.Sy
ncQuoteConsumer.wsdl
■
Oracle_
Home\integration\orabpel\samples\utils\104.StockQ
uoteService.wsdl
Overview of Synchronous Service Concepts
A synchronous callback requires the following two key 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.
Establishing the Partner Link
This section covers the following topics:
5-2
■
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
Oracle BPEL Process Manager Developer’s Guide
Overview of Synchronous Service Concepts
■
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"/>
<!-- 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
Invoking a Synchronous Web Service
5-3
Overview of Synchronous Service Concepts
-->
<!-- 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 -->
<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.
5-4
Oracle BPEL Process Manager Developer’s Guide
Overview of Synchronous Service Concepts
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.
Accessing Web Services on Remote Servers
When creating a partner link, you can also select Web services on remote servers. Edit
the Oracle_Home\integration\jdev\jdev\lib\ext\inspection.wsil file
to specify the remote location.
The Web service is then accessible from JDeveloper BPEL Designer. Click the WSIL
Browser icon when creating a partner link on the Create Partner Link window. This
displays the WSDL Chooser window, which enables you to select the remote Web
service.
See Also: "PartnerLink Activity" on page C-12
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 C-9
Invoking a Synchronous Web Service
5-5
Calling a Synchronous Service
Calling a Synchronous Service
This section examines the QuoteConsumer.bpel file so that you can explore the
concepts involved with a synchronous callback operation. You can import the project
file at this location to examine the application. For a more step-by-step approach, see
http://www.oracle.com/technology/bpel and download the files under BPEL
Training Materials.
Figure 5–1 provides an overview of the QuoteConsumer.bpel file in Eclipse BPEL
Designer, which defines a simple application with five activities.
Figure 5–1 Overview 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 invokeStockQuote service 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 that performs the synchronous callback is on lines 61–91:
<assign>
<copy>
<from variable="input" part="payload" query="/tns:symbol"/>
<to variable="request" part="symbol" query="/symbol"/>
</copy>
5-6
Oracle BPEL Process Manager Developer’s Guide
Summary
</assign>
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"
portType="services:StockQuoteService" operation="process"
inputVariable="request" outputVariable="response"/>
<!-- 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
5-7
Summary
5-8
Oracle BPEL Process Manager Developer’s Guide
6
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’s .wsdl file
contains the information necessary to request and receive the desired information.
Figure 6–1 provides an overview of how this BPEL process works with the
asynchronous loan processor Web service.
Invoking an Asynchronous Web Service 6-1
Use Case for Asynchronous Web Services
Figure 6–1 Asynchronous Service Invocation
Deployment Descriptor
(bpel.xml)
Client
Application
WSDL
Client
PartnerLink
BPEL Process
Input
<variable>
d1
<receive>
BPEL
Console
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 inititiating 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 requestor.
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 6–1.
6-2
Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
See Also: The following sample files for examples of an asynchronous
Web service that is not a BPEL process:
■
C:\orabpel\samples\interop\axis\BPELCallingAsyncAXIS
(for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\interop\axis\BPEL
CallingAsyncAXIS (for JDeveloper BPEL Designer)
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 described in this chapter:
If you are using Eclipse BPEL Designer:
■
C:\orabpel\samples\utils\AsyncLoanService\LoanServi
ce.wsdl
■
C:\orabpel\samples\tutorials\105.AsyncCompositeLoan
Broker\ LoanBroker.bpel
■
C:\orabpel\samples\tutorials\105.AsyncCompositeLoan
Broker\bpel.xml
If you are using JDeveloper BPEL Designer:
■
Oracle_
Home\integration\orabpel\samples\utils\AsyncLoanS
ervice\LoanService.wsdl
■
Oracle_
Home\integration\orabpel\samples\tutorials\105.As
yncCompositeLoanBroker\LoanBroker.bpel
■
Oracle_
Home\integration\orabpel\samples\tutorials\105.As
yncCompositeLoanBroker\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
Invoking an Asynchronous Web Service 6-3
Overview of Asynchronous Callback Concepts
See Also: "PartnerLink Activity" on page C-12
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.
<!-- 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>
6-4
Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
</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:
■
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>
Invoking an Asynchronous Web Service 6-5
Overview of Asynchronous Callback Concepts
See Also:
■
■
"Step 1: Adding a Partner Link for an Asynchronous Service" on
page 6-10 for instructions on creating a partner link
Appendix E, "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 5, "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
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 6-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.
6-6
Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
See Also: The following sections for instructions on creating invoke
and receive activities:
■
"Step 2: Adding an Invoke Activity" on page 6-11
■
"Step 3: Adding a Receive Activity" on page 6-13
■
"Invoke Activity" on page C-9
■
"Receive Activity" on page C-14
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:
<!-- 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 6–2 provides an
overview.
Invoking an Asynchronous Web Service 6-7
Overview of Asynchronous Callback Concepts
Figure 6–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 6–2 shows how messages are passed along with WS headers so that the
response can be sent to the correct destination.
The example in this chapter uses WS-Addressing for correlation. To view the
messages, you can use TCP tunneling, which is described in "Using TCP Tunnelling to
See Messages Exchanged Between Programs" on page 6-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 Tunnelling 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 flow and Web
services.
6-8
Oracle BPEL Process Manager Developer’s Guide
Overview of Asynchronous Callback Concepts
To monitor the SOAP messages, insert a software listener in 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/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.
If you are a JDeveloper BPEL Designer user, you can also use the built-in Packet
Monitor to see SOAP messages for both synchronous and asynchronous services.
See Also: The following documentation, which is accessible from
http://www.oracle.com/technology/bpel:
■
■
Web Services Addressing (WS-Addressing) Specification for complete
details about WS-Addressing
BPEL-TN001: TCP Tunneling the Oracle BPEL Process Manager for
instructions on using TCP tunneling to view SOAP messages
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 6-14
for a tutorial on creating correlations sets in JDeveloper BPEL
Designer
■
C:\orabpel\samples\tutorials\109.CorrelationSets
(for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\109.Co
rrelationSets (for JDeveloper BPEL Designer)
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>
Invoking an Asynchronous Web Service 6-9
Calling an Asynchronous Service
See Also:
■
"Returning External Faults" on page 9-7
■
"Reply Activity" on page C-15
■
■
C:\orabpel\samples\references\Reply (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\Reply
(for JDeveloper BPEL Designer)
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 can
create a dehydration point. 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.
You insert this point between the invoke activity and receive activity. Figure 6–1 on
page 6-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 Applications Navigator.
2.
In the diagram view, right-click either side of the BPEL process (under Partner
Links).
3.
Select Create Partner Link from the menu.
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:
■
■
6-10
Name: Enter a name for the partner link.
WSDL File: Enter the name of the WSDL file to use. Click the Browse WSDL
Files from Local File System or WSIL Browser icon above this field to locate
the correct WSDL.
Oracle BPEL Process Manager Developer’s Guide
Calling an Asynchronous Service
■
■
■
5.
Partner Link Type: Refers to the external service with which the BPEL process
is to interface. Select from the list.
My Role: Refers to role of the BPEL process in this interaction, for example,
requester. Select from the list.
Partner Role: Refers to the role of the external source, for example, provider.
Select from the list.
Click OK.
A new partner link for the loan application approver Web service (United Loan)
appears in the Partner Links area of the .bpel file’s diagram view.
See Also:
■
■
"partnerLinkTypes for Asynchronous Services" on page 6-3 for
conceptual details about partner links
"PartnerLink Activity" on page C-12
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 view, right-click either side of the BPEL process and
select Variables from the menu.
Invoking an Asynchronous Web Service 6-11
Calling an Asynchronous Service
The Variables window appears.
3.
Select Variables and right-click, then select Create Variable.
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
Message Types navigation window to select Message Types, then Partner
Links, then Loan Service, then United Loan, then Message Types, then
LoanServiceRequest Message.
■
6-12
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.
Oracle BPEL Process Manager Developer’s Guide
Calling an Asynchronous Service
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 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 6-6 for
conceptual details about the invoke activity
"Invoke Activity" on page C-9
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 6-11.
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 6-11.
Invoking an Asynchronous Web Service 6-13
Using Correlation Sets in an Asynchronous Service
3.
Double-click the receive activity and in the Receive window, 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 6-11.
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 C-14
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:
■
"Adding an Assign Activity to the Process Map" on page 3-11
■
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
JDeveloper BPEL Designer. 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
6-14
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
use correlation sets for a process having three receive activities with no associated
invoke activities.
This section contains the following topics:
■
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 workspace in the Applications Navigator section of the designer
window.
2.
Select New Project.
3.
Double-click BPEL Process Project in the Items window to display the BPEL
Process Project window.
4.
Enter an appropriate name in the BPEL Process Name field (for this example,
MyCorrelationSet is used).
5.
Select Asynchronous BPEL Process from the Template list.
6.
Click OK.
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.
Drag and drop an initial PartnerLink activity onto the right side of the designer
window anywhere beneath the header Partner Links.
2.
Enter FirstReceivePL in the Name field.
3.
Click the third icon at the top (the Define Adapter Service icon). This starts the
Adapter Configuration Wizard.
Invoking an Asynchronous Web Service 6-15
Using Correlation Sets in an Asynchronous Service
4.
Click Next on the Welcome window.
5.
Select File Adapter on the Adapter Type window and click Next.
6.
Enter FirstReceive in the Service Name field on the Service Name window and
click Next.
7.
Select Read File as the Operation Type on the Operation window and click Next.
The Operation Name field is automatically filled in with Read.
8.
Select Directory Names are Specified as Physical Path.
9.
Click Browse next to the Directory for Incoming Files (physical path) field.
10. Select a directory from which to read files (for this example,
C:\files\receiveprocess\FirstInputDir is selected).
11. Click Select.
12. Click Next.
13. Enter appropriate file filtering parameters in the File Filtering window.
14. Click Next.
15. Enter appropriate file polling parameters in the File Polling window.
16. Click Next.
17. Click Browse next to the Schema File URL field in the Messages window to
display the Type Chooser window.
18. Select an appropriate XSD schema file. For this example, Book1_4.xsd is the
schema and LoanAppl is the schema element selected.
19. Click OK.
The Schema File URL field (Book1_4.xsd for this example) and the Schema
Element field (LoanAppl for this example) are filled in.
20. Click Next.
21. Click Finish.
You are returned to the Partner Link window. All other fields are automatically
completed. The window looks as follows:
Field
Value
Name
FirstReceivePL
WSDL File
file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorr
elationSet/FirstReceive.wsdl
Partner Link Type
Read_plt
My Role
Read_role
Partner Role
Leave unspecified.
22. Click OK.
6-16
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
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 6 on
page 6-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 File URL 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 File URL 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
SecondReceivePL
WSDL File
file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorr
elationSet/SecondFileRead.wsdl
Partner Link Type
Read1_plt
My Role
Read1_role
Invoking an Asynchronous Web Service 6-17
Using Correlation Sets in an Asynchronous Service
Field
Value
Partner Role
Leave unspecified.
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 6 on
page 6-16 and Step 6 on page 6-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 File URL 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 File URL field (Book1_6.xsd for this example) and the Schema
Element field (CustResponse 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:
6-18
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
Field
Value
Name
ThirdReceivePL
WSDL File
file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorr
elationSet/ThirdFileRead.wsdl
Partner Link Type
Read2_plt
My Role
Read2_role
Partner Role
Leave unspecified.
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 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:
Field
Value
Name
receiveFirst
Partner Link
FirstReceivePL
Create Instance
Select this check box.
Invoking an Asynchronous Web Service 6-19
Using Correlation Sets in an Asynchronous Service
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
Partner Link
ThirdReceivePL
Create Instance
Do not select this check box.
The Operation (Read2) field is automatically filled in.
6-20
4.
Click the first icon to the right of the Variable field.
5.
Click OK on the Create Variable window that appears.
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
A variable named receiveThird_Read2_InputVariable is automatically created in
the Variable field.
6.
Click OK.
When complete, the designer window looks as follows. 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 JDeveloper BPEL Designer.
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 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 JDeveloper
BPEL Designer.
2.
Right-click Correlation Sets and select Create Correlation Set.
Invoking an Asynchronous Web Service 6-21
Using Correlation Sets in an Asynchronous Service
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.
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
6-22
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.
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
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.
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.
Invoking an Asynchronous Web Service 6-23
Using Correlation Sets in an Asynchronous Service
6.
Click OK.
This groups the second and third receive activities into a second correlated group.
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 JDeveloper BPEL Designer.
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.
6-24
Click OK.
Oracle BPEL Process Manager Developer’s Guide
Using Correlation Sets in an Asynchronous Service
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.
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 Applications Navigator of
JDeveloper BPEL Designer:
<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"/>
Invoking an Asynchronous Web Service 6-25
Summary
</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:
<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 JDeveloper BPEL Designer is also provided.
6-26
Oracle BPEL Process Manager Developer’s Guide
7
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 6, "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 samples:
■
C:\orabpel\samples\tutorials\106.ParallelFlows
(for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\106.Pa
rallelFlows (for JDeveloper BPEL Designer)
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 7–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
Parallel Flow 7-1
Defining a Parallel Flow
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.
Figure 7–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>
7-2
Oracle BPEL Process Manager Developer’s Guide
Defining a Parallel Flow
</flow>
This example shows two sequences, but the flow activity can have many sequences.
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 JDeveloper BPEL Designer.
1.
Drag and drop a flow activity into a scope 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 9-4
describes scope activities in detail.
2.
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 7-3
Customizing the Number of Flow Activities by Using the flowN Activity
See Also: The following documentation for examples of creating
flow activities in JDeveloper BPEL Designer:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Flow Activity" on page C-7
■
"Sequence Activity" on page C-17
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 runtime based on the data available and logic within the
process. An index variable increments each time a new branch is created, until the
index variable reaches the value of N.
The flowN activity performs activities on an arbitrary number of data elements. As the
number of elements changes, the BPEL process 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 7–2 shows an Oracle BPEL Console 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.
7-4
Oracle BPEL Process Manager Developer’s Guide
Customizing the Number of Flow Activities by Using the flowN Activity
Figure 7–2 An Oracle BPEL Console View of the Execution of a flowN activity
Figure 7–3 shows how a flowN activity appears in JDeveloper BPEL Manager.
Parallel Flow 7-5
Customizing the Number of Flow Activities by Using the flowN Activity
Figure 7–3 FlowN Activity Setup in the Diagram View
Figure 7–4 shows the flowN Window, which appears when you double-click the
flowN activity.
Figure 7–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 C-8
7-6
Oracle BPEL Process Manager Developer’s Guide
Customizing the Number of Flow Activities by Using the flowN Activity
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
-->
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
Parallel Flow 7-7
Summary
expression="bpws:getVariableData('inputVariable','payload',concat('/client:Nflo
wHotelsProcessRequest/client:ListOfHotels/client:HotelName[',bpws:getVariableDa
ta('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
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.
7-8
Oracle BPEL Process Manager Developer’s Guide
8
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 7, "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 samples:
■
■
C:\orabpel\samples\demos\LoanDemo\LoanFlow (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\demos\LoanDemo\L
oanFlow (for JDeveloper BPEL Designer)
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 8-2 explains how to create switch activities.
Conditional Branching
8-1
Using a Switch Activity to Define Conditional Branching
■
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 8-4 describes while activities.
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 time-out. 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 11, "Events and Timeouts" explains this feature in detail.
Using a Switch Activity to Define Conditional Branching
In Chapter 7, 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 8–1 provides an overview of a BPEL conditional branching process that has
been defined in a switch activity.
Figure 8–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>
8-2
Oracle BPEL Process Manager Developer’s Guide
Using a Switch Activity to Define Conditional Branching
</assign>
</case>
<otherwise>
<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 JDeveloper BPEL Designer:
1.
Drag a switch activity from the Component Palette into your BPEL flow.
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.
2.
Right-click the first branch and select Edit from the menu.
The Switch Case window appears.
3.
Enter an XPath Boolean expression in the Expression field. For example:
bpws:getVariableDate(’loanOffer1’,’payload’,’/loanOffer/APR’) >
bpws:getVariableData(’loanOffer2’,’payload’,’/loanOffer/APR’)
4.
Enter this expression on one line. To use the XPath Expression Builder, click the
XPath Expression Builder icon above the Expression field.
The two loan offers that the LoanFlow tutorial uses are stored in the global
variables loanOffer1 and loanOffer2. Each loan offer variable contains the
loan offer’s APR. The BPEL flow must choose the loan with the lower APR. One of
the following switch activities takes place:
■
■
If loanOffer1 has the higher APR, then the first branch selects loanOffer2
by assigning loanOffer2’s payload to selectedLoanOffer’s payload.
If loanOffer1 does not have the lower APR than loanOffer2, then the
otherwise case assigns loanOffer1’s payload to selectedLoanOffer’s
payload.
Conditional Branching
8-3
Using a While Activity to Define Conditional Branching
See Also: The following documentation for examples of creating
switch activities in JDeveloper BPEL Designer:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Switch Activity" on page C-18
■
■
c:\orabpel\samples\references\Switch (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Switc
h (for JDeveloper BPEL Designer)
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 inJDeveloper BPEL Designer:
1.
Drag and drop a while activity from 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.
8-4
Oracle BPEL Process Manager Developer’s Guide
Summary
See Also: The following documentation for examples of defining a
while activity in JDeveloper BPEL Designer:
■
"While Activity" on page C-23
■
Oracle BPEL Process Manager Order Booking Tutorial
■
■
c:\orabpel\samples\references\While (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\While
(for JDeveloper BPEL Designer)
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
8-5
Summary
8-6
Oracle BPEL Process Manager Developer’s Guide
9
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
■
Eclipse BPEL Designer 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.
Fault Handling
9-1
See Also: The following samples:
■
■
■
■
C:\orabpel\samples\tutorials\107.Exceptions (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\107.Ex
ceptions (for JDeveloper BPEL Designer)
C:\orabpel\samples\demos\ResilientDemo (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\demos\ResilientD
emo (for JDeveloper BPEL Designer)
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
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 9–1 shows how a fault handler sets the credit rating variable at -1000.
9-2
Oracle BPEL Process Manager Developer’s Guide
Defining a Fault Handler
Figure 9–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>
</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.
Fault Handling
9-3
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 is one of the key BPEL development tools. A scope is 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 your BPEL flow by grouping functional structures together, allowing you to
collapse them into what appears to be a single element in the BPEL designer (either
JDeveloper BPEL Designer or Eclipse BPEL Designer).
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 the BPEL designer (either Eclipse BPEL Designer or JDeveloper
BPEL Designer), 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>
Figure 9–2 shows how the getCreditRating scope activity appears after you have
expanded it in Eclipse BPEL Designer.
9-4
Oracle BPEL Process Manager Developer’s Guide
Using the Scope Activity to Manage a Group of Activities
Figure 9–2 Expanded Scope Activity
Figure 9–3 shows how the scope activity appears when it is collapsed.
Figure 9–3 Collapsed Scope Activity
To add a scope activity using Eclipse BPEL Designer:
1.
From the BPEL Palette (by default, in the upper right corner of the Designer in the
Process Map view), click More Activities to open the full palette menu.
2.
Click and drag a scope activity into the Process Map.
Fault Handling
9-5
3.
Open the scope by double-clicking it or by single-clicking the + sign.
4.
Drag activities from the BPEL Palette to build the function within the scope.
You can also drag the activities composing a function from your existing flow in
the Process Map and drop them into the scope.
See Also: The following documentation for examples of creating
scope activities in JDeveloper BPEL Designer:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Scope Activity" on page C-16
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"/>
9-6
Oracle BPEL Process Manager Developer’s Guide
Returning External Faults
<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 C-19
Oracle_
Home\integration\orabpel\samples\references\Throw
(for JDeveloper BPEL Designer)
c:\orabpel\samples\references\Throw (for Eclipse BPEL
Designer)
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)
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 8, "Conditional Branching" for more information on
setting up the conditional structure
Chapter 5, "Invoking a Synchronous Web Service" for more
information on synchronous interactions
"Reply Activity" on page C-15
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
Fault Handling
9-7
operation on the same port type that normally receives the requested information,
with an invoke activity.
See Also:
■
■
Chapter 6, "Invoking an Asynchronous Web Service" for more
information on asynchronous interactions
"Invoke Activity" on page C-9
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
■
Oracle BPEL Process Manager Quick Start Guide
■
"Catch Activity" on page C-4
■
■
c:\orabpel\samples\references\Catch (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\Catch
(for JDeveloper BPEL Designer)
Using the Empty Activity to Insert No-Op Instructions into a Business Process
There is often a need to use an activity that does nothing. An example is when a fault
must be caught and suppressed. In this case, you can use the empty activity to insert a
no-op instruction into a business process. The syntax to use an empty activity is as
follows:
<empty standard-attributes>
standard-elements
</empty>
If no catch or catchAll is selected, the fault is not caught by the current scope and
is rethrown to the immediately enclosing scope. If the fault occurs in (or is rethrown
to) the global process scope, and there is no matching fault handler for the fault at the
global level, the process terminates abnormally. This is as though a terminate
activity (described in "Using the Terminate Activity to Stop a Business Process
Instance" on page 9-10) had been performed.
Consider the following example:
<faulthandlers>
<catch faultName="x:foo">
<empty/>
9-8
Oracle BPEL Process Manager Developer’s Guide
Using Compensation after Undoing a Series of Operations
</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:
■
"Catch Activity" on page C-4
■
"Empty Activity" on page C-6
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.
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.
Fault Handling
9-9
■
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: "Compensate Activity" on page C-5
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>
standard-elements
</terminate>
See Also: The following documentation for examples of creating
terminate activities:
■
"Terminate Activity" on page C-19
■
Oracle BPEL Process Manager Quick Start Guide
■
■
9-10
c:\orabpel\samples\references\Terminate (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\references\Termi
nate (for JDeveloper BPEL Designer)
Oracle BPEL Process Manager Developer’s Guide
Eclipse BPEL Designer Example
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
Oracle_Home\integration\orabpel\system\xmllib directory).
2.
Declare a variable with messageType bpelx:RuntimeFaultMessage.
3.
Catch it using <catch faultName="bpelx:remoteFault"
"bpelx:bindingFault" faultName="varName">.
|
See Also: The following sample, which describes how to handle
runtime binding faults:
■
■
C:\orabpel\samples\demos\ResilientDemo (for Eclipse
BPEL Designer)
Oracle_
Home\integration\orabpel\samples\demos\ResilientD
emo (for JDeveloper BPEL Designer)
Eclipse BPEL Designer Example
To define a fault handler in Eclipse BPEL Designer, follow these steps:
1.
Drag a scope activity from the BPEL Palette and place it just above the credit
rating invoke activity.
2.
Expand the scope activity by clicking its Expand button and drag the invoke
credit rating activity into the scope activity.
Fault Handling 9-11
At the bottom of the scope area, there are three icons: a caution sign, a lightning
bolt, and a clock. The caution sign represents a fault handler.
3.
9-12
Click the caution sign, and select Add catch from the menu.
Oracle BPEL Process Manager Developer’s Guide
Eclipse BPEL Designer Example
The New Catch Wizard window appears:
4.
Select the fault name and the fault variable from the lists provided.
This defines where the fault comes from and which fault activates the fault
handler.
5.
Drag an assign activity into the BPEL process below the catch activity.
Fault Handling 9-13
6.
Add copy rules to the assign activity. In the BPEL Inspector, select Add Copy Rule
from the menu.
This defines what the BPEL flow does when it receives the defined fault.
9-14
Oracle BPEL Process Manager Developer’s Guide
Summary
7.
Click the Upper Element button to return to the Process Map view.
See Also: The following documentation for examples of defining
fault handling:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
"Catch Activity" on page C-4
■
■
c:\orabpel\samples\references\Catch (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\Catch
(for JDeveloper BPEL Designer)
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.
Fault Handling 9-15
9-16
Oracle BPEL Process Manager Developer’s Guide
10
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:
■
Use Case for Incorporating Java and J2EE Code BPEL Processes
■
Overview of Java and J2EE Code in BPEL Concepts
■
Using Java Embedding in JDeveloper BPEL Designer
■
Summary
Use Case for Incorporating Java and J2EE Code BPEL Processes
This use case demonstrates how you can invoke a session bean from within a BPEL
process. In this sample, you design the BPEL process so that it picks up a Social
Security number from the payload, and then use a Java embedding activity to invoke
the session bean (called CreditRating) by using the Social Security number (called ssn)
as a parameter. The CreditRating session bean then returns the credit rating for the
given Social Security number.
See Also: The following examples:
■
C:\orabpel\samples\tutorials\111.CallingSessionBean
s (for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\111.Ca
llingSessionBeans\SessionBeanSample.bpel (for
JDeveloper BPEL Designer)
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
Incorporating Java and J2EE Code in BPEL Processes 10-1
Overview of Java and J2EE Code in BPEL Concepts
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:
■
■
It has less tool support than SOAP services (described next).
It has less interoperability, because each application server needs a specific
binding.
Currently, you must write the binding manually.
See Also:
■
C:\orabpel\samples\tutorials\702.Bindings for
Eclipse BPEL Designer or Oracle_
Home\integration\orabpel\samples\tutorials\702.Bi
ndings for JDeveloper BPEL Designer for examples of WSIF
bindings for EJB, HTTP, and Java. Bindings must be written to
match the application server.
■
C:\orabpel\samples\demos\BankTransferDemo\BankTrans
ferFlow (for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\demos\BankTransf
erDemo\BankTransferFlow (for JDeveloper BPEL Designer)
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
10-2
Oracle BPEL Process Manager Developer’s Guide
Overview of Java and J2EE Code in BPEL Concepts
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, the 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);
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>
Incorporating Java and J2EE Code in BPEL Processes 10-3
Overview of Java and J2EE Code in BPEL Concepts
See Also:
■
C:\orabpel\samples\tutorials\111.CallingSessionBean
s (for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\111.Ca
llingSessionBeans (for JDeveloper BPEL Designer)
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). 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:
■
c:\orabpel\bin (for Eclipse BPEL Designer)
■
Oracle_Home\integration\orabpel\bin (for JDeveloper BPEL Designer
To use schemac, run a command similar to the following to generate the facades from
WSDL or XSD files:
C:\BPEL_project_dir\> schemac *.wsdl /*.xsd
After you run schemac, it creates a src folder for a HelperService.java service
and a com folder for the generated Java classes. Oracle provides a sample in the
following directories that showcases the use of facade classes in Java bindings:
■
■
c:\orabpel\samples\tutorials\702.Bindings\JavaBinding (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\702.Bindings\JavaB
inding (for JDeveloper BPEL Designer)
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)
10-4
Oracle BPEL Process Manager Developer’s Guide
Overview of Java and J2EE Code in BPEL Concepts
■
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-23
bpelx:exec Built-in Methods
Table 10–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 10–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
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)
Incorporating Java and J2EE Code in BPEL Processes 10-5
Using Java Embedding in JDeveloper BPEL Designer
Table 10–1
(Cont.) Built in Methods for <bpelx:exec>
Method Name
Description
void setVariableData(String name,
String part, Object value)
void setVariableData(String name,
String part, String query, Object
value)
Using Java Embedding in JDeveloper BPEL Designer
In JDeveloper BPEL Designer, 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 dialog
box.
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 10-3 appears as
follows:
10-6
Oracle BPEL Process Manager Developer’s Guide
Summary
See Also: "Java Embedding Activity" on page C-10 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.
Incorporating Java and J2EE Code in BPEL Processes 10-7
Summary
10-8
Oracle BPEL Process Manager Developer’s Guide
11
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 in JDeveloper BPEL Designer
■
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 files:
■
■
C:\orabpel\samples\tutorials\108.Timeouts (for
Eclipse BPEL Designer)
Oracle_
Home\integration\orabpel\samples\tutorials\108.Ti
meouts (for JDeveloper BPEL Designer)
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.
Events and Timeouts 11-1
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.
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 11–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.
11-2
The pick activity condition that completes first is the one that the BPEL process
executes. The other branch then is not executed.
Oracle BPEL Process Manager Developer’s Guide
Using the Pick Activity to Select Between Continuing a Process or Waiting
Figure 11–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 11-3
See Also:
■
■
■
The following samples:
C:\orabpel\samples\references\Pick (for Eclipse BPEL
Designer)
Oracle_
Home\integration\orabpel\samples\references\Pick
(for JDeveloper BPEL Designer)
"Pick Activity" on page C-13
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 in JDeveloper BPEL Designer:
■
"Wait Activity" on page C-22
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\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 Oracle_
Home\integration\orabpel\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>
Note: For Eclipse BPEL Designer, domain.xml is located in the
c:\orabpel\domains\default\config directory.
Defining a Timeout in JDeveloper BPEL Designer
To define a timeout in JDeveloper BPEL Designer, follow these steps:
1.
Drag the pick activity from the Component Palette, and place it just before the
receive activity for the Star Loan service.
The pick activity includes the onMessage and onAlarm branches.
11-4
Oracle BPEL Process Manager Developer’s Guide
Defining a Timeout in JDeveloper BPEL Designer
2.
Double-click the OnAlarm branch of the onAlarm activity and set its time limit to
1 minute instead of 1 hour.
3.
Press OK when complete.
4.
Double-click the onMessage activity, and edit its attributes to receive the response
from the loan service.
Events and Timeouts 11-5
5.
For each of the onMessage and onAlarm branches, drag an empty assign activity
onto its Drop activity here area. In other instances, this space can contain
additional logic and processing.
See Also: "Pick Activity" on page C-13
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 the Star Loan service, and the other branch is
a timeout set at one minute.
11-6
Oracle BPEL Process Manager Developer’s Guide
12
Invoking a BPEL Process
This chapter shows how a JAVA or a 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 chapter’s 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 files:
■
C:\orabpel\samples\tutorials\102.InvokingProcesses
(for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\102.In
vokingProcesses (for JDeveloper BPEL Designer)
Overview of Invoking BPEL Process Concepts
This chapter shows how 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.
The tutorial at
http://www.oracle.com/technology/products/ias/bpel/p
df/orabpel-Tutorial7-InvokingBPELProcesses.pdf
See Also:
Invoking a BPEL Process 12-1
Sending Messages to a BPEL Process from a Java or JSP Application
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.
Figure 12–1 illustrates how an application interacts with a BPEL process through a
client partner link, using one of a number of possible protocols.
Figure 12–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 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.
12-2
Oracle BPEL Process Manager Developer’s Guide
Sending Messages to a BPEL Process from a Java or JSP Application
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
Locator locator = new Locator("default", "bpel", null);
IDeliveryService deliveryService = (IDeliveryService)locator.lookupService
(IDeliveryService.SERVICE_NAME );
Note: This instance code uses bpel as the domain password. If you
have changed the password from the default password, then you
must update the instance with the correct password.
See Also: "Changing the Default Domain Password" on page 19-7
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:
■
■
C:\orabpel\docs\apidocs (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\docs\apidocs (for JDeveloper BPEL
Designer)
Invoking a Two-Way Operation through the Java API
Once 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,
Invoking a BPEL Process 12-3
Sending Messages to a BPEL Process from a Java or JSP Application
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>
<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 samples:
■
C:\orabpel\samples\tutorials\102.InvokingProcesses\
jsp\invokeCreditRatingService.jsp (for Eclipse BPEL
Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\102.In
vokingProcesses\jsp\invokeCreditRatingService.jsp
(for JDeveloper BPEL Designer)
Invoking a One-Way Operation through 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:
12-4
Oracle BPEL Process Manager Developer’s Guide
Sending Messages to a BPEL Process from a Java or JSP Application
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);
out.println( "BPELProcess HelloWorld initiated!" );
%>
See Also: The following samples:
■
C:\orabpel\samples\tutorials\102.InvokingProcesses\
jsp\invokeHelloWorld.jsp (for Eclipse BPEL Designer)
■
Oracle_
Home\integration\orabpel\samples\tutorials\102.In
vokingProcesses\jsp\invokeHelloWorld.jsp (for
JDeveloper BPEL Designer)
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
C:\orabpel\samples\demos\LoanDemoPlus for Eclipse BPEL Designer or
Oracle_Home\integration\orabpel\samples\demos\LoanDemoPlus for
JDeveloper BPEL Designer) 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.
Invoking a BPEL Process 12-5
Sending Messages to a BPEL Process from a Java or JSP Application
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.
See Also: The following samples for examples of how to send e-mail
or JMS messages from BPEL processes:
If you are using Eclipse BPEL Designer:
■
C:\orabpel\samples\tutorials\116.SendEmails
■
C:\orabpel\samples\tutorials\118.JMSService\buyer
If you are using JDeveloper BPEL Designer:
■
Oracle_
Home\integration\orabpel\samples\tutorials\116.Se
ndEmails
■
Oracle_
Home\integration\orabpel\samples\tutorials\118.JM
SService\buyer
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 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.
12-6
Oracle BPEL Process Manager Developer’s Guide
Summary
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.
Invoking a BPEL Process 12-7
Summary
12-8
Oracle BPEL Process Manager Developer’s Guide
13
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 13–1 provides an overview.
Interaction Patterns 13-1
Synchronous Interaction
Figure 13–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 13–2 provides an
overview.
13-2
Oracle BPEL Process Manager Developer’s Guide
Asynchronous Interaction
Figure 13–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 5, "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 13–3 provides an overview.
Interaction Patterns 13-3
Asynchronous Interaction with Timeout
Figure 13–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
d2
<invoke>
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 6, "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 13–4 provides an overview.
13-4
Oracle BPEL Process Manager Developer’s Guide
Asynchronous Interaction with a Notification Timer
Figure 13–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.
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 described in "BPEL Process as the
Service" on page 13-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 13–5 provides an overview.
Interaction Patterns 13-5
One Request, Multiple Responses
Figure 13–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 described in "BPEL Process as the
Service" on page 13-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 13–6
provides an overview.
13-6
Oracle BPEL Process Manager Developer’s Guide
One Request, One of Two Possible Responses
Figure 13–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 13–7 provides an overview.
Interaction Patterns 13-7
One Request, a Mandatory Response, and an Optional Response
Figure 13–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.
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 13–8 provides an
overview.
13-8
Oracle BPEL Process Manager Developer’s Guide
Partial Processing
Figure 13–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 13-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 13–9 provides an overview.
Figure 13–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, and therefore needs a mechanism for keeping track of which message goes
where. Figure 13–10 provides an overview.
As with all partner activities, the WSDL file defines the interaction.
13-10 Oracle BPEL Process Manager Developer’s Guide
Summary
Figure 13–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 6-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
13-11
Summary
13-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 14, "XSLT Mapper and Transformations"
■
Chapter 15, "Oracle BPEL Process Manager Notification Service"
■
Chapter 16, "Oracle BPEL Process Manager Workflow Services"
■
Chapter 17, "Worklist Application"
■
Chapter 18, "Sensors"
14
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 a Transform Activity
■
The XSLT Mapper
■
Creating an XSL Map
■
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:
■
Oracle_
home\integration\orabpel\samples\demos\XSLMapper
■
Oracle_
home\integration\orabpel\samples\tutorials\114.XS
LTTransformations
■
Oracle BPEL Process Manager Order Booking Tutorial
Creating a Transform Activity
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. To create a transformation with these mappings, you first drag and drop a
transform activity from the Component Palette into your BPEL process diagram, as
shown in Figure 14–1.
XSLT Mapper and Transformations 14-1
Creating a Transform Activity
Figure 14–1
Invoking the Mapper from JDeveloper BPEL Designer
Double-click the transform activity. Figure 14–2 shows the Transform window.
Figure 14–2
14-2
Transform Window
Oracle BPEL Process Manager Developer’s Guide
The XSLT Mapper
Perform the following procedures
1.
Specify the following information:
■
■
■
■
2.
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
Target part of the variable (for example, a payload schema consisting of an
invoice) to which to map
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.
■
If the map file already exists, click the flashlight icon (first icon) to browse
mappings.
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.
■
■
If the map file does not exist, enter a name for the map file in the Mapper File
field and click the magic wand icon (second icon) to create a new mapping.
If the map file already exists and you want to edit it, click the note pad icon
(third icon) to edit the mapping.
Note: You can also create an XSL map file from an XSL stylesheet.
Click New, then XML, then XSL Map From XSL Stylesheet from the
File main menu in JDeveloper BPEL Designer.
See Also: The online Help for the Transform window for detailed
descriptions of the fields
The XSLT Mapper
You use the XSLT Mapper transformation tool to create the contents of a map file.
Figure 14–3 shows the layout of the XSLT Mapper.
XSLT Mapper and Transformations 14-3
The XSLT Mapper
Figure 14–3
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
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 14–3 (for example, type, cardinality, and so on).
The Functions Palette in the upper right of Figure 14–3 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:
14-4
■
One in the source panel
■
One in the target panel
Oracle BPEL Process Manager Developer’s Guide
Creating an XSL Map
■
One in the mapper pane or canvas in the middle
Right-click in 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.
Creating an XSL Map
The following steps provide a high level overview of how to create an XSL map using
the po.xsd and invoice.xsd files in the Oracle_
home\integration\orabpel\samples\demos\XSLMapper directory.
1.
In JDeveloper BPEL Designer, select the workspace project in which you want to
create the new XSL map.
2.
Add the po.xsd and invoice.xsd files to the project.
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.
6.
–
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).
Under Source, expand Project Schema Files, and then po.xsd. Select
PurchaseOrder as the root element for the source.
XSLT Mapper and Transformations 14-5
Using the XSLT Mapper
7.
Under Target, expand Project Schema files, and then invoice.xsd. Select Invoice
as the root element for the target.
8.
Click OK.
A new XSL map is created.
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
■
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 14–4.
14-6
Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 14–4
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 14–5).
5.
Click OK to save the text.
A T icon is displayed next to the node that has text associated with it.
6.
Figure 14–5
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.
Set Text Window
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
XSLT Mapper and Transformations 14-7
Using the XSLT Mapper
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:
Figure 14–6
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 Function Description. 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
handle on the concat function. Also drag a thread from the ShippedTo name and
connect it to the right handle on the concat function, as shown in Figure 14–6.
Using the Concat Function
See Also: The documentation for the XPath extension functions,
which is described in Appendix G, "XPath Extension Functions" and is
also accessible by clicking Manage BPEL Domain, and then XPath
Library in Oracle BPEL Console
14-8
Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
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 14–7
Editing Function Parameters
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 14–8.
The chaining function can also be defined by dragging and dropping the function to a
connecting link.
XSLT Mapper and Transformations 14-9
Using the XSLT Mapper
Figure 14–8
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, then XSL Maps from the Tools main
menu.
See Also: Oracle_
home\integration\orabpel\samples\demos\XSLMapper\Ext
ensionFunctions\README.txt for detailed instructions
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 14–9.
14-10 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 14–9
Editing XPath Expressions
When you double-click the icon, the Edit XPath Expression window appears, as shown
in Figure 14–10. You can press the Ctrl key and then the spacebar to invoke the XPath
Building Assistant.
Figure 14–10
Edit XPath Expression Window
Figure 14–11 shows the XPath Building Assistant.
XSLT Mapper and Transformations
14-11
Using the XSLT Mapper
Figure 14–11
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.
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 14–12 shows the results.
14-12 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 14–12
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 14–13 shows the results.
XSLT Mapper and Transformations
14-13
Using the XSLT Mapper
Figure 14–13
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 14–14 shows the results.
Figure 14–14
Handling Repetition or Arrays
14-14 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Note: 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.
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 14–15.
Figure 14–15
Auto Mapping
The behavior of the auto map can be tuned by altering the settings in JDeveloper BPEL
Designer preferences or by right-clicking the transformation window and selecting
Auto Map Preferences. This displays the window shown in Figure 14–16.
XSLT Mapper and Transformations
14-15
Using the XSLT Mapper
Figure 14–16
Auto Map Preferences
This window enables you to customize your auto mapping as follows:
■
■
■
■
■
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 14–17.
14-16 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 14–17
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 14–16 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 14–18. The
window enables you to filter one or more mappings.
XSLT Mapper and Transformations
14-17
Using the XSLT Mapper
Figure 14–18
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
The auto map confirmation window can also be turned on or off with Confirm Auto
Map Links in the context menu of the mapper pane, as shown in Figure 14–19.
14-18 Oracle BPEL Process Manager Developer’s Guide
Using the XSLT Mapper
Figure 14–19
Confirm Auto Map Links Selection
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 14–20 provides an example of the Completion Status window.
XSLT Mapper and Transformations
14-19
Using the XSLT Mapper
Figure 14–20
Completion Status
Generating Dictionaries
A dictionary is an XML file that captures the synonyms for mappings. Right-click the
mapper pane as shown in Figure 14–19 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, then XSL Maps,
then Auto Map in the Tools main menu of JDeveloper BPEL Designer.
5.
Perform an automatic mapping from the purchase order to the purchase order
acknowledgment.
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, then XSL Maps in the Tools
main menu of JDeveloper BPEL Designer.
14-20 Oracle BPEL Process Manager Developer’s Guide
Testing the Map
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 JDeveloper BPEL Designer after importing the file.
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, which enables you
to select the new source or target schema to use.
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 pane context sensitive
menu, as shown in Figure 14–21.
Figure 14–21
Invoking the Test Window
XSLT Mapper and Transformations
14-21
Testing the Map
Test Window
The Open button is used to load a sample XML instance file for testing. If you do not
have a source file or if you prefer the system to generate a random source instance,
you can click the Generate button. After you have a sample source instance, you can
generate the result document by clicking Test, as shown in Figure 14–22. This enables
the Target XML section to display the target XML.
Figure 14–22
Test Window
Note: By default, the Xalan XSL processor is used for testing XSL
mappings, If you want to use the Oracle XSL Processor to test
mappings, select Preferences, then XSL Maps in the Tools main menu
of JDeveloper BPEL Designer to change this setting in the Preferences
window.
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
14-22 Oracle BPEL Process Manager Developer’s Guide
Testing the Map
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 14–23.
Figure 14–23
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 Oracle_Home\integration\jdev\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, then XSL Maps in the Tools main menu of JDeveloper BPEL
Designer 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
XSLT Mapper and Transformations
14-23
Summary
than the value of the maxOccurs attribute for a particular element, the number of
occurrences created for that particular element is the maxOccurs value, not the
specified number.
■
Generate optional elements
If selected, any optional element (its attribute minOccurs set to a value of 0) is
generated the same way as any required element (its attribute minOccurs set to a
value greater than 0).
■
Maximum depth
To avoid the occurrence of recursion in sample XML generation caused by
optional elements, specify a maximum depth in the XML document hierarchy tree
beyond which no optional elements are generated.
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
■
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.
14-24 Oracle BPEL Process Manager Developer’s Guide
15
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 Notification Service in JDeveloper BPEL Designer
■
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,
JDeveloper BPEL Designer uses the notification service to alert users by voice 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 JDeveloper BPEL Designer and send an e-mail with an attachment.
See: Oracle_Home\integration\orabpel\samples\tutorials\
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 15-1
Configuring Notification Service in JDeveloper BPEL Designer
■
■
■
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, 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 15–1 shows the notification service interfaces and supported service types.
Figure 15–1
Notification Service Interfaces and Supported Service Types
Email
Server
Web Services
Interface
SMTP
IMAP/
POP
Fax
Server
Notification
Service
Java
Interface
SOAP
call
SMS
Server
Voice
Gateway
Oracle Application
Server Wireless
Server
Configuring Notification Service in JDeveloper BPEL Designer
The diagram view in JDeveloper BPEL Designer includes a Notification activity in the
Component Palette, as shown in Figure 15–2.
15-2
Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
Figure 15–2
Diagram View in JDeveloper BPEL Designer—Notification Activity
To use the notification service, do the following:
1.
In Diagram View, select Process Activities from the Component Palette list.
2.
Drag and drop a Notification activity from the Process Activities list (for this
example, to a position below receiveInput and above callbackClient in the
diagram).
The Notification Service wizard starts.
3.
Click Next on the Welcome window.
The Step 1 of 2: Select a Notification channel window appears.
Oracle BPEL Process Manager Notification Service 15-3
Configuring Notification Service in JDeveloper BPEL Designer
4.
Select a notification channel from the following options and click Next.
■
EMail
■
Voice
■
SMS
■
Fax
■
Pager
The next step depends on which notification channel you select.
See:
■
■
■
■
■
"The E-mail Notification Channel" on page 15-4 to configure
e-mail notification
"The Voice Notification Channel" on page 15-10 to configure voice
message notification
"The SMS Notification Channel" on page 15-12 to configure SMS
notification
"The Fax Notification Channel" on page 15-13 to configure fax
notification
"The Pager Notification Channel" on page 15-14 to configure
pager notification
The E-mail Notification Channel
When you select Email for the notification channel, the Notification Service Wizard Step 2 of 2: Specify Email Parameters window appears. Figure 15–3 shows the required
e-mail notification parameters.
15-4
Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
Figure 15–3
1.
Notification Service Wizard - Step 2 of 2: Specify Email Parameters Window
Enter information for each field as described in Table 15–1.
Table 15–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.
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 15-15.
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, or a combination. The XPath Expression Builder can be
used to set dynamic text based on data from process variables
that you specify. Dynamic data is automatically enclosed in <%
%> when you use the XPath Expression Builder with free text.
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 15-6.
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 Next, then Finish.
The BPEL fragment that invokes the notification service to send the e-mail
message is created.
Oracle BPEL Process Manager Notification Service 15-5
Configuring Notification Service in JDeveloper BPEL Designer
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.
Run the Notification Service wizard and select Email for the channel.
2.
Specify values for To, Subject, and Body.
3.
Select Multipart and enter 2 for the number of attachments. (Note that the number
of attachments must include the body part.)
4.
The Notification Service wizard generates the MultiPart element with two body
parts. The first body part is for the message body and the other is used for the
attachment. The Notification Service wizard generates the BPEL fragment with an
assign activity with multiple copy rules. One of the copy rules copies the
attachment, as follows:
<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>
15-6
Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
</ContentBody>
</Content>
</from>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content"/>
</copy>
<copy>
<from expression="string('text/html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/
ns1:MimeType"/>
</copy>
<copy>
<from expression="string('NotificationAttachment1.html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/ns1:BodyPartName"/>
</copy>
<copy>
<from expression="string(‘This is a test message from John Cooper')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[1]/
ns1:ContentBody"/>
</copy>
<copy>
<from expression="string('text/html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:MimeType"/>
</copy>
<copy>
<from expression="string('NotificationAttachment2.html')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:BodyPartName"/>
</copy>
<copy>
<from expression="string('message2')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:
MultiPart/ns1:BodyPart[2]/
ns1:ContentBody"/>
</copy>
</assign>
5.
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’).
Oracle BPEL Process Manager Notification Service 15-7
Configuring Notification Service in JDeveloper BPEL Designer
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
:MimeType"/>
</copy>
<copy>
<from expression="string('MyImage.gif')"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1
:BodyPartName"/>
</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
:ContentBody"/>
</copy>
See: Oracle_
Home\integration\orabpel\samples\tutorials\130.SendEmail
WithAttachments for an example of sending attachments using e-mail
Configuring the E-mail Server
The file ns_emails.xml in the directory Oracle_
Home\integration\orabpel\system\services\config contains the
configuration for e-mail accounts. Each EmailAccount element sets the configuration
of a specific e-mail account. The name attribute in the EmailAccount element is the
name of the account.
A default e-mail account is specified in the e-mail configuration file. This account is
used when there is no account specified to send an e-mail notification. This account is
also used to send task-related notifications. A default e-mail account must always be
specified in the configuration file.
The EmailAccount element contains the OutgoingServerSettings and
IncomingServerSettings attributes. For actionable notifications in a workflow,
both IncomingServerSettings and OutgoingServerSettings are required.
Table 15–2 describes the XML elements for the e-mail notification configuration stored
in the ns_emails.xml file.
15-8
Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
Table 15–2
XML Elements for the E-mail Notification Configuration File
Name
Description
EmailAccount/Name
Name of the account. This can be any name, but
must be unique within this server.
EmailAccount/GeneralSettings/FromNa Name of the From e-mail address
me
EmailAccount/GeneralSettings/FromAd E-mail address for the From e-mail address
dress
EmailAccount/OutgoingServerSettings Name of the outgoing SMTP server
/SMTPHost
EmailAccount/OutgoingServerSettings Port of the outgoing SMTP server
/SMTPPort
EmailAccount/IncomingServerSettings Name of the incoming e-mail server
/Server
EmailAccount/IncomingServerSettings Port of the incoming e-mail server
/Port
EmailAccount/IncomingServerSettings User ID of the e-mail address
/UserName
EmailAccount/IncomingServerSettings User password
/Password
EmailAccount/IncomingServerSettings Encrypted attribute of the password. It is true if
the password is encrypted and false if it is not.
/Password[encrypted
Generally, you should set this to false when you
first enter the password. The server automatically
encrypts the password the first time it reads the
configuration file and sets the attribute to true.
EmailAccount/IncomingServerSettings Secure sockets layer (SSL) attribute. It is true if the
incoming server requires SSL and false if it does
/UseSSL
not.
EmailAccount/IncomingServerSettings Name of the folder from which to read the incoming
messages
/Folder
EmailAccount/IncomingServerSettings Polling interval for reading messages from the
incoming messages folder
/PollingFrequency
Example ns_emails.xml File
EmailAccounts xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<EmailAccount>
<Name>Default</Name>
<GeneralSettings>
<FromName>Oracle BPM</FromName>
<FromAddress>bpm1@dlsun4254.us.oracle.com</FromAddress>
</GeneralSettings>
<OutgoingServerSettings>
<SMTPHost>dlsun4254.us.oracle.com</SMTPHost>
<SMTPPort>225</SMTPPort>
</OutgoingServerSettings>
<IncomingServerSettings>
<Server>dlsun4254.us.oracle.com</Server>
<Port>2110</Port>
<Protocol>pop3</Protocol>
<UserName>bpm1</UserName>
<Password ns0:encrypted="false"
Oracle BPEL Process Manager Notification Service 15-9
Configuring Notification Service in JDeveloper BPEL Designer
xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">welcome
</Password>
<UseSSL>false</UseSSL>
<Folder>Inbox</Folder>
<PollingFrequency>1</PollingFrequency>
<PostReadOperation>
<MarkAsRead/>
</PostReadOperation>
</IncomingServerSettings>
</EmailAccount>
</EmailAccounts>
The Voice Notification Channel
When you select Voice for the notification channel, the Notification Service Wizard Step 2 of 2: Specify Voice Parameters window appears. Figure 15–4 shows the required
voice notification parameters.
Figure 15–4
1.
Notification Service Wizard - Step 2 of 2: Specify Voice Parameters Window
Enter information for each field as described in Table 15–3.
Table 15–3
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, or a combination. The XPath
Expression Builder can be used to set dynamic text based on
data from process variables that you specify. Dynamic data is
automatically enclosed in <% %> when you use the XPath
Expression Builder with free text.
2.
Click Next, then Finish.
15-10 Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
The BPEL fragment that invokes the notification service for voice notification is
created.
Configuring the Wireless Service Provider for Voice
The configuration for the wireless service provider is stored in an XML file, ns_
iaswconfig.xml, which is in
Oracle_Home\integration\orabpel\system\services\config
Table 15–4 describes the XML elements for the voice notification configuration stored
in ns_iaswconfig.xml on the Oracle_Home server.
Table 15–4
XML Elements for the Voice Notification Configuration File
Name
Description
/IASWConfiguration/SoapURL
URL of the wireless service provider
/IASWConfiguration/UserName
Name of the user account with the wireless service
provider
/IASWConfiguration/Password
User password
/IASWConfiguration/Password[encr
ypted
Encrypted attribute of the password. It is true if the
password is encrypted and false if it is not. Generally,
you should set this to false when you first enter the
password. The server automatically encrypts the
password the first time it reads the configuration file
and sets the attribute to true.
/IASWConfiguration/ProxyHost
Name of the proxy server
/IASWConfiguration/ProxyPort
Port number of the proxy server
Note: The username and password are intentionally left blank at
installation. If a username or password is not specified, the wireless
server allows up to 50 notifications from a specific IP address. After 50
notifications, you must get a paid account from
http://messenger.oracle.com
You then specify the appropriate username and password in the
configuration file, ns_iaswconfig.xml, or by using Oracle
Enterprise Manager 10g Application Server Control Console.
Example ns_iaswconfig.xml File
<?xml version = '1.0' encoding = 'UTF-8'?>
<!--This XML file stores the details of the IAS Wireless Notification Service-->
<IASWConfiguration xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<!-- URL to the SOAP Service -->
<SoapURL>http://messenger.oracle.com/xms/webservices</SoapURL>
<!-- UserName - this username should exist in iAS Wireless schema -->
<UserName>username</UserName>
<Password ns0:encrypted="false"
xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">password
</Password>
</IASWConfiguration>
Oracle BPEL Process Manager Notification Service
15-11
Configuring Notification Service in JDeveloper BPEL Designer
The SMS Notification Channel
When you select SMS for the notification channel, the Notification Service Wizard Step 2 of 2: Specify SMS Parameters window appears. Figure 15–5 shows the required
SMS notification parameters.
Figure 15–5
1.
Notification Service Wizard - Step 2 of 2: Specify SMS Parameters Window
Enter information for each field as described in Table 15–5.
Table 15–5
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 15-15.
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, or a combination. The XPath Expression Builder can be
used to set dynamic text based on data from process variables
that you specify. Dynamic data is automatically enclosed in <%
%> when you use the XPath Expression Builder with free text.
Body
SMS message body. This must be plain text. This can be free text
or dynamic text as described for the Subject parameter.
2.
Click Next, then Finish.
The BPEL fragment that invokes the notification service for SMS notification is
created.
15-12 Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
Configuring the Wireless Service Provider for SMS
As with the voice notification channel, the configuration for the wireless service
provider for SMS is stored in the XML file ns_iaswconfig.xml, which is in
Oracle_Home\integration\orabpel\system\services\config
See "Configuring the Wireless Service Provider for Voice" on page 15-11 to configure a
wireless service provider for SMS.
The Fax Notification Channel
When you select Fax for the notification channel, the Notification Service Wizard - Step
2 of 2: Specify Fax Parameters window appears. Figure 15–6 shows the required fax
notification parameters.
Figure 15–6
1.
Notification Service Wizard - Step 2 of 2: Specify Fax Parameters window
Enter information for each field as described in Table 15–6.
Table 15–6
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. Dynamic data is
automatically enclosed in <% %> when you use the XPath
Expression Builder with free text.
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.
Oracle BPEL Process Manager Notification Service
15-13
Configuring Notification Service in JDeveloper BPEL Designer
2.
Click Next, then Finish.
The BPEL fragment that invokes the notification service for fax notification is
created.
Configuring the Fax Cover Page
To add cover pages for a fax, you must edit the Oracle_
Home\integration\orabpel\system\services\config\ns_
faxcoverpages.xml. Use the cover page name to specify the cover page in the fax
message.
<FaxCoverPages xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
<FaxCoverPage>
<Name>legal</Name>
<MimeType>application/pdf</MimeType>
<FileLocation>C:\orabpel\integration\bpm\runtime\config\faxcoverpages\003288.pdf</
FileLocation>
</FaxCoverPage>
</FaxCoverPages>
Configuring the Wireless Service Provider for Fax
As with the voice notification channel, the configuration for the wireless service
provider for fax is stored in the XML file ns_iaswconfig.xml, which is in
Oracle_Home\integration\orabpel\system\services\config
See "Configuring the Wireless Service Provider for Voice" on page 15-11 to configure a
wireless service provider for fax. Note that you cannot use the Oracle Enterprise
Manager 10g Application Server Control Console to configure a fax provider for this
release.
The Pager Notification Channel
When you select Pager for the notification channel, the Notification Service Wizard Step 2 of 2: Specify Pager Parameters window appears. Figure 15–7 shows the required
pager notification parameters.
Figure 15–7
Notification Service Wizard - Step 2 of 2: Specify Pager Parameters window
15-14 Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
1.
Enter information for each field as described in Table 15–7.
Table 15–7
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 Next, then Finish.
The BPEL fragment that invokes the notification service for pager notification is
created.
Configuring the Wireless Service Provider for Pager
As with the voice notification channel, the configuration for the wireless service
provider for pager is stored in the XML file ns_iaswconfig.xml, which is in
Oracle_Home\integration\orabpel\system\services\config
See "Configuring the Wireless Service Provider for Voice" on page 15-11 to configure a
wireless service provider for pager. Note that you cannot use the Oracle Enterprise
Manager 10g Application Server Control Console to configure a pager provider for this
release.
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:
Oracle BPEL Process Manager Notification Service
15-15
Configuring Notification Service in JDeveloper BPEL Designer
ora:getUserProperty(userID, propertyName)
The first argument evaluates to the user ID. The second argument is the property
name. Table 15–8 lists the property names that can be used in this XPath function.
Table 15–8
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:
ora:getUserProperty(bpws:getVariableData(‘inputVariable’,
‘payload’,‘/client:BPELProcessRequest/client:userid’), ‘mail’)
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
"Selecting Users or Groups by Browsing the User Directory" on page 16-23 for more
information on 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 15–9, " E-mail Activation Element and Respective Attributes in
bpel.xml" and "The activationAgents Element Structure in bpel.xml" on
page 15-17.
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 15-17.
Table 15–9 describes the activationAgents element and activationAgent
attributes of the activation fragment contained in the bpel.xml file.
15-16 Oracle BPEL Process Manager Developer’s Guide
Configuring Notification Service in JDeveloper BPEL Designer
Table 15–9
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
gent/property
is test_account, then the test_account.xml file is included in all
name=”accountName”
the e-mail-related information.
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">
<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>
Oracle BPEL Process Manager Notification Service
15-17
Summary
-->
</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 Console, 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.
15-18 Oracle BPEL Process Manager Developer’s Guide
16
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:
■
Overview of Workflow Services
■
Use Cases for Workflow Services
■
Workflow Patterns
■
Task Notifications
■
Payload Display
■
Configuration for Task Service
■
Identity Service
■
Workflow-Related XPath Extension Functions
■
Approver Functions
■
Vacation Request Example
■
Summary
See Also: Appendix F, "Demo User Community" for the
organizational hierarchy of the demonstration user community used
in examples throughout this chapter
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 16–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 (Worklist
Application).
Oracle BPEL Process Manager Workflow Services 16-1
Overview of Workflow Services
Figure 16–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
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
Features of workflow services include:
■
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 and the ability to archive and
purge task details based on specified policies
–
JSP-based forms for viewing and updating task details
See Also: "Workflow Patterns" on page 16-8
■
Multiple workflow patterns—includes standard patterns such as simple approval,
sequential approval, parallel approval, and so on. Variations on workflow patterns
such as automatic escalation, renewal, and reminders are also supported. You can
also mix and match patterns to create complex patterns.
See Also: "Workflow Patterns" on page 16-8
■
Identity service—interacts with back-end identity management systems to capture
all user information from Java AuthoriZatioN (JAZN) and LDAP. Identity services
provide 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 16-77
16-2
Oracle BPEL Process Manager Developer’s Guide
Overview of Workflow Services
■
Notification service—notifies users of assigned tasks and task changes using
various delivery channels, such as e-mail, voice message, fax, pager, or SMS. With
notification service, you can also do the following:
–
Customize the notification content for different types of tasks
–
Perform actions on tasks using e-mail
See Also: Chapter 15, "Oracle BPEL Process Manager
Notification Service"
■
The Worklist Application—enables you to access tasks and act on them. The
Worklist Application can be extended or customized based on the application.
With the Worklist Application, you can do the following:
–
View tasks assigned to a user or role
–
Perform authorized actions on tasks in the worklist
–
Filter tasks based on various criteria
–
Acquire and check out shared tasks
See Also: Chapter 17, "Worklist Application"
Workflow Functionality: A Procurement Process Example
The functionality of workflow services can be illustrated using a simple procurement
business process, as shown in Figure 16–2. The business process receives a purchase
list of items from an employee and invokes the approved vendor’s pricing service to
determine the total cost to purchase those items. Then a task is assigned to the
employee’s manager. The manager reviews the total purchase cost and approves or
rejects the request. The activities related to task assignment and getting the outcome of
the task are performed within a scope to separate human workflow from the
automated workflow. If the request is approved, then the vendor’s order service is
invoked to place the order for the requested items. The employee is notified whether
the request is approved (with the order confirmation number received from the order
service) or rejected. This requires a directory service lookup to determine user
information. When the task is assigned to the manager, the manager may need to be
notified that a task is waiting for approval. This requires the invocation of a
notification service. The manager uses the Worklist Application to determine the
details of the task (what approval is being requested and the amount requested) and
then approves it.
Oracle BPEL Process Manager Workflow Services 16-3
Overview of Workflow Services
Figure 16–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
Workflow Services Components
Figure 16–3 shows the following workflow services components:
■
TaskActionHandler
All workflow business processes use the services of a business process called
TaskActionHandler to put items on a user’s worklist and get responses from users.
This process also maintains the timer events like task expiration, task reminder,
and so on. This business process is predeployed in Oracle BPEL Server. See
Appendix B, "Workflow and Notification Reference" for more information.
■
TaskManagementService
This 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/reassign tasks, and so on. The task service is used by the
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. Task service consists of the following services.
See Appendix B, "Workflow and Notification Reference" for more information.
16-4
Oracle BPEL Process Manager Developer’s Guide
Overview of Workflow Services
■
TaskRoutingService
The TaskRoutingService offers services to route, escalate, and reassign the task. See
Appendix B, "Workflow and Notification Reference" for more information.
■
Identity service
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. See "Identity Service" on page 16-77 for more
information.
■
Worklist Application service
The Worklist Application is a sample Web-based application that provides the
ability to retrieve tasks based on a variety of filter criteria and to perform task
actions on the selected tasks. See Chapter 17, "Worklist Application" for more
information.
■
Notification service
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 Chapter 15, "Oracle BPEL Process Manager
Notification Service" for more information.
Figure 16–3
Workflow Services Components
Workflow Services
Task
Action
Handler
Identity
Service
Portal
Users
BPEL
Process
Worklist
Task
Management
Service
Worklist
Service
E-mail Client
Task
Routing
Service
Identity
Management
· OID
· LDAP
· JAZN
Notification
Service
Database
Notification
Channels
· E-mail
· Application Server Wireless
- Voice
- SMS
Figure 16–4 shows the interactions between the services and the business process.
Oracle BPEL Process Manager Workflow Services 16-5
Use Cases for Workflow Services
Figure 16–4
Workflow Services and Business Process Interactions
BPEL Engine
Business
Process
TaskActionHandler
Process
Manages task
life cycle
Worklist application
Web application to search
for tasks, view tasks, act
on tasks
Task Manager and Task
Routing Service
Provides task persistence,
taskescalation /
reassignment based on
user info, APIs to
retrieve tasks based on
specified criteria, role
resolution, send
notifications
Worklist Service
Retrieve tasks based on
specified filter, sort tasks,
retrieve task attachments,
and perform actions on
selected tasks
Workflow Services
Identity Service
Provides:
· user/group/role
lookup
· user authentication
· authorization
Notification Service
Sends notification to users
by e-mail, voice message,
or short message service
User Directory
(one of)
Oracle
Internet
Directory
JAZN
XML
LDAP,
Custom
Use Cases for Workflow Services
Using workflow services is demonstrated in the VacationRequest,
LoanDemoPlusWithWorkflow, DocumentReview, and HelpDeskServiceRequest
demos.
See: Oracle_Home\integration\orabpel\samples\demos
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 16–5, is described in the VacationRequest sample.
16-6
Oracle BPEL Process Manager Developer’s Guide
Use Cases for Workflow Services
Figure 16–5
BPEL
Process
Assigning Tasks to a User or Role from a Directory
Assign Task
Workflow
Services
Task Complete
OID
LDAP
Using the Various Flow Patterns
A task may be routed through multiple users through a sequential flow, a parallel
flow, or an adhoc flow. 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 16–6, is described in the LoanDemoPlusWithWorkflow
sample.
Figure 16–6
Flow Patterns and Routing Policies
Workflow Service
Get Approvals
BPEL
Process
Change Routing
All Approvals
Complete
Various
Routing
Patterns
See "Workflow Patterns" on page 16-8 for the various flow patterns supported by
workflow services. You can use these patterns as building blocks to create complex
workflows.
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 16–7. For example, consider a support call, which is part of the
Oracle BPEL Process Manager Workflow Services 16-7
Workflow Patterns
HelpDeskServiceRequest process. A high-priority task may be assigned to a certain
user and if the user does not respond in 2 days, then the task is routed to the manager
for further action.
Figure 16–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
The Worklist Application
Users typically access tasks assigned to them by using the Worklist Application, as
shown in Figure 16–8. A worklist consists of tasks assigned to the user 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 Worklist Application can be customized and
extended based on the specific needs of an application. See Chapter 17, "Worklist
Application" for details about worklist functionality and the sample Worklist
Application.
Figure 16–8
Reports
Oracle BPEL Worklist Application—Access Tasks, Forms, Attachments, and
Workflow Services
List Work Items
Complete Task
Get Weekly
Productivity
Report
Task Details
and History
Workflow Patterns
Oracle BPEL Process Manager provides a library of workflow patterns. You can choose
a pattern that meets your business requirement and model your workflow based on
the pattern. Oracle BPEL Process Manager supports the following patterns:
■
16-8
Simple workflow (single-user task)—used for a business process that requires a
user's action (or inaction if the user does not act on the task within the allotted
Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
time). Based on the user's action or inaction, the business process modeler defines
what the business process does. See "Simple Workflow" on page 16-31 for more
information.
■
■
■
■
■
■
■
■
■
■
Simple workflow with escalation (extension of a single-user task)—used to
escalate the task, to the user's manager for example, if the user does not respond
within the allotted time. See "Simple Workflow with Automatic Escalation" on
page 16-33 for more information.
Simple workflow with renewal (extension of a single-user task)—used to extend
the expiration period if the user does not respond within the allotted time. The
business process modeler specifies how many times the task can be renewed
before it expires. See "Simple Workflow with Automatic Renewal" on page 16-37
for more information.
Sequential workflow—used to route tasks to multiple users in a sequence. The
business process modeler specifies the participants for the task as a list or a
management chain. See "Sequential Workflow" on page 16-40 for more
information.
Sequential workflow with escalation (extension of a sequential workflow)—used
to escalate the task if a user does not take action within the allotted time. See
"Sequential Workflow with Escalation" on page 16-47 for more information.
Parallel workflow—used when multiple users, working in parallel, must take
action, such as in a hiring situation when multiple users vote to hire or reject an
applicant. The business process modeler specifies the voting percentage that is
needed for the outcome to take effect, for example, a majority vote or a unanimous
vote. See "Parallel Workflow" on page 16-49 for more information.
Parallel workflow with final reviewer (extension of parallel workflow)—used
when a task is first sent to multiple users in parallel and then sent to a final
reviewer for a decision. See "Parallel Workflow with Final Reviewer" on page 16-52
for more information.
Adhoc (or dynamic) workflow—used to assign a task to one user first, who then
decides where the task goes next. The task is routed until one of the assignees
completes it and does not route it further. See "Adhoc Workflow" on page 16-54 for
more information.
FYI task—used when a task is sent to a user, but the business process does not
wait for a user response; it just continues. See "FYI Tasks" on page 16-56 for more
information.
User Task 2.0 Macro—supports user tasks from Oracle BPEL Process Manager
release 2.0. This user task requires the business process modeler to explicitly assign
task properties and also requires a custom application to view and act on tasks.
The User Task 2.0 Macro is available for backward compatibility and is replaced
with the new workflow services and patterns in this release. See "The User Task 2.0
Macro" on page 16-57 for more information.
Task continuation—used to build complex workflow patterns using the task
continuation (extension) concept. Task continuation allows one workflow to be
continued with another workflow, thus creating a mix of the previously described
patterns to create complex workflows. See "Task Continuations" on page 16-57 for
more information.
Oracle BPEL Process Manager Workflow Services 16-9
Workflow Patterns
The Modeling Process
Using the JDeveloper BPEL Designer component of Oracle BPEL Process Manager,
you can model workflow by specifying parameters and answering questions posed by
the Workflow wizard.
Modeling a workflow is a five-step process:
1.
Specify the workflow pattern.
2.
Specify task details and configurations.
Add the task title, payload, expiration parameter, outcomes, and so on.
3.
Specify the assignment policy.
Assign the task to the user, role, or group, and indicate whether it is a static or
dynamic assignment.
See "Task Assignment" on page 16-19 for more information.
4.
Specify the pattern-specific policies.
Each pattern defines policies specific to the pattern. For example, sequential
workflow requires routing rules, which may be based on management levels,
titles, and the outcomes that cause a task to be routed further.
5.
Specify task notification.
Notifications are sent to alert users of changes to the state of a task. Notifications
can be sent by e-mail, telephone voice message, fax, pager, or SMS.
See "Task Notifications" on page 16-61 and Chapter 15, "Oracle BPEL Process
Manager Notification Service" for more information.
The end result of specifying the parameters is the generation of a BPEL scope that uses
BPEL constructs to orchestrate the workflow. The Workflow wizard in JDeveloper
BPEL Designer automatically generates the BPEL fragment and task configuration, as
shown in Figure 16–9.
16-10 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–9
Pattern-Based Modeling
JDeveloper
BPEL
Designer
1
Model workflow pattern
Workflow Service
BPEL Process
Task Row
Sequential, parallel,
Adhoc, FYI ...
<receive>
Initiate
Task Details
Title:
Priority:
Creator:
Expiration Date:
Outcomes:
<invoke>
assignTask
2a Automatically
generates
BPEL
fragment
<receive>
onTaskComplete
Form
(payload
display)
Check
Outcome
Routing Slip
(assignment
policy)
setPayload
Notifications
2b Automatically
configures
task and
routing slip
for workflow
service
OID
LDAP
Calendar
1 2
7
Escalation
Rules
End
3
4 5
6
8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30
Editing or Deleting a Workflow
To edit a workflow, you manually edit the invoke and assign activities that are created
when you configure the workflow pattern. For each workflow pattern described in this
chapter, see the discussion on customization for more information.
To delete a workflow, you delete the scope and search block, which automatically
deletes the variables, partner links, and so on.
Task Details and Configurations
When you model a workflow, you specify the values for task attributes such as title,
payload, expiration, and configuration for the task. The configuration includes
possible outcomes of the task, payload display, and so on. The task attributes are
assigned using the BPEL assign activity. The task configuration is captured in an XML
file. The XML file is named taskConfigworkflow_name.xml and is available as
part of the JDeveloper project.
Task Attributes
The following task attributes are shown in Figure 16–10 and Figure 16–11.
■
Task Title (required)
The task title is used to display the task in Oracle BPEL Worklist Application. The
title can include static strings and data from other business process variables.
■
Payload (required)
The task payload is the data in the task. The payload is restricted to BPEL
variables and its substructures.
Oracle BPEL Process Manager Workflow Services
16-11
Workflow Patterns
■
Payload Display (required)
The payload display identifies the display mechanism for the payload in the
Worklist Application. Auto generated JSP form is the default option in which a
JSP is generated by inferring the schema of the selected payload.
Use the XSL file option to specify an XSL file for the payload display. If you select
to use an XSL style sheet generated by an external utility, you must make the
following modifications:
■
■
Add namespaces relating to the task and its requirements to the generated
XSL.
Ensure that all XPath queries start with the task payload in place of the root of
the XML.
Use the JSP URL option to specify your own JSP that can be used to display the
payload. See "Payload Display" on page 16-66 for more information.
■
Task Creator (optional)
The creator of the task is the user who initiates the task. The creator can be defined
using the XPath Expression Builder. The creator can view the tasks they created
from the Worklist Application if they have access to the application. The creator
can perform some actions specific to the creator from the Worklist Application,
such as withdraw the task. If the creator is not specified, it defaults to the task
owner.
■
Expiration Duration
The expiration duration is the maximum duration that the task can be open. This
is optional for some workflow patterns and is required for other workflow
patterns (such as auto-escalate).
■
Task Priority
If you select the advanced options in the Workflow wizard, you can 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.
■
Task Owner (optional)
The task owner can view the 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. This optional attribute defaults to
the system user bpeladmin if not specified. The task owner can be specified in
the advanced screens.
■
Identification Key (optional)
The identification key can be used as a user-defined identification 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
Worklist Application by the identification key. This attribute has no default value.
16-12 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–10
Workflow Wizard: Task Details
Figure 16–11
Workflow Wizard: Optional Task Details
Task Outcomes
The task outcomes capture the possible outcomes of a task such as Accept, Reject, and
Approve. The outcomes of the task are specified during the creation of the workflow.
The Worklist Application displays these outcomes as the possible actions that a user
can perform. You can select one of the seeded outcomes as the possible actions that a
user can perform. The task outcomes can also have display values that are different
Oracle BPEL Process Manager Workflow Services
16-13
Workflow Patterns
from the actual outcome value. This permits outcomes to be internationalized. See
"Resource Bundles" on page 16-19 for more information about internationalization.
Figure 16–12 shows where the conclusions are added. By default, JDeveloper BPEL
Designer displays common outcomes from the following file, which can be changed to
modify the default list of outcomes:
Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\TaskConclusion.xml
Figure 16–12
Task Outcomes
After the workflow is created, you can change the custom actions in the
conclusions element of the task configuration XML file, as shown in bold in the
following code example.
<taskType ....>
<task ...>
<conclusions>
<conclusion name="ACCEPT">
<displayValue>Accept</displayValue>
</conclusion>
<conclusion name="REJECT">
<displayValue>Reject</displayValue>
</conclusion>
</conclusions>
...
</task>
<notifications>
...
</notifications>
</taskType>
Advanced Task Configurations
The task also has the following optional configurations. All these configurations are
captured in the task configuration file. The following configurations are available
through the advanced options in the workflow.
■
Flex Fields
■
Restricted Actions
16-14 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
■
Version-Tracking Attributes
■
Task Notifications and Reminders
■
Resource Bundles
Flex Fields The task object contains flex fields for extending the task to capture any data
in addition to the payload. These flex fields are treated like other header attributes in
the worklist. Tasks can be searched based on data in any of the flex fields. Flex fields
are available for each of the following data types: string, double, long, and date.
When modeling the business process, you can specify which flex fields are used and a
display string for the flex fields. The display value is used by the Worklist Application
for the data (instead of using the name of the flex field itself). This also permits display
values to be internationalized. See "Resource Bundles" on page 16-19 for more
information on internationalization. Figure 16–13 shows how you configure flex fields.
Only the flex fields that are configured in this window are displayed in the Worklist
Application.
Figure 16–13
Task Flex Fields
You can change flex field information in the flexFields element of the task
configuration XML file, as shown in bold in the following code example.
<taskType ....>
<task ...>
...
<flexFields>
<flexField name="flexString2">
<displayValue>displayfor flex string</displayValue>
</flexField>
</flexFields>
...
Oracle BPEL Process Manager Workflow Services
16-15
Workflow Patterns
</task>
<notifications>
...
</notifications>
</taskType>
The following flex fields are available:
■
flexString1
■
flexString2
■
flexString3
■
flexString4
■
flexLong1
■
flexLong2
■
flexDouble1
■
flexDouble2
■
flexDate1
■
flexDate2
■
flexDate3
The Workflow wizard in JDeveloper BPEL Designer does not capture the assignment
to the flex fields. The assignments to the flex fields can be manually added in the
workflow BPEL scope. In every workflow that is generated, an assign named
setUserDefinedAttributes in the scope is generated for the workflow. The
assignments to the flex fields can be added in this assign, as shown in the following
BPEL code example.
<sequence>
<assign name="setUserDefinedAttributes">
...
<copy>
<from expression="string('value of flex string 1')"/>
<to variable="WorkflowVar1" query="/task:task/task:flexString1"/>
</copy>
</assign>
...
<sequence>
Restricted Actions The actions that are performed from the 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 never to suspend a loan application. To model this scenario, at
design time, you can mark Suspend as a restricted action. When an action is marked
as restricted, the Worklist Application does not display the action for this task.
Figure 16–14 shows how restricted actions are configured.
16-16 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–14
Restricted Actions
The following actions can be restricted:
■
Auto Release
■
Reassigned
■
Escalated
■
Renewed
■
Info Requested
After the workflow is created, you can configure restricted actions in the
restrictedActions element of the task configuration XML file, as shown in the
following code example.
<taskType ...>
<task ...>
...
<restrictedActions>
<restrictedAction>AUTO RELEASE</restrictedAction>
<restrictedAction>ESCALATED</restrictedAction>
<restrictedAction>REASSIGNED</restrictedAction>
<restrictedAction>RENEWED</restrictedAction>
<restrictedAction>INFO REQUESTED</restrictedAction>
<restrictedAction>SUSPENDED</restrictedAction>
</restrictedActions>
</task>
<notifications>
...
</notifications>
</taskType>
Version-Tracking Attributes When a task is modified, Oracle BPEL Process Manager
creates a new version of the task as part of the task history. Changes to some of the
task attributes, such as status, assignees, payload, and attachments, are always tracked
with a new version. In addition, you can mark other attributes of the task as version
tracked, including the title of the task, any flex attributes, and comments. Figure 16–15
shows where the version tracking attributes are specified.
Oracle BPEL Process Manager Workflow Services
16-17
Workflow Patterns
Figure 16–15
Version Tracking Attributes
The following attributes can be version tracked:
■
flexString1
■
flexString2
■
flexString3
■
flexString4
■
flexLong1
■
flexLong2
■
flexDouble1
■
flexDouble2
■
flexDate1
■
flexDate2
■
flexDate3
■
title
■
payload
■
identificationKey
■
comments
■
attachments
After the workflow is created, you can change version tracked attributes in the
versionTracking element of the task configuration XML file, as shown in the
following code example.
<taskType ....>
<task ...>
...
<versionTracking>
<attribute>attachments</attribute>
<attribute>payload</attribute>
16-18 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
<attribute>flexString2</attribute>
<attribute>comments</attribute>
</versionTracking>
...
</task>
<notifications>
...
</notifications>
</taskType>
Task Notifications and Reminders As part of workflow modeling, you can optionally
specify notifications and reminders to be sent to users if the task is not acted upon in a
certain time. See "Task Notifications" on page 16-61 for more information.
Resource Bundles Resource bundles can be specified in the task configurations.
Resource bundles are used for the following task configurations:
■
Display value for outcomes
Display values for the outcomes can be plain text or keys in the resource bundle
specified. When the display value is for the format message(key), the display
value is fetched from the resource bundle specified for the task configuration.
■
Display value for flex strings
Display values for the flex strings are treated like the display value for task
outcomes.
■
Notification messages
Notification messages for e-mails can also be internationalized. To get the
internationalized message for notifications, use the XPath extension function
orcl:get-localized-string().
The resource bundle can be part of the BPEL suitcase or in some other location that can
be looked up by the BPEL run-time server. To make the resource bundle available as
part of the BPEL suitcase, add the resource bundle files to the project before deploying
the project.
Resource bundle information is captured in the task configuration file as shown in the
following code example. If the resource bundle is available as part of the project, then
resourceBundleLocation need not be set.
<taskType ...
resourceBundleName="VacationRequestResource"
resourceBundleLocation=" VacationRequestResourceLocation"
...
...
</taskType>
Task Assignment
Tasks can be assigned to both groups and users, as shown in Figure 16–16. When tasks
are assigned to groups, the task can be seen by any user in the group. For a user to act
on a task assigned to a group, the user must acquire the task first. Task assignees can
be specified in one of the following ways.
■
Static assignment
In a static assignment, the assignees are specified at design time. The users can be
typed in or they can be selected by browsing the identity service-supported user
directories.
Oracle BPEL Process Manager Workflow Services
16-19
Workflow Patterns
■
Dynamic assignment using XPath expressions
The assignees of the task can be assigned from other business process variables
using the bpws:getVariableData(…) expression and other XPath expressions.
For example, the task can be assigned to the manager of the vacation requester
using the expression
ora:getManager(bpws:getVariableData('inputVariable','payload','/client:
VacationRequestProcessRequest/client:creator'))
Figure 16–16
Dynamic Assignment Using an XPath Expression
Task Assignment Evaluation
The assignee is captured as a node set. In the two modes for specifying the assignees,
the assignee information is represented as follows:
■
Static Assignment
When the assignment is specified by browsing the user directory, the assignees are
visually represented as a comma-separated string. In BPEL, a node set is created
with a node created for each user specified.
■
Dynamic Assignment
The XPath expression evaluates to a node set. The value of each node represents a
user in the assignee list. There can be only one node in the node set, but the value
of each node must be a valid user name. It cannot be a comma-separated string. If
the input expression is a comma-separated string, XSLT can be used to create a
node set from it.
The assignee list is interpreted in different ways for different types of assignments, as
follows:
■
Single assignment
16-20 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
The task is assigned to all the assignees in the node set. Each of the assignees can
see and approve the task after acquiring it.
■
Sequential task
The task is assigned sequentially to each of the assignees in the node set. For
example, if the assignee is set to a node set, as in
<user xmlns="ns1-namespace>jstein</user>
<user xmlns="ns1-namespace>jcooper</user>
<user xmlns="ns1-namespace>wfaulk</user>
then the task is first assigned to jstein. On their approval, it is assigned to
jcooper, and on jcooper's approval, it is assigned to wfaulk.
■
Parallel task
In a parallel task, a subtask is created for each node in the node set, and the
assignee of each subtask is the value of each node in the node set. For example, if
the assignee is set to a node set, then a subtask is created for jstein, jcooper,
and wfaulk, as follows:
<user xmlns="ns1-namespace>jstein</user>
<user xmlns="ns1-namespace>jcooper</user>
<user xmlns="ns1-namespace>wfaulk</user>
One exception is the sequential task with management chain, where all the assignees
specified are treated as a single assignment for the first assignment. The management
chain is computed from the previous approver of the task.
The DocumentReview demo demonstrates dynamic assignment from a node set. The
DocumentReview process is modeled on the parallel task with the final approver
pattern.
See: Oracle_Home\integration\orabpel\samples\demos
Task Assignment Based on External Services
In a scenario where the task assignment is retrieved from an external service, the
Dynamic assignment using XPath expression option can be used. The element being
pointed to by the XPath expression must be either a node (if assigning to a single user
or group) or a node set (if assigning to multiple users or groups).
Any complex task assignee computation must be done before the workflow is started.
For example, if the assignee of the task should be the one with the least load of all the
possible assignees, then a service can be implemented to compute the assignee, and
the assignee returned from the service can be set as the task assignee using the XPath
option.
Assigning a Task to a Specific User of a Role and Marking It As Acquired
When the task is assigned to a group or multiple users, the task must be acquired
before a user can act on the task. It is also possible to set the task as acquired to a user
from the business process. This can be done by adding a copy rule in the assign
activity named setUserDefinedAttributes. This copy statement sets the
/task:task/task:acquiredBy element of the task, as shown in Figure 16–17. The
acquiredBy value can be computed from a service; for example, a service that does
some load balancing among users computes the acquiredby value. This return value
can be set to the acquiredBy element of the task.
Oracle BPEL Process Manager Workflow Services
16-21
Workflow Patterns
Figure 16–17
Copy Rule
Setting Task Assignees from a Dynamic Delimited String
In a scenario in which the assignees are represented as a delimited string (for example,
a comma-separated string), the delimited string must be converted to a node set to set
the task assignees from it. For this purpose, you can use
orcl:create-nodeset-from-delimited-string. The arguments for this
function are as follows:
■
■
QName in which each node in the node set must be created. The QName can be
represented in two forms:
–
task:assignee
–
{http://mytask/task}assignee
Delimited string
The delimiter used to delimit the string, which can be , (comma) or ;
(semicolon), for example.
For example, the BPEL variable inputVariable, part payload, and query
/client:TestExtensionFunctionProcessRequest/client:input represent
the assignees in a comma-separated format (example, jcooper,jstein,wfaulk)
and this comma-separated list contains the assignees of the task. This string cannot be
used as-is to set the task assignees because the task assignees are expected to be a node
set. To set the assignees, select the dynamic assignment in the task assignees page, as
shown in Figure 16–18, and set it to
16-22 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
orcl:create-nodeset-from-delimited-string('task:assignee',
bpws:getVariableData('inputVariable','payload',
'/client:TestExtensionFunctionProcessRequest/client:input'), ',')
Figure 16–18
Workflow Wizard—Assignees
Selecting Users or Groups by Browsing the User Directory
Assignees can be selected by browsing the user directory (Oracle Internet Directory
(OID), JAZN/XML, LDAP, and so on) that is configured for use by Oracle BPEL
Process Manager. Clicking the flashlight icon to browse OID users (next to the User(s)
or Group(s) text boxes) produces the Identity lookup dialog window.
In the identity lookup dialog window, shown in Figure 16–19, you can search by
entering a search string such as jcooper, j*, *, and so on. Clicking Lookup
fetches all the users that match the search criteria.
Oracle BPEL Process Manager Workflow Services
16-23
Workflow Patterns
Figure 16–19
Identify Lookup Dialog
One or more users or groups can be highlighted and selected by clicking Select.
You can view the hierarchy of a user by highlighting the user and clicking Hierarchy,
as shown in Figure 16–20. Similarly, clicking Reportees displays the reportees of a
selected user or group.
16-24 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–20
User Hierarchy
You can view the details of a user or group by highlighting the user or group and
clicking Detail, as shown in Figure 16–21.
Oracle BPEL Process Manager Workflow Services
16-25
Workflow Patterns
Figure 16–21
Detail Information for a User
Adding a Task Attachment from a Business Process
You can add task attachments from the BPEL process and the Worklist Application.
Task attachments can be one of the following types:
■
URI—A URI attachment is a reference to a URL or file location.
■
Content—A content attachment file is a file that is uploaded.
From the BPEL process, you can set attachments on the task variable by adding the
following copy statements in the assign named setUserDefinedAttributes in
the workflow scope.
1.
In the Create Copy Rule window, set the From part to be the following XML
Fragment:
<attachment xmlns="http://xmlns.oracle.com/pcbpel/taskservice/task">
<name/>
<URI/>
<content/>
</attachment>
The attachment element in the task object is initially empty, so the attachment
element must be initialized.
16-26 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
2.
Select the To part to be the attachment element in the task variable.
3.
Add another copy statement that sets the attachment content. For example, if the
attachment is available at a URI captured by the input message, the XPath
extension function ora:readFile is as follows (this is the From expression):
ora:readFile(bpws:getVariableData('inputVariable','payload','/client:DocumentRe
viewProcessRequest/client:URI'))
4.
Select the To part as /task:task/task:attachment[1]/task:content of
the task variable that was created by the wizard.
By default, the tree does not add the index 1, so it must be added manually.
Oracle BPEL Process Manager Workflow Services
16-27
Workflow Patterns
If the attachment is a URI attachment, the To is set to
/task:task/task:attachment[1]/task:URI of the task variable.
5.
Add another copy statement that sets the attachment name.
For example, if the name is captured in a business process variable, select that
element for the copy From.
6.
Select the To as /task:task/task:attachment[1]/task:name of the task
variable that was created by the wizard.
16-28 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
By default, the tree does not add the index 1, so it must be added manually.
The DocumentReview demo demonstrates adding task attachments from the BPEL
process. The document review process sends a document to multiple users for their
review. The document to be reviewed is set as a task attachment.
See: Oracle_Home\integration\orabpel\samples\demos
Actions Performed on a Task
The Worklist Application enables users to participate in a BPEL process by performing
tasks that require manual intervention. The worklist user interface displays tasks
specific to the logged-in user based on the user’s permissions and assigned groups and
roles. The types of actions that the user 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. Additionally, a user can modify flex fields, task
priority, or include comments or 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 their worklist and routed to the next approver or back to the business process
based on the workflow pattern.
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.
Oracle BPEL Process Manager Workflow Services
16-29
Workflow Patterns
The process owner or workflow administrator can always perform any of these
operations on processes that they own. The various system actions allowed on a
task are as follows:
–
Escalate—This operation enables a user to escalate a task to their manager for
further action.
–
Reassign—A manager can delegate a task to reportees. Similarly, the process
owner or a user with BPMWorkflowReassign privileges can delegate a specific
task to any other person in the organization.
–
Request More Information—Any participant in the workflow can request
more information from the task creator 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.
–
Request More Information with Reapproval—Any participant in the workflow
can request more information from the task creator or any of the prior
approvers of the task and require the approvers who have approved the task
reapprove it. This action is supported only if the current user task supports
sequential approval. For example, 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 when jcooper submits the information, jstein and wfaulk approve
the task before it comes to cdickens. If cdickens requests information with
reapproval from jstein and then jstein submits the information, then
wfaulk approves the task before it comes to cdickens.
–
Submit More Information—This operation enables a user to respond to a
request for additional information. This action is performed after the user has
made the necessary updates to the task or has added comments or
attachments containing additional information.
–
Route—This operation 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.
–
Suspend—This operation enables process 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).
–
Resume—This operation enables process 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.
–
Acquire—This operation enables a user to obtain an exclusive right to work on
a task that is assigned to a group or multiple users. No action can be
performed on a task assigned to a group or multiple users until it is acquired.
Only one user can acquire a task at any given time.
–
Release—This operation enables a user to abandon the exclusive right to work
on a task that is assigned to a group or multiple users. After a task is released,
any other user who is assigned to the task can acquire it.
–
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 modeler has restricted task renewal on the workflow.
–
Withdraw—The creator of the task can withdraw any pending task if they are
no longer interested in sending it further through the workflow. A process
16-30 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
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.
See Also:
■
■
"Identity Service" on page 16-77 for details on the roles in the
system
Chapter 17, "Worklist Application" for information on how to
perform the system actions
XML Validation
If you set the validateXML property to true (the default is false) on the Manage BPEL
Domain window of Oracle BPEL Console, each message exchanged with each of the
Web services is validated against its schema. However, workflow services fail during
XML validity checks at run time. This is because the BPEL variables exchanged with
the workflow services are not completely initialized in the BPEL process. Part of the
initialization happens in the service itself.
Simple Workflow
Simple workflow is used when a task must be acted on by one user. The task can be
assigned to a set of users or groups. If the task is assigned to multiple participants, one
of them must acquire the task and complete it. See "Actions Performed on a Task" on
page 16-29 for a description of the actions a user can perform from the Worklist
Application.
Figure 16–22 shows how simple workflow is implemented in BPEL.
Figure 16–22
A Simple Workflow Implemented in Oracle BPEL Process Manager
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such as assignees,
payload, expiration date
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
Oracle BPEL Process Manager Workflow Services
16-31
Workflow Patterns
Figure 16–23 shows a user task modeled using the simple workflow in JDeveloper
BPEL Designer.
Figure 16–23
A Simple Workflow Modeled in JDeveloper BPEL Designer
Use Case
An employee, through the employee portal, submits a vacation request. The portal
initiates a business process that includes a user task modeled using a simple workflow.
The task is assigned to the manager of the employee. When the manager approves or
rejects the vacation request, the employee is notified with the manager's decision by
e-mail. See the VacationRequest example in the samples directory for an
implementation of this use case.
See: Oracle_Home\integration\orabpel\samples\demos
Customizations for Simple Workflow
The following customizations are possible:
■
Changing the assignee after creating the user task
16-32 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
The assign named setUserDefinedAttributes in the generated scope
captures the setting of the task assignee. Depending on whether the task is
assigned to a user or a group, the task attribute assigneeUsers or
assigneeGroups is set. This assignment can be changed to modify the task
assignee. For example, if you are using an external service that does load
balancing or determines task assignee based on contents of the payload, you can
call this service and set the assignees to a local variable. This variable can then be
used to do a dynamic assignment based on an XPath expression.
■
Changing the outcomes after creating the user task
The outcomes are captured in the XML task configuration file, where they can be
changed manually. See "Task Outcomes" on page 16-13 for more information.
■
Changing the user task to support multiple approvals
A simple workflow (or any variation of simple workflow) does not support
multiple approvals because it is intended for a single approval. If reapproval is
required, change the user task to sequential workflow.
Simple Workflow with Automatic Escalation
Simple workflow with automatic escalation is a variation of the simple workflow in
which the task is escalated when the task expires. The rules of escalation are specified
as part of creating the user task. As in a simple workflow, the task can be assigned to a
set of users or groups. See "Actions Performed on a Task" on page 16-29 for a
description of the actions a user can perform from the Worklist Application. If the user
does not perform any of the custom actions before the task expires, the task is
escalated to their manager as specified in the user directory that is configured with the
identity service.
Figure 16–24 shows how simple workflow with automatic escalation is implemented
in Oracle BPEL Process Manager.
Oracle BPEL Process Manager Workflow Services
16-33
Workflow Patterns
Figure 16–24
Simple Workflow with Automatic Escalation
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such
as assignees, payload, expiration date
setEscalationPolicy (assign)
Captures the escalation policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
while (task != completed || errored || expired || withdrawn)
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
escalateTask (invoke)
If the task is expired, escalate the task
Figure 16–25 shows the user task scope modeled using the simple workflow with
automatic escalation.
16-34 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–25
Simple Workflow with Automatic Escalation in JDeveloper BPEL Designer
Use Case
The HelpDeskServiceRequest process gives users the ability to file help desk service
request tickets. If the person who receives the ticket does not act on it within a
specified time period, the ticket is automatically escalated to their manager. The ticket
is automatically escalated three times if no one has acted on it within a predefined
time, until it gets to the CEO of the company. If the CEO also does not act on it, it
expires.
See: Oracle_Home\integration\orabpel\samples\demos
Pattern-Specific Parameters
Two parameters are specific to this pattern.
■
The maximum number of times the task can be escalated
This required parameter specifies how many times the task is escalated. For
example, if this parameter to set to 2, then the task is assigned to the user
jcooper. If none of the users acts on the task in time, the task is assigned to
jcooper (initial assignee), user jstein (jcooper's manager) and user wfaulk
(jstein's manager).
■
The title of a user to whom the task can be escalated
This optional parameter specifies the title of the last user to whom the task can be
escalated. For example, if this parameter is set to Manager, the task is assigned to
user jcooper. If none of the users acts on the task in time, the task is assigned to
jcooper (initial assignee) and user jstein (jcooper's manager), whose title is
Manager.
Oracle BPEL Process Manager Workflow Services
16-35
Workflow Patterns
The title can be typed in or selected from a list of prespecified titles. The list of
titles that are displayed is configured in defaultUserTitles.xml at
Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
When both these parameters are specified, the task is escalated until one of the
conditions causes the escalation to stop. For example, if the maximum number of times
is 4 and the title is Manager, then the task is assigned to jcooper. If none of the users
acts on the task in time, the task is assigned to jcooper (initial assignee), and user
jstein (jcooper's manager), whose title is Manager.
Figure 16–26 shows where these parameters are specified.
Figure 16–26
Escalation
Customizations for Simple Workflow with Automatic Escalation
The customizations in "Customizations for Simple Workflow" on page 16-32 apply to
this pattern, in addition to the following.
■
Changing the duration for the task assignment
When the task is expired and is escalated, the task is renewed for a duration equal
to the initial expiration duration of the task. The BPEL assign named
setEscalationPolicy in the user task scope sets the renewal duration in the
variable oraBPMExpDuration. This copy statement can be changed to change the
expiration duration for the subsequent task assignments.
■
Changing the number of levels of escalation
The BPEL assign named setEscalationPolicy in the user task scope
captures the number of levels of escalation in the variable
oraBPMManagementChain (the query for the copy is
16-36 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
/identityservice:managementChain/identityservice:levels). This
can be changed to any appropriate value.
■
Changing the title of the last user to whom the task is escalated
The BPEL assign named setEscalationPolicy in the user task scope stores
the title of the last user in the variable oraBPMManagementChain (the query for
the copy is
/identityservice:managementChain/identityservice:uptoTitle).
This can be changed to any appropriate value.
■
Changing the user to whom the task is escalated on task expiration
By default, on task expiration, the task is escalated to the user’s manager. This can
be changed by changing the generated BPEL scope. In the generated BPEL scope,
there is another BPEL scope named escalateTask that performs the escalation.
In the scope, change the escalateTask invoke to invoke the updateTask
operation on the TaskManagerService instead of the escalateTask
operation. The TaskManagerService.wsdl file defines the updateTask
operation. The task assignees (users or groups) to whom the task is escalated must
be set before the operation is invoked. In addition, the state of the task
(task:task/task:state) must be set to ASSIGNED before the operation is
invoked.
Simple Workflow with Automatic Renewal
Simple workflow with automatic renewal is a variation of the simple workflow in
which the task is renewed when the task expires. The rules of renewal are specified as
part of creating the user task. As in a simple workflow, the task can be assigned to a set
of users or groups. See "Actions Performed on a Task" on page 16-29 for a description
of the actions a user can perform from the Worklist Application. If the user does not
perform any of the custom actions before the task expires, the task is renewed for a
specific duration.
Figure 16–27 shows how simple workflow with automatic renewal is implemented in
Oracle BPEL Process Manager.
Oracle BPEL Process Manager Workflow Services
16-37
Workflow Patterns
Figure 16–27
Simple Workflow with Automatic Renewal
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task,
such as assignees, payload, expiration date
setRenewalPolicy (assign)
Captures the renewal policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task,
such as process id, process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
while (task != completed || errored || expired || withdrawn)
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
renewTask (invoke)
If the task is expired and has not been renewed the maximum
number times, renew the task
Figure 16–28 shows the user task scope modeled using the simple workflow with
automatic renewal.
16-38 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–28
Simple Workflow with Automatic Renewal
Use Case
A business process manages renewal of magazine subscriptions. The rules of the
subscription are that if the user cancels the subscription one month before the
expiration date of the current subscription, then the subscription is cancelled free of
charge. If the user cancels in the last month of the current subscription, then the
subscription is cancelled with a charge. If the user does not cancel, it is renewed.
The process is initiated 60 days before the subscription is up for renewal. The process
contains a user task modeled with the simple workflow with automatic renewal
pattern. When the magazine subscription task is assigned to a user, an e-mail is sent to
the user. The user can go to a portal and renew or cancel the subscription. Depending
on the user action, the business process determines the cancellation or cancellation
with charge or renewal.
Pattern-Specific Parameters
One parameter is specific to this pattern.
■
The maximum number of times the task can be renewed
This required parameter specifies how many times the task is renewed.
Customizations for Simple Workflow with Automatic Renewal
The customizations in "Customizations for Simple Workflow" on page 16-32 apply to
this pattern, in addition to the following:
■
Changing the duration for the task assignment
When the task expires, it is renewed. The renewal duration of the task is the same
as it was for the first task assignment. The BPEL assign named
setRenewalPolicy in the user task scope sets the new expiration duration in
Oracle BPEL Process Manager Workflow Services
16-39
Workflow Patterns
the variable oraBPMRenewDuration. This copy statement can be changed to
change the expiration duration for the subsequent task assignments.
■
Changing the number of levels of renewal
The BPEL assign named setRenewalPolicy in the user task scope stores the
maximum number of levels of renewal in the variable
oraBPMMaxTimesRenewed. This can be changed to any appropriate value.
■
Adding logic depending on number of times renewed
The BPEL scope level variable oraBPMNumOfTimesRenewed captures the
number of times the task is renewed. This variable can be used to build additional
logic in the business process.
Sequential Workflow
Sequential workflow is used when a task must be approved by multiple users. The
users or groups to whom the task is assigned can be specified in one of the following
ways:
■
■
■
List of users in a management chain
List of users or groups from the identity service set during the design time of the
process
Dynamic list of users or groups from another business process variable
In each of the preceding cases, the task is sequentially assigned to each of the users in
the list. See "Actions Performed on a Task" on page 16-29 for a description of the
actions a user can perform from the Worklist Application. In a sequential workflow, a
request for information with reapproval is permitted.
As part of modeling a sequential workflow, the list of outcomes that cause the task to
be routed can also be specified. For example, if a task has two outcomes, ACCEPT and
REJECT, the business logic might require the task to be routed to the next approver
only if the current user accepts the task. A continue routing expression can also be
specified. If this condition evaluates to true, the task is routed.
Figure 16–29 shows how the sequential workflow is implemented in Oracle BPEL
Process Manager.
16-40 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–29
How Sequential Workflow Is Implemented in BPEL
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such as
assignees, payload, expiration date
setRoutingPolicy (assign)
Captures the routing policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
while (task != completed || errored || expired || withdrawn)
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
routeTaskToNextApprover (invoke)
If the task is completed and the outcome requires routing and the continue
routing expression evaluates to true, route the task to the next approver
Based on the assignees, a future approver function is created to capture future
approvers of the task. This function is persisted in the approvers element of the task. If
the management chain assignment is used, the managementChain function is
created. If a list of users is provided (either using static assignment from a user
directory or an XPath function), a list function is created. The list function has a user or
group function in it to represent the assignees. This approver function creation is done
in the assign named setRoutingPolicy in the generated workflow scope. This
function is not changed in normal circumstances; however, it can be changed if a
complicated sequential assignment is being created. For example, first assign to users
jcooper and jstein, then assign to wfaulk, and so on. (The complexity of this
example is multiple users assignment—jstein and jcooper—for the first
assignment).
Examples of approver functions are as follows:
■
managementChain("2", "Manager")
Oracle BPEL Process Manager Workflow Services
16-41
Workflow Patterns
Routes the task to users in the management chain. The management chain
includes users within two levels and up to a user whose title is Manager.
■
users("jcooper", "jstein")
Routes the task once to users jcooper and jstein.
■
users("jcooper", "jstein", acquiredBy("jcooper"))
Routes the task once to users jcooper and jstein. Also sets the acquiredBy to
jcooper.
■
groups("LoanAgentGroup", "Supervisor", acquiredBy("jcooper"))
Routes the task once to groups LoanAgentGroup and Supervisor. Sets the
acquired-by to jcooper.
■
list(users("jcooper", "jstein"), groups("LoanAgentGroup"),
acquiredBy("jcooper"))
Routes the task once to users jcooper and jstein and group LoanAgentGroup
and also sets the acquiredBy to jcooper.
■
list(users("jcooper","jstein")),
list(groups("LoanAgentGroup"))
Routes the task to users jcooper and jstein. When one of those users acquires
and acts on the task, routes the task to group LoanAgentGroup.
■
adhoc()
The task supports adhoc routing and the next users or groups are specified by the
current approver of the task.
These functions are evaluated when the task must be routed to the next approver. See
"Approver Functions" on page 16-105 for more information, and for how to modify the
value of the approvers element to achieve different results.
Figure 16–30 shows the user task scope modeled using the sequential workflow.
16-42 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–30
Sequential Workflow in JDeveloper BPEL Designer
Use Cases
A loan application processing system receives loan applications. These loan
applications are initially assigned a group called LoanAgentGroup. A user in this
group evaluates and approves the loan application and provides a loan offer. If the
loan application amount is greater than 100,000 US dollars, then the loan application
and the initial loan offer are sent to the initial approver's manager. After they approve
it, the loan application is routed to their manager. If the loan application amount is less
than or equal to 100,000 US dollars, then the initial loan offer is sent back to the caller.
This use case is demonstrated in the LoanDemoPlusWithWorkflow sample.
Another use case is when a purchase order approval system processes a purchase
order using a business process. An employee belonging to a group named Supervisor
initially evaluates the purchase order. After the initial user approves the purchase
order, their manager approves it. After the manager approves the purchase order, the
purchase order is forwarded to the billing and shipping departments. This use case is
demonstrated in the Order Booking tutorial purchase order approval service.
See Also: Oracle BPEL Process Manager Order Booking Tutorial
Pattern-Specific Parameters
The sequential workflow has the following pattern-specific parameters.
■
The approvers assignment policy
■
Outcome that results in the task being routed
■
Continue routing expression
Oracle BPEL Process Manager Workflow Services
16-43
Workflow Patterns
In simple workflow, the assignees are specified for the only assignment of the task. In
sequential workflow, the set of users to whom the task is routed is specified. There are
two ways to specify this.
1.
A list of users from a business process variable or a static list set at design time.
2.
A management chain. This involves selecting the initial assignees (a set of groups
or users) and parameters to select the management chain. The parameters to select
the management chain include specifying the following attributes:
a.
The number of levels in the management chain
This required parameter specifies how many levels in the management chain
are included in the list. For example, if this parameter to set to 2 and the task is
initially assigned to a user jcooper, then both the user jstein (jcooper's
manager) and user wfaulk (jstein's manager) are included in the list, apart
from jcooper (the initial assignee).
b.
The title of the last user in the management chain
This optional parameter specifies the title of the last user in the management
chain. For example, if this parameter is set to Manager and the task is assigned
to a user jcooper, user jstein (jcooper's manager) is included in the list,
apart from jcooper (the initial assignee).
The title can be typed in or selected from a list of prespecified titles. The list of
titles is configured in defaultUserTitles.xml at
Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
When both these parameters are specified, then the task routing is determined by both
the title and the number of levels. The routing continues until one of the
conditions—title or the number of levels—no longer applies. The following examples
illustrate this.
Example: If the maximum level in the management chain is four and the title is
Manager and the task is assigned to a user jcooper, then the list includes jcooper
(initial assignee) and user jstein (jcooper's manager), whose title is Manager. The
task is not be routed beyond the Manager, even though the maximum number of
levels is set to 4. This is useful in cases where you want the approvals to go up to a
certain management level (for example, Director).
Example: If the maximum level in the management chain is 1 and the title is Director
and the task is assigned to a user jcooper, then the list includes jcooper (initial
assignee) and user jstein (jcooper’s manager, whose title is Manager). It does not
include wfaulk (jstein’s manager, whose title is Director) because the task was
already routed to one user beyond the initial assignee.
There are also two parameters that determine if the task must be routed.
1.
The list of outcomes that cause the task to be routed can also be specified. For
example, if a task has two outcomes, ACCEPT and REJECT, the business logic
might require the task to be routed to the next approver only if the current user
accepted the task.
2.
A continue routing expression can also be specified. If this expression evaluates to
true, the task is routed further after a specific user acts on it. This expression can
be used to dynamically control how many approvals are required. Examples of
this expression are as follows:
a.
The task is routed only if the loan amount is greater than 1000; otherwise it is
approved only once.
16-44 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
bpws:getVariableData('loan',
'/auto:loan/auto:loanApplication/auto:loanAmount') > number(10000)
b.
The task is routed until it is approved by a manager.
ora:getPreviousApproversTitle(‘/task:task/task:taskId’) = string(‘Manager’)
c.
The task is approved at most three times.
ora:getNumberOfTimesApproved(‘/task:task/task:taskId’) < 3
d.
The task is approved at most three times when the loan amount is greater than
10000; otherwise it should be approved only once.
ora:getNumberOfTimesApproved(‘/task:task/task:taskId’) < 3 and
bpws:getVariableData('loan',
'/auto:loan/auto:loanApplication/auto:loanAmount') > number(10000)
The extension function ora:getPreviousApproversTitle() gets the title of the
previous task approver. The function getNumberOfTimesApproved() gets the
number of times a task was approved. See "Workflow-Related XPath Extension
Functions" on page 16-100 for a list of the extension functions.
Figure 16–31 shows the routing parameters.
Figure 16–31
Routing Parameters
Customizations for Sequential Workflow
■
Changing the initial assignee in the management chain after creating the user task
The assign named setUserDefinedAttributes in the generated scope
captures the assignment of the task assignee. Depending on whether the task was
assigned to a user or a group, the task attribute assigneeUsers or
assigneeGroups is set. This assignment can be changed to modify the task
assignee.
■
Changing the management chain parameters after creating the user task
The assign named setRoutingPolicy in the generated scope sets the
approver function in the task attribute approvers. The approver function
contains the management chain parameters. The parameters can be changed in
this function. See "Approver Functions" on page 16-105 for more information.
Oracle BPEL Process Manager Workflow Services
16-45
Workflow Patterns
■
Changing the assignees in the list after creating the user task
The assign named setUserDefinedAttributes in the generated scope
captures the assignment of the task assignee. The assignment to the
oraBPMRouteAssignees variable attributes
/taskmngr:assigneeEntities/taskmngr:assignee captures the list of
users or groups.
■
Changing the outcomes after creation of the user task
Task outcomes are captured in the XML task configuration file, where outcomes
can be changed manually. See "Task Outcomes" on page 16-13 for more
information.
■
Changing routing policy
The assign named setRoutingPolicy captures the routing policy. The future
assignees of a task in a sequential workflow are captured in the approvers
attribute of the task object. This assign sets the approvers attribute to an approver
function depending on the assignment policy chosen—management chain or list
of users. See "Approver Functions" on page 16-105 for more information.
■
Changing continue routing expression
In the generated scope, the continue routing expression is evaluated in the
assign named evaluateRoutingCriteria. The condition that is set in the
wizard is negated with a not() in this expression. This expression can be changed
as needed.
■
Adding continue routing expression
The response from each user is received in the receive activity
receiveUpdatedTask. The receive activity follows a switch activity in
which one of the case statements is:
Task is COMPLETED and the task outcome is one of the outcomes specified in the
routing policy
The expression on this case statement can be changed to add any continue routing
expression.
■
Adding approvers
In the management chain routing policy, approvers can be added by changing the
management chain parameters as described previously. Similarly, by changing the
assignees in the list of users as described previously, approvers can be added.
■
Changing the user or group to whom the task is routed based on output of an
external system
In the generated BPEL, there is a scope named routeTaskToNextApprover.
This scope is responsible for routing the task to the next user or group. By default,
this routing is based on the approver function. In a scenario where the next task
assignee is determined by an external system, the activities in the
routeTaskToNextApprover scope can be modified to achieve that. The
TaskRoutingService exposes an operation called routeTask that routes the task
to a specified user or group. The input message for this operation includes the
task, an id that identifies either a user or a group, and a Boolean flag that identifies
the entity as a group or a user. After a message is created, change the
routeTaskToNextApprover invoke and its input variable accordingly to use
the routeTask operation instead of the routeTaskToNextApprover operation.
16-46 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Sequential Workflow with Escalation
The sequential workflow with escalation is used when a task must be approved by
multiple users and the task must be escalated when it expires. This pattern is an
extension of the sequential workflow and all that applies to the sequential workflow
also applies to this pattern.
Figure 16–32 shows how sequential workflow is implemented in Oracle BPEL Process
Manager.
Figure 16–32
Sequential Workflow with Escalation
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such as
assignees, payload, expiration date
setRoutingPolicy (assign)
Captures the routing policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
while (task != completed || errored || expired || withdrawn)
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
routeTaskToNextApprover
(invoke)
If the task is completed and the
outcome requires routing and
the continue routing expression
evaluates to true, route the task
to the next approver
escalateTask (invoke)
If the task is expired and the
escalation rules are met,
escalate the task
Oracle BPEL Process Manager Workflow Services
16-47
Workflow Patterns
Use Case
An employee (for example, jcooper) requests a new laptop urgently. The sequential
workflow first routes the task to their manager for approval (for example, jstein)
and then to a person in the procurement department (for example, jlondon) to
acquire the laptop. If the workflow is set up with automatic escalation after two days,
then the request first goes to the manager for approval and if it is not approved in two
days, then the task can be automatically routed to the next person in the management
hierarchy (jstein’s manager, wfaulk). Similar escalation can also be done for the
procurement representative. This enables the workflow to complete without long
delays in the approval process.
Pattern-Specific Parameters
All the parameters that apply to the sequential workflow apply to this pattern as well.
In addition to those parameters, the following parameters are specific to this pattern.
■
The maximum number of times the task can be escalated
This required parameter specifies how many times the task is escalated for each
assignment. For example, if this parameter to set to 2, the task is assigned to user
jcooper. If jcooper does not act on the task in time, then the task is escalated to
user jstein (jcooper's manager). If jstein does not act on the task, then the
task is escalated to user wfaulk (jstein's manager).
■
The title of a user up to whom the task can be escalated
This optional parameter specifies the title of the last user to whom the task can be
escalated. For example, if this parameter is set to Manager, then the task is
assigned to a user jcooper. If none of the users act on the task in time, then the
task is assigned to jcooper (initial assignee) and user jstein (jcooper's
manager), whose title is Manager.
The title can be typed in or selected from a list of prespecified titles. The list of
titles is configured in defaultUserTitles.xml at
Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
When both these parameters are specified, the task is escalated until one of the
conditions causes the escalation to stop. For example, if the maximum number of times
is 4, and the title is Manager, then the task is assigned to user jcooper. If none of the
users act on the task in time, then the task is assigned to jcooper (initial assignee),
user jstein (jcooper's manager), whose title is Manager.
Customizations for Sequential Workflow with Escalation
All the customizations that apply to the sequential workflow apply to this pattern also.
■
Changing the escalation policy
The assign named setRoutingPolicy in the generated scope sets the
escalation policy. The title of the last user to escalate up to is set to the attribute
/identityservice:managementChain/identityservice:uptoTitle of
the variable oraBPMManagementChain. The level of escalation is set to the
attribute
/identityservice:managementChain/identityservice:levels of the
variable oraBPMManagementChain. These assignments can be changed as
required.
■
Changing the expiration duration of the task when escalated
16-48 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
By default, the expiration duration of the task when escalated is the initial
expiration duration of the task. Changing the assignment to the variable
oraBPMExpDuration in the assign setRoutingPolicy changes the
expiration duration when the task is escalated.
■
Changing the user to whom the task is escalated on task expiration
By default, on task expiration, the task is escalated to the user’s manager. This can
be changed by changing the generated BPEL scope. In the generated BPEL scope,
another BPEL scope named escalateTask performs the escalation. In the scope,
change the escalateTask invoke to invoke the updateTask operation on the
TaskManagerService instead of the escalateTask operation. The
TaskManagerService.wsdl defines the updateTask operation. The task
assignees (users or groups) to whom the task is escalated must be set before the
operation is invoked. In addition, the state of the task (task:task/task:state)
should be set to ASSIGNED before the operation is invoked.
Parallel Workflow
Parallel workflow is used when a task must be approved by multiple users or groups
simultaneously. Each user views a subtask, which is a clone of the task at the time of
creation. Each user can add attachments and comments independent of the other
users. The users reviewing the task in parallel are not able to see the tasks of the other
users. This includes the comments, attachments, and outcomes of the other tasks. The
owner of the task can see all the subtasks. When the creator withdraws the parent task,
all the subtasks are withdrawn as well.
The users and groups that review the task can be specified in one of the following
ways. In each of the preceding cases, a subtask is created for each of the users or
groups in the list.
■
List of users or groups from OID set during the process design time
■
List of users or groups from another business process variable
The outcome of the final task is selected based on the outcomes of each of the subtasks.
The outcome of the task is selected based on the following criteria:
■
■
Percentage an outcome requires for it to be selected as the final outcome of the
task. For example, assume there are two possible outcomes, ACCEPT and REJECT,
and there are five subtasks. If two of the subtasks are accepted and three are
rejected, and the acceptance percentage required for an outcome is 50%, then the
outcome of the task is rejected.
If none of the outcomes have the required percentage, a default outcome can be
specified as the outcome of the task.
Parallel workflow can be configured for early completion. When early completion is
specified, that is, when the outcome of the task can be computed with the outcomes of
the completed subtasks, then the pending subtasks are withdrawn. If no early
completion is specified, the workflow waits for all the responses.
Figure 16–33 shows how parallel workflow is implemented in Oracle BPEL Process
Manager.
Oracle BPEL Process Manager Workflow Services
16-49
Workflow Patterns
Figure 16–33
Parallel Workflow
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such as
assignees, payload, expiration date
setOutcomeDeterminationPolicy (assign)
Captures the outcome determination policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
For each assignee, create and execute subtask
completeMainTask (invoke)
Complete the main task based on the outcome determination policy
Figure 16–34 shows the subtask execution process.
Figure 16–34
The Parallel Workflow Subtask Process
initiateSubTask (invoke)
Initiates the subtask by invoking the TaskManagerService
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler business process
Compute number of outcomes based on the outcome of the subtask
(switch-case and assign)
16-50 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–35 shows the user task scope modeled using parallel workflow.
Figure 16–35
Parallel Workflow in JDeveloper BPEL Designer
Assigning Parallel Tasks to Each User in a Group
You cannot use a concat function to assign a parallel task to each user in a group.
Instead, use the ora:getUsersInGroup(groupName) extension function to
perform this task (for example, assign the parallel task to users fkafka, szweig, and
mmitch in group LoanAnalyticGroup). This extension function gets the users in a
group as a node-set. In this case, specify the XPath expression as follows in the
Dynamic assignment using XPath expression field in the Assignees window of the
Workflow wizard:
ora:getUsersInGroup('LoanAnalyticGroup')
The use of the ora:getUsersInGroup function is described on Oracle BPEL Console
under Manage BPEL Domain > XPath Library and also in Appendix G, "XPath
Extension Functions".
Oracle BPEL Process Manager does not provide built-in functionality for explicitly
assigning a task to each user in multiple groups. For example, if group
LoanAgentRole has users jcooper, jstein, and wfaulk and group Supervisor
has users jlondon and cdickens, then creating a parallel task to assign to users
jcooper, jstein, wfaulk, jlondon, and cdickens is not directly supported. As a
workaround, you can write your own bpelx:exec (Java inside BPEL) to create a
node-set that contains all the users from both groups and assign the parallel task to
that node-set.
Use Case
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. The process is modeled using the parallel workflow, where
each interviewer can vote independently from the other interviewers.
Oracle BPEL Process Manager Workflow Services
16-51
Workflow Patterns
Pattern-Specific Parameters
Parallel workflow has the following pattern-specific parameters.
■
The percentage required for an outcome to be chosen as the final outcome
■
The default outcome
■
Configuration if early completion is enforced
Figure 16–36 shows where these parameters are configured.
Figure 16–36
Outcome Determination
Customizations for Parallel Workflow
■
Changing the outcomes after creation of the user task
The outcomes are captured in the XML task configuration file, where they can be
changed manually. See "Task Outcomes" on page 16-13 for more information.
■
Changing the parameters of the outcome determination policy
The assign named setUserDefinedAttributes in the generated scope
captures the outcome determination policy. The percentage required for the final
outcome is assigned to the BPEL variable oraBPMConclusionPercentage and
the default outcome is set in the BPEL variable oraBPMDefaultConclusion.
Parallel Workflow with Final Reviewer
Parallel workflow with a final reviewer is an extension of the parallel workflow in
which, after users review the task in parallel, the task is assigned to a final reviewer.
The final reviewer can be users or groups. When there is more than one final reviewer
or if the task is assigned to a group, one of the users must acquire the task before
reviewing it. All that applies to the parallel workflow applies to the parallel workflow
with final reviewer as well. The final reviewer can see all the subtasks, where each
subtask is a task that was acted on by a user in the parallel workflow.
16-52 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
The final reviewer (users or groups) of the task can be specified in one of the following
ways:
1.
List of users or groups from OID set during the process design time
2.
List of users or groups from another business process variable
The outcome of the final task is selected based on the outcomes of each of the subtasks,
as in the parallel workflow. The final reviewer can check the outcome that is selected
based on the outcome determination policy from the history of the task from the
Worklist Application.
Parallel workflow with final reviewer is implemented using the task continuation
concept. See "Task Continuations" on page 16-57 for more information. Parallel
workflow with final reviewer is a parallel workflow continued by a simple task.
Use Case
A DocumentReview process is used to review a document. The document creator
creates the document and initiates a process by specifying the document and the
reviewers of the document. Each reviewer can review the document simultaneously
and independently of the other reviewers. After all the reviewers are done reviewing,
the creator of the document gets to review the comments of the reviewers. See the
DocumentReview example in the samples directory for an implementation of this use
case.
See: Oracle_Home\integration\orabpel\samples\demos
Pattern-Specific Parameters
Parallel workflow with final reviewer has the same pattern-specific parameters as
parallel workflow. In addition to choosing the parallel participants, the final reviewer
must also be set. Figure 16–37 shows where the final reviewer is selected.
Oracle BPEL Process Manager Workflow Services
16-53
Workflow Patterns
Figure 16–37
Setting Reviewers
Customizations for Parallel Workflow with Final Reviewer
All the customizations for the parallel workflow apply to this pattern, in addition to
the following:
■
Changing the final reviewer of the task
The assign named setUserDefinedAttributes in the generated scope
captures the reviewers. The reviewers are set in the
/taskmngr:assigneeEntities/taskmngr:assignee attribute of the
oraBPMReviewers variable. This assignment can be changed to change the final
reviewer.
Adhoc Workflow
Adhoc workflow is used when each user selects users or groups as the next assignee
when approving the task. As part of configuring the workflow, only the initial assignee
is set. A user can choose either to complete the task by selecting an outcome or to set
an outcome and send the task to other users or groups.
Figure 16–38 shows how sequential workflow is implemented in Oracle BPEL Process
Manager.
16-54 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–38
Adhoc Workflow
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such
as assignees, payload, expiration date
setRoutingPolicy (assign)
Captures the routing policy
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
while (task != completed || errored || expired || withdrawn)
initiateTaskActionHandler (invoke)
Initiates the TaskActionHandler business process. This process receives
the actions from the Worklist application via the TaskManagerService.
receiveUpdatedTask (receive)
Receives the updated task from the TaskActionHandler
business process
routeTaskToNextApprover (invoke)
If the task is completed and the outcome requires routing and the continue
routing expression evaluates to true, route the task to the next approver
Use Case
This pattern is typically used when a sequence of users or roles that need to act on the
task is not determined automatically by the workflow process, but instead by the user
who is currently assigned the task. Each user decides whether the task must be routed
further or if it is complete. For example, an HR representative writes a new policy
document and has it reviewed by their manager. The manager may decide that
another person should also review it before it is accepted. This person may in turn
forward the task to others before approving it. Hence, the task may be routed to
multiple users before coming back to the original reviewer, who then finally approves
it based on comments from others.
Customizations for Adhoc Workflow
■
Changing the initial assignee of the task
Oracle BPEL Process Manager Workflow Services
16-55
Workflow Patterns
The assign named setUserDefinedAttributes in the generated scope
captures the assignment of the task assignee. Depending on whether the task is
assigned to a user or a group, the task attribute assigneeUsers or
assigneeGroups is set. This assignment can be changed to modify the initial
assignee.
FYI Tasks
The FYI task is a nonblocking task that is listed as an assigned task for the assignee in
the Worklist Application. The process that created the task does not wait for a response
from the user. The process continues after creating the task. From the Worklist
Application, the user can perform the available custom action so that the task no
longer appears in the assigned list.
The FYI task cannot be extended. Any other workflow can be extended with an FYI
task, but the FYI task itself cannot be extended.
Figure 16–39 shows how the FYI task is implemented in Oracle BPEL Process
Manager.
Figure 16–39
The FYI Task
setUserDefinedAttributes (assign)
Captures the user-defined attributes of the task, such as
assignees, payload, expiration date
setSystemDefinedAttributes (assign)
Captures the system attributes of the task, such as process id,
process version
initiateTask (invoke)
Initiates the task by invoking the TaskManagerService
Use Case
A purchase order approval system processes purchase orders. When the system
processes approvals over $100,000, a supervisor must be notified, but without
stopping the processing. This information is used by the supervisor to monitor the
system.
Customization for FYI Tasks
■
Changing the assignee after creating the FYI task
The assign named setUserDefinedAttributes in the generated scope
captures the assignment of the task assignee. Depending on whether the task was
assigned to a user or a group, the task attribute assigneeUsers or
assigneeGroups is set. This assignment can be changed to modify the task
assignee.
16-56 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
The User Task 2.0 Macro
The User Task 2.0 Macro supports the user task from earlier releases. This user task
requires the business process modeler to assign task properties explicitly and also
requires a custom application to view and act on tasks. The User Task 2.0 Macro is
available for backward compatibility and is replaced with the workflow services and
patterns in this release.
Tasks created using the User Task 2.0 Macro cannot be viewed in the Worklist
Application. These tasks cannot be continued with the continue task concept.
Task Continuations
Complex workflow patterns can be built using the task continuation (extension)
concept. Task continuation allows one workflow to be continued with another
workflow. For example, if you have a document review workflow that goes through a
voting process followed by two level manager approvals before the document is
published, you can start with the Parallel Workflow pattern and select the Extend
Existing Workflow check box to add the Sequential Workflow pattern. The second
workflow shares the task details and history with the first workflow. The Extend
Existing Workflow check box is disabled if there are no existing workflows.
When a workflow 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
■
Task configuration such as outcomes and notification messages
When a workflow is being created, the first window in the wizard (see Figure 16–40)
enables you to determine if a new workflow should be created or a previous workflow
should be extended. When Extend Existing Workflow is selected, all the existing
workflows are listed. Selecting a particular workflow permits the user to extend
(continue) the selected workflow.
Oracle BPEL Process Manager Workflow Services
16-57
Workflow Patterns
Figure 16–40
Task Continuation
Any workflow pattern can be extended with any other workflow pattern, with the
following restrictions:
■
The FYI task cannot be extended. Any other workflow can be extended with an
FYI task, but the FYI task itself cannot be extended.
■
The User Task 2.0 Macro cannot be extended.
■
No workflow can be extended with the User Task 2.0 Macro.
When a task is extended, the previous task’s expiration date is also carried over. This
has the following impact:
■
If no expiration duration was set in the old task, and
■
■
■
if there is no expiration duration set in the extended workflow, then the task
does not expire.
if a new expiration duration is set in the extended workflow, then this
expiration duration is based on the time the extended task is initiated.
If an expiration duration was set in the old task, and
■
■
if there is no expiration duration set in the extended workflow, then the
expiration date of the old task is the expiration date of the current task.
if a new expiration duration is set in the extended workflow, then this
expiration duration is based on the previous expiration date
(task:task/task:expirationDate).
If the expiration date carry over is not required for the scenario being modeled, then
the expirationDate element must be cleared. You can add a copy in the
setUserDefinedAttributes of the generated scope to set the
/task:task/task:expirationDate element to the expression string(‘’).
Figure 16–41 shows the copy wizard with such an assignment.
16-58 Oracle BPEL Process Manager Developer’s Guide
Workflow Patterns
Figure 16–41
Create Copy Rule
The first workflow from which others are extended must have a union of all the
conclusions of all the workflows.
For example, if the first workflow has conclusions of yes and no, the second
workflow has conclusions of yes and maybe, and the third workflow has conclusions
of no and let’s see, then design the first workflow with conclusions of yes, no,
maybe, and let’s see.
Use Case
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, then 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 parallel workflow for the hiring. If the candidate is hired, then a simple workflow
can extend the parallel workflow so that the hiring request, history, and the
interviewer comments are carried over. This simple workflow is assigned to the HR
contact.
Pattern-Specific Parameters
There are no parameters specific to the extended workflow. The parameters are driven
by the pattern chosen for the extended workflow.
Oracle BPEL Process Manager Workflow Services
16-59
Workflow Patterns
Customization for Task Continuations
The follow customization applies:
■
■
Customization applicable to the workflow pattern also applies to the extended
workflow.
Changing a new workflow to an extended workflow
Any new workflow can be changed to an extended workflow. For example, if
Workflow1 uses the BPEL variable Workflow1Var and Workflow2 uses
Workflow2Var, and Workflow2 must be changed to extend Workflow1, then do
the following:
1.
Delete the BPEL variable Workflow2Var.
2.
Replace all occurrences of Workflow2Var in the BPEL with Workflow1Var.
3.
In the generated scope, after the BPEL assign activities, there is a scope
named initiateTask. In this scope, there is an invoke initiateTask
activity that calls the TaskManagerService in the operation initiateTask.
Change this operation to reinitiateTask.
This customization is useful when two workflows that have different payloads
must carry the same history information. When modeled as new workflows, the
modeler can take advantage of the autogenerated JSP for display purposes and
then change the new workflow to an extended workflow.
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.
Payload Updates
The task carries a payload in it. If the payload is set from a business process variable,
then an assign 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:mergeChildNodes(...), ora:getNodes(...)), then this assign is not
created because of the lack of a process variable to copy the payload back. If the
payload need not 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
16-60 Oracle BPEL Process Manager Developer’s Guide
Task Notifications
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
</bpelx:pattern>
</bpelx:annotation>
...
</case>
<otherwise>
<bpelx:annotation>
<bpelx:pattern>Task is EXPIRED, WITHDRAWN or ERRORED
</bpelx:pattern>
</bpelx:annotation>
...
</otherwise>
</switch>
Task Notifications
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.
The notifications for a task can be configured during the creation of a task.
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:
Oracle BPEL Process Manager Workflow Services
16-61
Task Notifications
■
Assigned—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 workflow
–
Task is renewed
–
Task is delegated
–
Task is reassigned
–
Task is escalated
–
Task is resumed (from a suspension)
–
Information for a task is submitted
■
Information is requested for a task
■
Task is suspended
■
Task is errored
■
Task is expired
■
Task is completed
■
Task is withdrawn
■
Reminder
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
■
Creator—the user who created the task
■
Approvers—the users who have approved the task so far
–
This applies in a sequential workflow where multiple users have approved the
task and a notification must be sent to all of them.
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.
See Also: Chapter 15, "Oracle BPEL Process Manager
Notification Service"
Channels Used for Notification
The channel through which a user is notified is determined by the notification
preference attribute of the user as 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
users-properties.xml at
Oracle_Home\integration\orabpel\system\services\config
In an OID-based system, the user properties can be changed using Oracle Delegated
Administration Service. If this attribute is not set, the e-mail channel is used as the
default.
16-62 Oracle BPEL Process Manager Developer’s Guide
Task Notifications
Notification Messages
Notification messages can include static strings and XPath expressions as follows:
<html>
<body>
<%bpws:getVariableData('TaskNotification',
'/taskNotification:taskNotification/taskNotification:
recipientDisplayName')%>
<br>
<%bpws:getVariableData('taskObject', '/task:task/task:title')%>
is assigned to
you. Please act on the task from the <A
href="<%bpws:getVariableData('TaskNotification',
'/taskNotification:taskNotification/taskNotification:
worklistApplicationLink')%>”>
Worklist Application</A>
</body>
</html>
In creating the messages, only two BPEL variables are available to the user—the task
variable and a task notification variable. 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 the XPath tree browsing. The
task notification variable is a transient variable available to get information about the
recipient and assignees.
Table 16–1 lists the elements that are available when using the task notification
variable.
Table 16–1
Elements for the Task Notification Variable
Element Name
Description
recipient
The recipient id
recipientLocale
The locale of the recipient to use in getting messages from
resource bundles for internationalization. Messages from
bundles can be retrieved using the
orcl:get-localized-string(…) extension function.
recipientDisplayName
The display name of the recipient as in the user store (OID,
Active directory, and so on). If no display name is specified,
the convention {lastname}, {firstname} is used.
assignees
A comma-separated string of all the assignee ids.
assigneeDisplayNames
A comma-separated string of all the assignee display names.
worklistApplicationLink
The link to the Worklist Application. This link takes the user
to the particular task for which the e-mail is sent.
actionLinks
If actionable notifications are enabled, the actions link has
text to create HTML links of the format <html
link>custom action<html link><space><html
link>custom action<html link><space>….
processURL
The process URL is useful to look up a resource bundle that
is deployed with the BPEL suitcase. Messages from resource
bundles can be retrieved using the
orcl:get-localized-string(…) extension function.
The first argument in this function is the base URL. If the
message bundle is deployed with the suitcase, the base URL
can be retrieved using the processURL element of the task
notification BPEL variable.
Oracle BPEL Process Manager Workflow Services
16-63
Task Notifications
Any XPath extension function that can only be evaluated within the context of a
business process such as ora:getProcessURL() or ora:getInstanceId()
cannot be evaluated in the task notifications. Task attributes such as processName,
processVersion, instanceId, and domainId can be used for these purposes.
E-mail Approval
Task actions can be performed through e-mail, if the task is set up to enable e-mail
actions. (The same actions can also be performed from the 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
actionableEmailAccount in the XML file Oracle_
Home\integration\orabpel\system\services\config\wf_config.xml.
For example:
<workflowConfigurations
xmlns="http://xmlns.oracle.com/pcbpel/humanworkflow/configurations">
<actionableEmailAccount>AccountReceiving</actionableEmailAccount>
...
</workflowConfigurations>
Figure 16–42 shows where you specify if the e-mail message is an actionable message.
Figure 16–42
Notification Service Wizard - Step 1 of 1: Specify Email Parameters
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
16-64 Oracle BPEL Process Manager Developer’s Guide
Task Notifications
the interval between the reminders can also be configured. The message marked for
reminders (REMINDER) is used, and if there is no such message, the message meant for
the assignees when the task is assigned is used to send reminders.
Reminders can be added in the task configuration file. In the task configuration file,
the reminder element is added inside the notifications element as follows:
<taskType ......... >
<task actionableNotifications="YES">
..........
</task>
<notifications>
<reminder recurrence="1" relativeDate="ASSIGNED">PT3H</reminder>
<action name="REMINDER">
<messages recipient="ASSIGNEES"
xmlns:ns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
.............
</messages>
</action>
<action name="ASSIGNED">
<messages recipient="ASSIGNEES"
xmlns:ns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
.............
</messages>
</action>
</notifications>
</taskType>
The recurrence specifies the number of times reminders are sent. The possible
values for recurrence are EVERY, NEVER, 0, 1, 2 …, 10.
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.
The value for the reminder element itself is 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 EXPIRED, 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
Oracle BPEL Process Manager Workflow Services
16-65
Payload Display
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 EXPIRED, 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.
Payload Display
The task payload is an XML structure that must be displayed in a usable form in the
Worklist Application. You have three options for displaying the payload in the
Worklist Application:
■
Autogenerated JSP
■
XSL
■
The Custom JSP URL
As Figure 16–43 shows, any of these options can be selected as the payload display
mechanism in the Workflow wizard. The Payload field is expecting a
bpws:getVariableData function that gets the payload root from a BPEL process's
variable data.
Figure 16–43
Workflow Wizard - Step 3 of 6: Task Details
Autogenerated JSP
When the Auto generate JSP form option is selected, two files, a default JSP file and a
mapping file, are automatically generated to display the payload at the end of the
Workflow wizard.
16-66 Oracle BPEL Process Manager Developer’s Guide
Payload Display
The name of the default JSP file, task_name_WF_Form.jsp, is generated based on
your task name. The file is added to the HTML root directory of your project, which is
by default the public_html directory.
Along with the default JSP file, a mapping XML file is also generated. It is named
task_name_WF_Fields.xml, and is added to the root directory of your project.
Behind the scenes, the JSP run-time library and the OraBPEL library are automatically
added to your BPEL project for compilation of the JSP file.
The default JSP was 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 WYSIWYG 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>
</schema>
This XSD has the structure shown in Figure 16–44.
Oracle BPEL Process Manager Workflow Services
16-67
Payload Display
Figure 16–44
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.
16-68 Oracle BPEL Process Manager Developer’s Guide
Payload Display
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. As
an example, in the payload field in Figure 16–43 on page 16-66, 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 showable fields. The root element in the mapping file
contains its targetNameSpace, other namespaces, showXmlView, and
xmlEditable as its attributes.
The payload, by default, shows only the HTML form view. It also has an XML source
view that can be used to set payload XML directly. ShowXmlView identifies if the
XML source view is enabled, while xmlEditable identifies if the XML source view in
the payload presentation is editable or not. ShowXmlView is set to false by default,
while xmlEditable is set to true.
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.
Oracle BPEL Process Manager Workflow Services
16-69
Payload Display
Note: Do not modify this XPath field because it is also a unique key
that determines the identity of the field.
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.
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. To do that, you modify your taskConfigtaskName.xml file. Add
two attributes—resourceBundleName and resourceBundleLocation—to the
top element, task. The resourceBundleLocation attribute points to a JAR file,
and resourceBundleName specifies the resource bundle’s file name in the JAR file.
The resourceBundleLocation attribute is optional for globalization purposes.
The following code shows an example of taskConfig<taskName>.xml:
<taskType name="taskConfigSimpleWorkflow2.xml"
resourceBundleName="MyBundle"
targetNamespace="http://taskTypes/taskConfigSimpleWorkflow2.xml"
features="xpathNotification"
xmlns:tns="http://taskTypes/taskConfigSimpleWorkflow2.xml"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:xp20="http:
//www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20"
xmlns:ldap="http://schemas.oracle.com/xpath/extension/ldap"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:Notification="http:
//xmlns.oracle.com/pcbpel/taskservice/taskNotification"
xmlns:client="http://xmlns.oracle.com/i18nProcess"
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns="http://xmlns.oracle.com/pcbpel/taskservice/tasktype"
xmlns:ns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"
xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
xmlns:task="http://xmlns.oracle.com/pcbpel/taskservice/task"
xmlns:orcl="http:
//www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc">
<task actionableNotifications="YES"
xmlns="http://xmlns.oracle.com/pcbpel/taskservice/tasktype">
<conclusions>
<conclusion name="ACCEPT">
<displayValue>getMessage(ACCEPT_MSG)</displayValue>
</conclusion>
...
</taskType>
MyBundle 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>
16-70 Oracle BPEL Process Manager Developer’s Guide
Payload Display
<xpath>/ns0:task/ns0:payload/taskTitle</xpath>
<editable>true</editable>
<resourceKey>TASK_TITLE</resourceKey>
</field>
then calling
PayloadUtil.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.
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 JDeveloper BPEL
Designer.
By default, all the fields are set to text field. If you want to change text field to text
area, you can do the following. In the Component Palette, select Text Area, as shown
in Figure 16–45. Drop it into the position of the text field you want to replace. Note
that the name of the text field is set by calling the function
PayloadFormGenerator.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. Set the text area’s name and value to the
same name and value as text field. Delete the text field.
Oracle BPEL Process Manager Workflow Services
16-71
Payload Display
Figure 16–45
JDeveloper BPEL Designer JSP Design View
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.
If the place you want to insert HTML elements that 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.
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. 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 UpdateServlet that expects certain values. If your change is
complicated and has programming logic in it, you must switch to the source view and
modify the JSP code directly. See "The Custom JSP URL" on page 16-74 for a
lightweight code analysis of the JSP.
See Also: The HelpDeskServiceRequest demo in Oracle_
Home\integration\orabpel\samples\demos for an example of
an autogenerated JSP and how to change the payload presentation
By putting the statement <%@ page pageEncoding="UTF-8" %> in the default JSP,
UTF-8 is set as the default encoding. If you want to modify this statement to set the
JSP to other encoding, for example ISO, then you must also change UpdateServlet.
To do this, add one encoding element in the taskConfigtask_name.xml file. The
modified file looks as follows:
16-72 Oracle BPEL Process Manager Developer’s Guide
Payload Display
<taskType>
<task>
...
<payloadDisplay>
<jsp>defaultWFPayloadJSP</jsp>
<xpathFile>taskConfigSimpleWorkflowWithAutomaticEscalation
1_WF_Fields.xml</xpathFile>
<encoding>ISO</encoding>
</payloadDisplay>
</task>
</taskType>
Multibyte Payload in the Task Detail JSP
To ensure that a multibyte payload is correctly displayed on the Task Detail page,
modify the TaskConfigtask_name.xml file that is generated during design time by
adding the following element as a child element of PayloadDisplay:
<encoding>character_set_used_for_JSP</encoding>
If this element is not specified, UTF-8 is used by default.
Deploying the Autogenerated JSP
Using JDeveloper BPEL Designer, you can deploy your BPEL project directly to OC4J.
When you deploy your project, the default JSP file is deployed at
Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\applications\hw_
services\
worklistxpress\payload\bpel_process_name_bpel_process_version\
Because every autogenerated JSP is named based on its task name only, by deploying
the JSPs under their corresponding bpel_process_name_bpel_process_
version directories, there are no collisions.
On other platforms, the same directory structure is used.
If you choose to deploy your project on OC4J by using obant, ensure that you copy
the autogenerated JSP file to the preceding directory by inserting a copy statement
like the following to your project’s build.xml file.
<copy todir="${home}/system/appserver/oc4j/j2ee/home/applications/hw_
services/worklistxpress/payload/bpel_HelpDeskServiceRequest_1.0">
<fileset dir="public_html">
<include name="*.jsp" />
</fileset>
</copy>
If you make changes to your JSP or mapping file, you must deploy your BPEL project
after the modifications.
See Also: The HelpDeskServiceRequest demo in Oracle_
Home\integration\orabpel\samples\demos for more
information on the build.xml file
XSL
Another payload display option is to provide an XSL file that transforms the payload
XML instance to HTML. The root of the XML instance that is to be transformed is the
{http://xmlns.oracle.com/pcbpel/taskservice/task}payload element.
The payload itself cannot be updated using this option.
Oracle BPEL Process Manager Workflow Services
16-73
Payload Display
See Also: Oracle_
Home\integration\orabpel\samples\demos\OrderApproval
for an example in which an XSL file is used to display the payload
The Custom JSP URL
A custom JSP can display the payload in the Worklist Application. This section
describes how to write a JSP for payload presentation. Before deciding on writing a
custom JSP, evaluate if the default payload JSP can be modified to suit your needs,
since modifying the default JSP is the easiest way to construct your JSP. See
"Customizing the Autogenerated JSP" on page 16-69 for how to generate and modify
the default payload JSP.
Code analyzing an autogenerated payload JSP helps you formalize how to write your
JSP. The autogenerated JSP imports oracle.tip.pc.api.worklist.payload.*.
This package contains classes used to access payload values.
The first section of the default JSP gets the payload object from the task object. No null
checking is done for these variables in the JSP file because these checks are done before
calling the JSP.
A form object is created from the task object. This form object represents the mapping
file. The optional login page, next page, and error page are received from the
parameter list in case they are needed in the JSP.
The call to PayloadFormGenerator.getRequiredFormParameters() returns a
map of required parameters that must be sent to the JSP and the update payload
servlet. This map contains parameter names (keys) and parameter values (values).
Ensure that, in the payload JSP, you call this method and send these parameters so that
the update payload servlet functions properly.
The next section contains code that presents the payload. The first div block gives the
XML view of the payload, while the second div block provides the HTML form view.
Notice that the name of every form parameter is the result of calling
PayloadFormGenerator.constructName(xpath). This is because there are
illegal characters in XPath while used as HTTP parameters. Ensure that the JSP calls
this function to construct parameter names for the particular XPath.
Form.getField(xpath) gets the field from the mapping file. Since the custom JSP
does not use a mapping file, this function need not be called.
PayloadFormGenerator.selectNodeValue() is the function that gets the value
of the given XPath from the payload. The namespace map must be passed to this
function.
Your JSP can use the update servlet provided in the application.
PayloadConstant.UPDATE_SERVLET_URL stores the URL of the payload update
servlet.
The update servlet expects the following required parameters to be set:
PayloadConstant.WORKLIST_CONTEXT_PARAMETER_NAME
PayloadConstant.WORKLIST_TASKID_PARAMETER_NAME
And these optional parameters:
PayloadConstant.WORKLIST_TASK_VERSION_PARAMETER_NAME (optional)
PayloadConstant.WORKLIST_ERROR_PAGE_PARAMETER_NAME (optional)
PayloadConstant.WORKLIST_LOGIN_PAGE_PARAMETER_NAME (optional)
PayloadConstant.WORKLIST_NEXT_PAGE_PARAMETER_NAME (optional)
16-74 Oracle BPEL Process Manager Developer’s Guide
Configuration for Task Service
The preceding parameter names and their corresponding values can be obtained by
calling the PayloadFormGenerator.getRequiredFormParameters() function.
It also expects certain parameters to be defined in the servlet’s session object, but you
need not be concerned about these parameters in your JSP file.
For all payload updates, the custom JSP must send the names and values of the fields
that have to be updated. The names are constructed by calling
PayloadFormGenerator.constructName(String xpath).
The update servlet must know what the prefixes represent in the XPath. Therefore, a
namespace map must be sent to the servlet. Any parameter whose name starts with ns
and is followed by a numeric number is assumed to be a namespace prefix. Its value is
the namespace value. You should always send parameter ns0 with its value
PayloadConstant.NS_ROOT_URL.
APIs
As with the autogenerated JSP, the JSP run-time library and the OraBPEL library are
automatically added to your BPEL project for compilation of the custom JSP file.
See: Oracle_
Home\integration\orabpel\docs\workflow\oracle\tip\pc
\api\worklist\payload for Javadoc API documentation
Customizing the Complete Task JSP
The previous sections described how you can customize the look and feel of the
payload portion of the task using a custom JSP, XSL, or by modifying the
autogenerated JSP. You can also override the complete JSP, including the header (task
attributes and actions section) and the footer (attachment, comments section) by
specifying a custom JSP to display the entire task details. The payload JSP URL is
captured in the task configuration XML file in the element payloadDisplay, as
follows:
<taskType ...>
<task ...>
...
<payloadDisplay>
<jsp>http://localhost:9700/payloads/vacationrequest/payload.jsp</jsp>
</payloadDisplay>
...
</notifications>
</taskType>
Configuration for Task Service
The following sections discuss how to configure task services.
Autorelease Duration
If a task is assigned to groups or multiple users, one of the users in the group or the list
of users must acquire the task before acting on it. After the task is acquired, none of the
initial assignees can see the task if the task was assigned to them. If the user does not
act within a given time, the task is automatically released so that all the other users in
the group or list of users can see it. A particular business process can disable the
autorelease by making autorelease a restricted action. See "Restricted Actions" on
page 16-16 for more information.
Oracle BPEL Process Manager Workflow Services
16-75
Configuration for Task Service
The release duration is configurable in the file wf_config.xml at
Oracle_Home\integration\orabpel\system\services\config
The configurations for the autorelease durations are in the element
taskAutoReleaseConfiguration. The release durations can be configured for
tasks of each priority. For each priority, the autorelease duration can be specified as a
percentage of the expiration (the percentageOfExpiration attribute) duration or a
default value (the default attribute). The default values are used when the task does
not have an expiration duration. The datatype of default 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.
For example, if the task of priority 3 is acquired at 3/24/2005 10:00 AM and the task
expires at 3/31/2005 10:00 AM, then the time left for expiration is 7 days. If the
percentageOfExpiration for priority 3 tasks were 50, then the task is released at
3/37/2005 10:00 PM (3 ½ days from when it was acquired).
The taskAutoReleaseConfiguration element in the configuration file is shown
as follows:
<workflowConfigurations
xmlns="http://xmlns.oracle.com/pcbpel/humanworkflow/configurations">
<taskAutoReleaseConfigurations>
<taskAutoRelease priority="1"
<taskAutoRelease priority="2"
<taskAutoRelease priority="3"
<taskAutoRelease priority="4"
<taskAutoRelease priority="5"
</taskAutoReleaseConfigurations>
default="P1D"
default="P2D"
default="P3D"
default="P4D"
default="P5D"
percentageOfExpiration="30"/>
percentageOfExpiration="40"/>
percentageOfExpiration="50"/>
percentageOfExpiration="60"/>
percentageOfExpiration="70"/>
</workflowConfigurations>
Actionable E-mail Accounts
Task actions can be performed through e-mail. The 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 property
oracle.tip.pc.services.hw.taskservice.actionableEmailAccount at
Oracle_Home\integration\orabpel\system\services\config\pc.properties
Worklist Application URL
In the e-mails that are sent for tasks, the link to the Worklist Application is read from
the XML file wf_config.xml at
Oracle_Home\integration\orabpel\system\services\config\
The element worklistApplicationURL identifies the URL. Configuring this is
useful if the custom Worklist Application is built. The tag PC_HW_TASK_ID_TAG in
this URL is replaced with the task id when constructing the URL for the e-mail.
<workflowConfigurations
xmlns="http://xmlns.oracle.com/pcbpel/humanworkflow/configurations">
<worklistApplicationURL >
http://localhost:9700/integration/worklistapp/TaskDetails?taskId=PC_HW_TASK_ID_TAG
16-76 Oracle BPEL Process Manager Developer’s Guide
Identity Service
</worklistApplicationURL >
...
</workflowConfigurations>
Identity Service
This section describes the identity service component of Oracle BPEL Process
Manager. 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.
Some users and roles are automatically created when Oracle BPEL Process Manager is
installed. Seeded users include:
■
guest
■
default
■
bpeladmin
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 need not 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.
Note: The BPMPublic role can be used and explicitly granted to each
user if a third-party provider does not support an implicit PUBLIC
role.
■
■
■
■
■
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, then 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 process owner can
change the outcome of the task.
BPMSystemAdmin—Both BPMWorkflowAdmin and BPMSystemAdmin have the
same level of workflow privileges.
Oracle BPEL Process Manager Workflow Services
16-77
Identity Service
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.
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
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 16–46.
Figure 16–46
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 are used to 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.
See Also: Oracle Application Server Containers for J2EE User’s Guide
16-78 Oracle BPEL Process Manager Developer’s Guide
Identity Service
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 are used to retrieve these details.
Custom User Repository Plug-ins
This mode enables UPI to define a new custom identity service provider to plug in a
specific non-LDAP-based user repository. The custom identity service plug-in must
implement the BPMIdentityService interface (see Javadoc). This
identityservice class name must be registered in is_config.xml. See "User and
Role Properties" on page 16-80 for more information.
See Also:
■
■
See Oracle_
Home\integration\orabpel\docs\workflow\oracle\tip
\pc\services\identity for Javadoc on the
BPMIdentityService interface
See Oracle_
Home\integration\orabpel\samples\hw\isplugin\db\D
BPlugin.htm for instructions on how to write a custom identity
service provider plug-in
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 users and groups 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:
Oracle BPEL Process Manager Workflow Services
16-79
Identity Service
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 the XML-based provider, then you must supply a username and
password to the Admintool. If you are using the LDAP-based provider, you need
not specify the -user and -password arguments.
■
If you are using a third-party LDAP server or a custom user repository, you must
use the specific tools available for that directory.
User and Role Properties
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
■
Time zone
■
Preferred language
■
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. Also, automatic escalation and manager
views are not available if the manager field is not available to identity service.
The following OID objectClasses are used to specify user and role properties such
as mail, manager, and telephoneNumber.
■
top
■
person
■
–
cn
–
sn
–
description
–
telephoneNumber
organizationalPerson
16-80 Oracle BPEL Process Manager Developer’s Guide
Identity Service
■
■
■
–
title
–
telephoneNumber
–
facsimileTelephoneNumber
inetOrgPerson
–
displayName
–
givenName
–
manager
–
mail
–
homePhone
–
mobile
–
pager
–
preferredLanguage
orclUserV2
–
middleName
–
orclTimeZone
–
orclWorkflowNotificationPref
orclGroup
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
Oracle_Home\integration\orabpel\system\services\config
Configuring Identity Service
The following sections describe how to configure identity services.
Structure of the Identity Service Configuration File
Identity service configuration is defined in the is_config.xml file. The file must be
located in a directory that is included in the CLASSPATH of Oracle BPEL Process
Manager. By default, it is stored in
Oracle_Home\integration\orabpel\system\services\config
The XML schema for the is_config.xml file is stored in
Oracle_Home\integration\orabpel\system\xmllib\workflow\xsd
Figure 16–47 shows the structure of the BPMIdentityService configuration.
Oracle BPEL Process Manager Workflow Services
16-81
Identity Service
Figure 16–47
BPMIdentityService Configuration
The identity service configuration file (as defined by is_config.xsd) consists of a
root element BPMIdentityServiceConfig, which can have only one provider. As
discussed previously, identity service supports the following main plug-in types:
JAZN provider, third-party LDAP directories, or custom repository plug-ins.
The provider element specifies the providerType, which can be JAZN, LDAP, or
CUSTOM, provider name (optional), and any provider-specific properties.
For example, in the case of the JAXN XML provider, you must set the providerType
attribute to JAZN and specify the value of the userPropertiesFile attribute. See
"Configuration for the XML-Based JAZN Provider" on page 16-85 for more
information about userPropertiesFile.
Similarly, if you use a custom plug-in to the identity service, you must set the
providerType attribute to CUSTOM. You then specify the class name for custom
identity service plug-in implementation, as follows:
<BPMIdentityServiceConfig
mlns="http://www.oracle.com/pcbpel/identityservice/isconfig" >
<provider providerType="CUSTOM"
name="CustomPlugIn"
class="package.name.CustomIdentityService"
</provider>
</BPMIdentityServiceConfig>
In addition, the provider can define the following optional parameters in the
configuration file. Most of these parameters apply to JAZN-based or LDAP-based
providers, but can be used by custom providers also.
connection Element The connection element is used to specify the URL, admin
username (binddn- bind as this Distinguished name), the credential (password) for the
LDAP or RDBMS connection used by the identity service, and a Boolean flag
(encrypted) to specify that the password is either in plain text or is encrypted.
Identity service overwrites the is_config.xml file after reading the configuration
and encrypts the user password if it finds the password in plain text. Figure 16–48
shows the structure of the connection configuration.
16-82 Oracle BPEL Process Manager Developer’s Guide
Identity Service
Figure 16–48
connection Configuration
The connection can specify connection pool properties by setting the following
attributes on the pool element:
■
initsize—initial size of the connection pool
■
maxsize—maximum size of the connection pool
■
prefsize— preferred size of the pool
■
timeout—time after which the connection is released if there is no activity (in
seconds)
The LDAP plug-in for identity service uses the following default values:
■
initsize="2"
■
maxsize="25"
■
prefsize="10"
■
timeout="60"
If you are using a custom identity service plug-in, you can also specify any additional
connection-specific properties as name-value pairs.
userControls and roleControls Elements The userControls element is used to define
user controls and to restrict the LDAP user search. Figure 16–49 shows the structure of
the userControls element.
Oracle BPEL Process Manager Workflow Services
16-83
Identity Service
Figure 16–49
userControls Element
The roleControls element is used to define role controls and restrict the LDAP role
search. Figure 16–50 shows the structure of the roleControls element.
Figure 16–50
roleControls Element
Both userControls and roleControls can have a search element that has the
following optional attributes:
■
■
■
■
searchbase—a list of LDAP entries, the distinguished names (DNs) of user or
group containers.
maxSizeLimit—the maximum number of elements that are fetched from LDAP
during a search operation
maxTimeLimit—the maximum time to wait to retrieve elements from an LDAP
search
scope—determines the search level. The value can be onelevel, in which the
search descends one level from the supplied DN or subtree, in which the search
descends the hierarchy from the DN to the lowest level in the tree.
By default, the LDAP provider for identity service uses the following values:
maxSizeLimit ="1000", maxTimeLimit ="120" (sec), and scope="subtree".
16-84 Oracle BPEL Process Manager Developer’s Guide
Identity Service
provider Element The provider element enables specifying additional property
elements, which can be used by custom plug-ins. An example follows:
<BPMIdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig" >
<provider providerType="CUSTOM" name="db2"
class="package.name.CustomIdentityService"
<property name="customProperty" value="customValue" />
</provider>
</BPMIdentityServiceConfig>
In addition, the property element can be defined as part of any of the other elements
(userControls, searchControls, search, and so on) in the configuration file.
Configuration for the XML-Based JAZN Provider
The JAZN element jazn provider="XML" location="./jazn-data.xml"/ is
in
Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\
application-deployments\hw-services\orion-application.xml
and
Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\config\jazn.xml
The identity service configuration file must specify the userPropertiesFile
property and provide the value of the file name where all user properties are stored:
<IdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig"
xmlns:isc="http://www.oracle.com/pcbpel/identityservice/isconfig"
providerType="jazn">
<provider name="xml"
<property name="userPropertiesFile" value="users-properties.xml"/>
</provider>
</IdentityServiceConfig>
Note that the users-properties.xml file from that example stores all extended
user's properties. This is not required for JAZN authorization or authentication.
However, the BPEL identity service requires this file to get contact details and the
organizational hierarchy for users. If this file is not created, then certain workflow
functionality such as notifications, manager views, or task escalation may not work. By
default, the identity service looks for users-properties.xml in the Oracle BPEL
Process Manager classpath. Oracle Universal Installer stores the default
users-properties.xml in
Oracle_Home\integration\orabpel\system\services\config
JAZN documentation for how to configure the middle
tier to use the XML-based JAZN provider
See Also:
Configuration for the LDAP-Based JAZN Provider (OID)
If you select the Identity Management Access option during BPEL Process Manager
for OracleAS Middle Tier installation, the identity service is automatically configured
with OID. For all other installation scenarios, you must manually configure the
LDAP-based JAZN provider (OID) in two steps:
■
OID Configuration
■
Middle-Tier Configuration
Oracle BPEL Process Manager Workflow Services
16-85
Identity Service
OID Configuration Use the OID Migration Tool to load Oracle BPEL Process Manager
users and roles into OID. The OID Migration Tool can produce LDIF files for system
and demo users, which are suitable for loading into a directory server by using
standard command-line tools. The input to this tool is a pseudo-LDIF file containing
substitution variables. The tool is called ldifmigrator and is found in Oracle_
Home/bin. (See Oracle Identity Management Integration Guide for more information.)
The following predefined substitution variables are used in the file:
Substitution Variable
Value
Description
%s_UserContainerDN%
Distinguished name of the
entry under which all users
are added.
This is assigned the value of
the attribute:
orclCommonUserSearchBa
se from the entry
cn=Common,cn=Products
under the realm-specific
Oracle context.
%s_GroupContainerDN%
Distinguished name of the
entry under which all public
groups are supposed to be
added.
This is assigned the value of
the attribute:
orclCommonGroupSearchB
ase from the entry
cn=Common,cn=Products
under the realm-specific
Oracle context.
Note: The system and demo users must have passwords consistent
with password policy. Password policy can be verified with Oracle
Directory Manager. See the Password Syntax tab page of the
Password Policies page. See Oracle Internet Directory Administrator’s
Guide for additional details.
You can use the command-line variable s_UserCommonNamingAttribute with the
migration tool, which substitutes all occurrences of it with the value provided in the
command-line.
For example:
$ldifmigrator "input_file=system-oid.sbs" "output_file=system-oid.ldif" -lookup
"host=ldap.acme.com" "port=389" "subscriber=acme" "s_UserCommonNamingAttribute=cn"
dn="cn=admin" password=welcome
$ldifmigrator "input_file=demo-oid.sbs" "output_file=demo-oid.ldif"
-lookup dn="cn=admin" password=welcome "host=ldap.acme.com" "subscriber=acme"
"s_UserCommonNamingAttribute=cn"
where the subscriber is the JAZN realm and its name is acme, and cn is used to
construct the user's DN.
The system-oid.ldif file can be loaded to OID with the ldapadd utility.
Optionally, you can load demo-oid.ldif with the ldapmodify command.
For example:
$ldapadd -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f system-oid.ldif
$ldapmodify -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f demo-oid.ldif
16-86 Oracle BPEL Process Manager Developer’s Guide
Identity Service
See Also: Oracle Identity Management Application Developer’s Guide for
information about the ldapadd and ldapmodify commands
Note: By default, when a user enters a search request, OID searches
based on the cn, firstname, lastname, and email attributes. You
can customize the attributes that can be searchable. The user manager
attribute from inetOrgPerson objectClass should be searchable
to allow workflow escalation. Use Oracle Delegated Administration
tools to set it up. The recommended searchable attribute list is cn, sn,
givenName, uid, manager, title, mail, and telephoneNumber.
See Oracle Identity Management Guide to Delegated Administration for
more information.
Middle-Tier Configuration Middle-tier configuration consists of the following steps:
■
Configuring the middle tier to use the LDAP-based JAZN provider
In general, a JAZN XML-based definition should be commented and a new
LDAP-based provider definition is specified in both files:
–
Oracle_
Home\integration\orabpel\system\appserver\oc4j\j2ee\home\c
onfig\jazn.xml
<!-- jazn provider="XML" location="./jazn-data.xml"/ -->
<jazn provider="LDAP" location="ldap://host:port" default-realm="us" >
<property name="ldap.user" value="cn=orcladmin" />
<property name="ldap.password" value="!welcome1" />
</jazn>
where us is a default realm name for this example.
–
Oracle_
Home\integration\orabpel\system\appserver\oc4j\j2ee\home\a
pplication-deployments\hw-services\orion-application.xml
<!-- jazn provider="XML" location="./jazn-data.xml"/ -->
<jazn provider="LDAP" location="ldap://host:port" default-realm="us" />
where us is a default realm name for this example.
Do not place user and password information in orion-application.xml.
Also add the following directive to Oracle_
Home\integration\orabpel\system\appserver\oc4j\j2ee\home\c
onfig\application.xml to allow password indirection management:
<password-manager>
<jazn provider="XML" location="./jazn-data.xml" />
</password-manager>
See Also:
■
■
Oracle JAAS Provider (JAZN) configuration documentation
■
Oracle Application Server Security Guide
Configuring identity service configuration file
Open is_config.xml in
Oracle BPEL Process Manager Workflow Services
16-87
Identity Service
Oracle_Home\integration\orabpel\system\services\config
and define OID provider properties:
<BPMIdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="JAZN" name="oid" >
<connection url="ldap://host:port"
binddn="cn=orcladmin"
password="welcome1" encrypted="false" />
</provider>
</BPMIdentityServiceConfig>
The providerType must point to the JAZN mode. The provider must contain
connection specifications to define OID location, admin user, password and
encrypted flag.
Note: Setting the credentials element as follows enables you to
use clear (readable) passwords in the jazn-data.xml file the first
time:
<credentials>!welcome</credentials>
This enables the administrator to edit jazn-data.xml directly with a
text editor. When the file is read and persistence occurs, the password
in jazn-data.xml is obfuscated and becomes unreadable.
If the password is written in plain text, specify an exclamation point in
front of it.
■
Configuring the middle tier to use the LDAP-based JAZN provider with Secure
Socket Layer (SSL) Support
With 10g Release 2 (10.1.2), you must use NULL authentication when
communicating with Oracle Internet Directory. NULL authentication means that
data is encrypted with the Anonymous Diffie-Hellman cipher suite, but no
certificates are used for authentication.
If you choose SSL at install time, SSL is automatically enabled with NULL
authentication in place. You must manually enable SSL only if you did not choose
SSL as part of your installation.
In that case, for NULL authentication, add a <property> element to the <jazn>
element in jazn.xml and to the <connection> element in is_config.xml to
specify a protocol. You do not need to specify a wallet location or password,
because NULL authentication does not use certificates.
Add the following property element to jazn.xml (shown in bold):
<jazn provider="LDAP" location="ldap://example.com:636" default-realm="us">
<property name="ldap.user" value="cn=orcladmin"/>
<property name="ldap.password" value="!welcome1"/>
<property name="ldap.protocol" value="ssl"/>
</jazn>
Add the following connection element to is_config.xml (shown in bold):
<BPMIdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="JAZN" name="oid" >
<connection url="ldap://example.com:636" binddn="cn=orcladmin"
16-88 Oracle BPEL Process Manager Developer’s Guide
Identity Service
password="welcome1" encrypted="false">
<property name="securityProtocol" value="ssl" />
</connection>
</provider>
</BPMIdentityServiceConfig>
See the Oracle Application Server Containers for J2EE Security Guide for additional
details about JAZN configuration.
Configuration for a Third-Party LDAP Server
Note the following considerations when using a third-party LDAP server. The
configuration for Active Directory is slightly different. These differences are also
described.
Note: This section only describes Active Directory configuration on
Windows 2003. This is because Windows 2000 does not permit nested
security groups.
1.
The third-party LDAP servers must be configured to use the following standard
objectClasses:
For Active Directory
For Other Third-Party LDAP Servers
top
top
person
person
organizationalPerson
organizationalPerson
user
inetOrgPerson
group
groupOfUniqueNames
Usually LDAP servers predefine the list of searchable attributes based on the cn,
firstname, lastname, and email attributes. You can customize the attributes
that can be searchable. The user manager attribute from inetOrgPerson
objectClass should be searchable to allow workflow escalation. See the
documentation for the third-party LDAP server you are using for how to set up
the searchable attribute.
The recommended searchable attribute list is cn, sn, givenName, uid, manager,
title, mail, and telephoneNumber.
2.
When you seed Oracle BPEL Process Manager users and roles into the LDAP
server, the process assumes that the users’ and groups’ container is created in
LDAP. To create system and optionally demo ldif files, open the following
template files in:
Oracle_Home\integration\orabpel\system\services\config\ldap
For Active Directory
For Other Third-Party LDAP Servers
system-winServer2003-ActDir.sbs
system-ldap.sbs
demo-winServer2003-ActDir.sbs
demo-ldap.sbs
demo-roleGrants-winServer2003-ActDir.
sbs
Oracle BPEL Process Manager Workflow Services
16-89
Identity Service
Replace the substitution variables with the appropriate values, as shown in the
following examples. The actual values to enter depend upon your domain:
LDAP Server
Substitution Variable
Replace With Value
Active Directory
%s_UserContainerDN%
cn=Users,dc=us,dc=oracle,dc=com
%s_GroupContainerDN%
cn=Users,dc=us,dc=oracle,dc=com
%s_UserCommonNamingAttribute%
cn
%s_UserContainerDN%
ou=People,dc=ldap,dc=acme,dc=co
m
%s_GroupContainerDN%
ou=Groups,dc=ldap,dc=acme,dc=co
m
Other Third-Party LDAP
Servers
where:
■
■
■
%s_UserContainerDN% with a DN value of the entry under which all users
are supposed to be added. The users container with:
*
dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for
Active Directory
*
dn: ou=People,dc=ldap,dc=acme,dc=com is used in this example for
other third-party LDAP servers
%s_GroupContainerDN% with a DN value of the entry under which all
public groups are supposed to be added. The groups’ container with:
*
dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for
Active Directory
*
dn: ou=Groups,dc=ldap,dc=acme,dc=com is used in this example for
other third-party LDAP servers
%s_UserCommonNamingAttribute% with the value used to construct the
user's DN. In this example for other third-party LDAP servers, the cn value is
used. %s_UserCommonNamingAttribute% and value are not applicable to
Active Directory.
Perform the following steps based on your type of third party LDAP server:
■
For Active Directory:
Run the following commands at the DOS command prompt on Windows
2003:
ldifde.exe -i -k -f system-winServer2003-ActDir.ldif
ldifde.exe -i -k -f demo-winServer2003-ActDir.ldif
ldifde.exe -i -k -f demo-roleGrants-winServer2003-ActDir.ldif
See the following Microsoft Active Directory Documentation for details about
all bulk import options for Active Directory’s ldifde.exe:
http://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies
/directory/activedirectory/stepbystep/adbulk.mspx#ECAA
The Windows system administrator must set passwords for all seeded users;
otherwise, worklist application authentication does not work for those users.
■
For other third-party LDAP servers:
16-90 Oracle BPEL Process Manager Developer’s Guide
Identity Service
Store changes in the system-ldap.ldif and demo-ldap.ldif files. Then
load the system-ldap.ldif file to the LDAP server by using the ldapadd
utility. Optionally, load demo-ldap.ldif with the ldapmodify utility.
For example:
$ldapadd -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f
system-oid.ldif
$ldapmodify -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f
demo-oid.ldif
See the documentation for the third-party LDAP server you are using for
information about the ldapadd and ldapmodify commands.
3.
The identity service third-party LDAP provider must specify connection,
userControls, and roleControls elements in the identity service
configuration file.
Identity service third-party LDAP provider implementation defines a set of user
search properties that must be configured:
■
■
nameattribute—the name of the LDAP attribute that uniquely identifies
the name of the user. In Sun Directory Server, it is uid; in Active Directory, it is
user.
objectClass—the LDAP schema object class used to represent a user. In Sun
Directory Server, it is inetOrgPerson.
And set of role search properties:
■
■
■
■
nameattribute—the name of the LDAP attribute that uniquely identifies
the name of the role. In Sun Directory Server, it is uniqueMember; in Active
Directory, it is member.
objectclass—the LDAP schema object class that is used to represent a
group. In Sun Directory Server, it is groupOfUniqueNames. In Active
Directory, it is group.
membershipsearchscope—specifies how deep in the LDAP directory tree
to search for role membership. Supported values: onelevel or subtree.
memberattribute—The attribute of a static LDAP group object specifying
the distinguished names (DNs) of the members of the group. In Sun Directory
Server, it is uniqueMember; in Active Directory, it is member.
Both userControls and roleControl must define a search element with the
searchbase attribute.
The searchbase attribute of the userControls search element is a space-separated
list of DNs in the LDAP directory that contains users; for example,
cn=users,dc=us,dc=abc,dc=com.
The searchbase attribute of the roleControls search element is a space-separated
list of DNs in the LDAP directory that contains roles; for example,
cn=Groups,dc=us,dc=abc,dc=com
An example of the LDAP server Sun Directory Server configuration follows:
<BPMIdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="LDAP" name="iplanet"
<property name="realmName" value="iPlanetRealm"/>
<connection url="ldap://host:port"
binddn="uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot"
Oracle BPEL Process Manager Workflow Services
16-91
Identity Service
password="welcome" encrypted="false" >
<pool initsize="2" maxsize="25" prefsize="10" timeout="60"/>
</connection>
<userControls >
<property name="nameattribute" value="uid"/>
<property name="objectclass" value="inetOrgPerson"/>
<search searchbase="ou=People,dc=us,dc=oracle,dc=com"
maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
</userControls>
<roleControls >
<property name="nameattribute" value="cn"/>
<property name="objectclass" value="groupOfUniqueNames"/>
<property name="membershipsearchscope" value="onelevel"/>
<property name="memberattribute" value="uniquemember"/>
<search searchbase="ou=Groups,dc=us,dc=oracle,dc=com"
maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
</roleControls>
</provider>
</BPMIdentityServiceConfig>
An example for Microsoft Active Directory follows:
<BPMIdentityServiceConfig
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="CUSTOM" name="Active Directory"
<property name="realmName" value="ActiveDirectoryRealm"/>
<connection url="ldap://host:port"
binddn="cn=administrator,cn=Users,dc=us,dc=oracle,dc=com"
password="welcome" encrypted="false" />
<userControls >
<property name="nameattribute" value="cn"/>
<property name="objectclass" value="user"/>
<search searchbase="cn=Users,dc=us,dc=oracle, dc=com",
maxSizeLimit="1000" maxTimeLimit="120 " scope="onelevel" />
</userControls>
<roleControls >
<property name="nameattribute" value="cn"/>
<property name="objectclass" value="group"/>
<property name="membershipsearchscope" value="onelevel"/>
<property name="memberattribute" value="member"/>
<search searchbase="cn=Users,dc=us,dc=oracle,dc=com"
maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
</roleControls>
</provider>
</BPMIdentityServiceConfig>
Configuration for CUSTOM User Repository Plug-ins
The following example shows how to use configuration properties to configure custom
plug-ins. In this example, the CustomIdentityService class is used to demonstrate
custom repository plug-ins. This class implements the BPMIdentityService
interface.
<BPMIdentityServiceConfig
mlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="CUSTOM" name="CustomProvider"
class="custompakage.CustomIdentityService">
<property name="realmName" value="CustomRealm"/>
<property name="CustomProviderProperty1" value="CustomProviderValue1"/>
16-92 Oracle BPEL Process Manager Developer’s Guide
Identity Service
<property name="CustomProviderProperty2" value="CustomProviderValue2"/>
<connection url="ldap://host:port"
binddn="uid=admin password="welcome" encrypted="false" >
<property name="CustomConnProperty1" value="CustomConnValue1"/>
<property name="CustomConnProperty2" value="CustomConnValue2"/>
</connection>
<userControls>
<property name="CustomControlsProperty1" value="CustomControlsValue1"/>
<property name="CustomControlsProperty2" value="CustomControlsValue2"/>
<search searchbase="ou=UserContainer,dc=us,dc=oracle,dc=com">
<property name="CustomSearchProperty1" value="CustomSearchValue1"/>
<property name="CustomSearchProperty2" value="CustomSearchValue2"/>
</search>
</userControls>
<roleControls >
<property name="CustomControlsProperty1" value="CustomControlsValue1"/>
<property name="CustomControlsProperty2" value="CustomControlsValue2"/>
<search searchbase="ou=GroupContainer,dc=us,dc=oracle,dc=com">
<property name="CustomSearchProperty1" value="CustomSearchValue1"/>
<property name="CustomSearchProperty2" value="CustomSearchValue2"/>
</search>
</roleControls>
</provider>
</BPMIdentityServiceConfig>
In addition to existing provider properties, you can define custom property elements
that can be added to provider, connection, userControls, roleControls, and
search elements in the configuration file to extend provider definitions.
Creating a Custom Identity Service Plug-in
You can write a custom identity service plug-in to integrate into specific third-party
repositories.
Requirements
The custom identity service plug-in must implement the BPMIdentityService
interface. This is the entry point for any identity service provider. See "Implementing
the Identity Service Plug-in" on page 16-94 for details.
See the sample implementation of a custom database plug-in in the Oracle_
Home\integration\orabpel\samples\hw\isplugin\db directory.
Description of Oracle BPEL Process Manager Interfaces
Table 16–2 describes the available interfaces.
Table 16–2
Interface
Interfaces
Description
BPMIdentitySe This is the main interface defining the Oracle BPEL Process Manager
rvice
identity service. For any plug-in, this is the main class that is instantiated
by the Identity Service Manager.
BPMUser
This defines an Oracle BPEL Process Manager user. A user is identified by
a logical name and has various associated attributes such as first name, last
name, e-mail, and so on.
Oracle BPEL Process Manager Workflow Services
16-93
Identity Service
Table 16–2
(Cont.) Interfaces
Interface
Description
BPMRole
This defines an Oracle BPEL Process Manager role. A role is defined as the
permissions or privileges required by a user to perform the tasks related to
their job. Roles are granted to users and groups of users. Roles can be
nested (that is, a role itself can be granted to another role, and so on).
BPMRole defines methods to find all users and roles that are granted a role.
BPMAppRole
This defines an Oracle BPEL Process Manager application role. Derived
from BPMRole, application roles are defined for tasks supported by an
application. This enables users and groups that are granted these roles to
perform all of the tasks related to the application.
BPMGroup
This defines an Oracle BPEL Process Manager group. Derived from
BPMRole, BPMGroup is a convenient way to assign rights and permissions
to several users at one time. All users who belong to a user group are
granted all of that group's permissions or access rights.
BPMProvider
This defines the set of methods and APIs that must be supported for any
third-party repository. This is a convenience interface. This interface makes
it possible to have one identity service implementation that can plug into
different custom providers. You only need to implement this interface for
each of your custom repositories.
BPMIdentity
This defines the common set of methods and APIs for roles and users. Both
BPMUser and BPMRole are derived from this interface.
BPMPrincipal
This represents an identity and defines the common methods for any
identity in the Oracle BPEL Process Manager identity service.
BPMIdentity derives from the BPMPrincipal interface.
See the Javadoc for the different interfaces of identity service at ORACLE_
HOME\integration\orabpel\docs\workflow.
Implementing the Identity Service Plug-in
The identity service plug-in can be implemented in one of two ways:
■
Simple Implementations
For simple implementations, you can use the framework provided in the database
plug-in sample to plug in your providers. This implementation is most suitable for
the following:
■
–
For simple repositories, in which you can implement just one interface and
have the plug-in up and running.
–
For supporting multiple providers, in which you can use the supplied
framework and easily add in the providers.
Advanced Implementations
For complex repositories, in which you can build your own framework and
implement all of the essential interfaces.
Simple Implementations The database plug-in sample provides a generic implementation
that can be reused with any custom third-party repository.
The easiest way to write an identity service for a custom plug-in is to take the existing
database plug-in sample and add the implementation of the BPMProvider interface
for the new custom repository. The BPMProvider interface defines the minimum set
of essential operations that must be defined over a custom repository for the identity
service to function correctly. The database plug-in sample implementation has a
16-94 Oracle BPEL Process Manager Developer’s Guide
Identity Service
DBProvider class to use as a reference. The rest of the code in the database plug-in
sample can be used for any identity service.
The database plug-in sample is located in the ORACLE_
HOME\integration\orabpel\samples\hw\isplugin\db directory. Two
identity service configuration files are provided in the config subdirectory: is_
config.xml and is_config_standalone.xml (for standalone testing with no
Oracle BPEL Server).
The sample is written as a custom plug-in based on a database-based repository. All
the database-related queries are localized to the DBProvider code. The rest of the
classes in the sample are generic and independent of the provider. This design permits
reuse of the database plug-in code for different plug-ins. See the dbplugin.htm file
in the ORACLE_HOME\integration\orabpel\samples\hw\isplugin\db
directory for more details on the database structure and tables.
The database plug-in sample includes the following key files in ORACLE_
HOME\integration\orabpel\samples\hw\isplugin\db\src:
■
CustomIdentityService.java
This class is the implementation of BPMIdentityService. This is the entry point
for instantiation of IdentityService. At instantiation, this class invokes the
ProviderFactory::getInstance method to get an instance of the current
BPMProvider. All other methods in this class delegate the request to the
BPMProvider instance, as shown in this example:
public class CustomIdentityService implements
BPMIdentityService {
private BPMProvider m_provider;
. . .
. . .
public CustomIdentityService() throws
BPMIdentityException {
Logger.debugLog("about to load provider");
. . .
. . .
ProviderFactory provFactory =
ProviderFactory.getInstance();
m_provider =
(BPMProvider)provFactory.getProvider();
Logger.debugLog("provider initialization complete");
. . .
. . .
}
. . .
. . .
public List getUsers() throws BPMIdentityException {
return m_provider.getUsers();
}
■
DBProvider.java
This class is the implementation of the BPMProvider interface. The
BPMProvider defines the minimal set of methods that must be defined for any
custom repository for an identity service plug-in. This class implements all
database-related queries so that the rest of the classes are generic. The
getInstance() method is called by the ProviderFactory to get an instance
Oracle BPEL Process Manager Workflow Services
16-95
Identity Service
of this class. See the Javadoc for the complete definition of the BPMProvider
interface.
■
ProviderFactory.java
This class is the factory class responsible for creating instances of the currently
active custom provider. The current provider is determined by the <provider>
element specified in the identity service configuration file. Users can switch to
different providers by updating the configuration file. The ProviderFactory
provides a getProvider() method that returns an instance of the currently
active custom provider (of type BPMProvider). This method only supports
custom providers. For all other providers, this method returns null. Because the
current provider is determined from the configuration, you can add different
provider implementations to the sample and switch to required providers as
necessary without recompilation.
The following code instantiates the currently active BPMProvider:
public static BPMProvider getProvider() throws Exception
{
......
......
// Currently supports DB Provider
// Extend for other providers
if( provCfg.getProviderType().equals(ISConfigSchemaConstants.CUSTOM_
PROVIDER))
{
Class providerClass;
String packNm = provCfg.getProviderClass();
int len = packNm.lastIndexOf('.');
String providerClsName = provCfg.getProviderName();
// Provider name is fully qualified
if( providerClsName.lastIndexOf('.') > 0 )
providerClass = Class.forName(providerClsName);
// Provider is in the same package as IdentityService
else providerClass = Class.forName(packNm.substring(0,len +1) +
providerClsName);
Method m = providerClass.getDeclaredMethod("getInstance", null);
BPMProvider provider = (BPMProvider)m.invoke(null, null);
return provider;
}
return null;
}
The following configuration file example provides additional details about
getProvider().
<provider providerType="CUSTOM" name="DBProvider" class =
"IdentityServiceCustomPlugin.CustomIdentityService">
The getProvider() code performs the following tasks:
–
Determines the type of provider
–
If the type is a CUSTOM provider, then:
*
Gets the class name
This is the fully-qualified name of the class that implements BPMIdentityService. For example, IdentityServiceCustomPlugin.CustomIdentityService is the fully-qualified class for this example.
16-96 Oracle BPEL Process Manager Developer’s Guide
Identity Service
*
Gets the name of the custom provider
The ProviderFactory uses the name to determine the class that implements the BPMProvider interface. In the database plug-in example
above:
name="DBProvider"
The getProvider() method then appends the classpath to the name to
get the fully qualified class name. In the example above, the fully qualified class name becomes IdentityServiceCustomPlugin.DBProvider. The method implicitly assumes that the DBProvider class is in
the same package as CustomIdentityService.
*
Invokes the getInstance() method on the loaded class.
The getInstance() method returns a newly created instance of the
BPMProvider implementation. In the example above, the getProvider() method returns an instance of the DBProvider.
■
CustomRoleImpl.java
This class is an implementation of BPMRole. This is an abstract class.
CustomAppRoleImpl and CustomGroupImpl are subclasses of this class that
use this implementation. This implements methods such as toNode() and
equals(Object obj). For all other methods, this class delegates or calls the
corresponding method on the DBProvider class. See the Javadoc for the complete
definition of the BPMRole interface.
■
CustomUserImpl.java
This is an implementation of the BPMUser interface. This class implements
methods to get and set user attributes such as name, first name, e-mail, and so on.
This class delegates all provider-related requests to DBProvider.
Using the database plug-in generic implementation, you can develop a custom plug-in
by performing the following tasks:
■
■
■
■
Implement the BPMProvider interface for the new provider. DBProvider can be
used as a reference implementation. This can be in a new package or in the same
package as the database plug-in.
Add the new BPMProvider code to the database plug-in code. It is best to copy
all of the sample files to a new directory, along with the provider code.
Optionally modify the ant build script to rename the IS-DBPlugin.jar file
(created by the database plug-in sample) for the new provider.
Follow the steps outlined in "Deploying the Identity Service Plug-in" on
page 16-98 and "Registering and Configuring Identity Service for the Custom
Plug-in" on page 16-98 for the new provider.
Advanced Implementations You can implement all of the essential interfaces such as
BPMIdentityService, BPMUser, and BPMRole for the custom repository. This may
be necessary for advanced use cases or complex repositories. In these cases, use the
database plug-in as a sample implementation.
Implement all of the following interfaces for the custom plug-in:
■
BPMIdentity
■
BPMPrincipal
■
BPMUser
Oracle BPEL Process Manager Workflow Services
16-97
Identity Service
■
BPMRole
■
BPMAppRole
■
BPMGroup
■
BPMIdentityService
■
BPMProvider (optional; it is not necessary to implement BPMProvider)
See the Javadoc for the different interfaces of the identity service at Oracle_
Home\integration\orabpel\docs\workflow.
Deploying the Identity Service Plug-in
For the workflow services to instantiate and invoke the plug-in, it must be deployed to
a location in the library path of Oracle BPEL Process Manager. For example, for the
database plug-in:
■
■
The command obant deploy compiles the sample files and then assembles a
JAR file that is copied to the Oracle_
Home\integration\orabpel\services\lib location. The database plug-in
is assembled into a JAR file named IS-DBPlugin.jar and deployed to the
Oracle_Home\services\lib location. See the Oracle_
Home\integration\orabpel\samples\hw\isplugin\db\build.xml file
for more details.
The plug-in must be deployed and the library path must point to this JAR file. The
IS-DBPlugin.jar file is added to the library path by adding the following lines
to the application.xml file (found in the Oracle_
Home\system\appserver\oc4j\j2ee\home\config directory)
<library path="D:\OraBPELPM_
1\integration\orabpel\system\services/lib/IS-DBPlugin.jar"/>
The same scheme of deployment can be used for any custom plug-in, with minor
changes such as the name of the provider JAR file.
Registering and Configuring Identity Service for the Custom Plug-in
Identity service configuration in defined in the is_config.xml file. The file must be
located in a directory that is in the classpath of Oracle BPEL Process Manager. By
default, it is stored in Oracle_Home\system\services\config.
The identity service configuration file consists of a root element
BPMIdentyServiceConfig, which can have only one provider. For any custom
service, the providerType attribute is set to CUSTOM (since this is a custom
provider).
The following sample configuration file describes the database plug-in implemented
as a custom provider (for more details, see the configuration file in ORACLE_
HOME\integration\orabpel\samples\hw\isplugin\db).
<BPMIdentityServiceConfig xmlns =
"http://www.oracle.com/pcbpel/identityservice/isconfig">
<provider providerType="CUSTOM" name="DBProvider" class =
"IdentityServiceCustomPlugin.CustomIdentityService">
<connection>
<property name="dataSource" value="jdbc/BPELSamplesDataSource"/>
</connection>
</provider>
</BPMIdentityServiceConfig>
16-98 Oracle BPEL Process Manager Developer’s Guide
Identity Service
Table 16–3 describes the components of the sample configuration file.
Table 16–3
Components
Component
Description
provider element
The provider element specifies the providerType. For custom
providers, this is CUSTOM.
name and class attributes
The class attribute is used to instantiate an IdentityService
of the specified class type. The name attribute is used by the
CustomIdentityService implementation to identify the
name of the BPMProvider class to instantiate. In the example
above, DBProvider is the implementation of
BPMCustomProvider, which handles all database queries as
well as processing. This model permits the
CustomIdentityService to be reusable with different
providers and data sources.
connection element
The connection element specifies the data source to which to
connect. For custom providers, this is defined by custom
properties.
dataSource property
This defines the JNDI name of the data source to which to
connect. This data source is defined in the data-sources.xml
file in the Oracle_
Home\integration\orabpel\system\appserver\oc4j\
j2ee\home\config directory.
<property name="dataSource"
value="jdbc/BPELSamplesDataSource"/>
Custom plug-ins can define name-value properties as required for their data source.
Creating Users and Groups
The identity service plug-in only provides interfaces for the following:
■
User authentication
■
User properties lookup
■
Group membership
■
Workflow
■
Actions permitted
The identity service plug-in does not include creation of users and roles or granting of
roles to users. You must use tools specific to the user repository to accomplish this
task. For OID, the users and roles can be created using the Directory Administration
Service (DAS) tool.
Using the Plug-in with Installed Samples
Once the plug-in is deployed and configured, you can run the standard workflow
service samples over the new provider. This requires seeding the system and demo
users and roles (those used by the samples) into the data source of the custom plug-in.
See Also: Appendix F, "Demo User Community" for the complete
list of system and demo users and roles
Oracle BPEL Process Manager Workflow Services
16-99
Workflow-Related XPath Extension Functions
Workflow-Related XPath Extension Functions
XPath extension functions mimic XPath 2.0 standards. The following extension
functions are available.
ora:lookupUser(userId)
This extension function is used to look up a user. The function returns an XML element
of complex type as defined by the schema in LocalIdentityService.xsd at
http://hostname:port/orabpel/xmllib/workflow/
The following code example demonstrates how to use the extension function.
<process...
xmlns:idservice= http://xmlns.oracle.com/pcbpel/identityservice/local
...
<variables>
...
<variable name="user" element="idservice:user"/>
</variables>
<sequence>
...
<assign name="lookupUser">
<!-- get the user-->
<copy>
<from expression="ora:lookupUser(bpws:getVariableData('input', 'payload',
'/tns:input/tns:userId'))"/>
<to variable="user"/>
</copy>
</assign>
...
</sequence>
</process>
If userId is not a valid user, the function returns null.
ora:lookupGroup(groupId)
This extension function is used to look up a group. The function returns an XML
element of complex type as defined by the schema in LocalIdentityService.xsd
at
http://hostname:port/orabpel/xmllib/workflow/
The following code example demonstrates how to use the extension function.
<process …
xmlns:idservice= http://xmlns.oracle.com/pcbpel/identityservice/local
...
<variables>
...
<variable name="group" element="idservice:group"/>
</variables>
<sequence>
...
<assign name="lookupGroup">
<!-- get the group-->
<copy>
<from expression="ora:lookupGroup(bpws:getVariableData('input', 'payload',
'/tns:input/tns:groupId'))"/>
<to variable="group"/>
16-100
Oracle BPEL Process Manager Developer’s Guide
Workflow-Related XPath Extension Functions
</copy>
</assign>
...
</sequence>
</process>
If groupId is not a valid user, the function returns null.
ora:getUserProperty(userId, attributeName)
This function can be used to get any property of the user. The arguments to the
function are as follows:
■
■
userId—String or element containing the user whose attribute is to be retrieved
attributeName—String or element containing the name of the user attribute.
The attribute name is one of the following values:
–
givenName
–
middleName
–
sn
–
displayName
–
mail
–
telephoneNumber
–
homephone
–
mobile
–
facsimileTelephoneNumber
–
pager
–
preferredLanguage
–
preferredLanguage
–
manager
If the user with the given userId does not exist, the function returns null. If the user
does not have the given property, or the value for the property is empty, then the
function returns the string undefined.
ora:getGroupProperty(groupId, attributeName)
This function can be used to get any property of the group. The arguments to the
function are as follows:
■
■
groupId—String or element containing the group whose attribute is to be
retrieved
attributeName—String or element containing the name of the group attribute.
The attribute name should be one of the following values:
–
displayName
–
mail
If the group with the given groupId does not exist, the function returns null. If the
group does not have the given property, or the value for the property is empty, then
the function returns the string undefined.
Oracle BPEL Process Manager Workflow Services
16-101
Workflow-Related XPath Extension Functions
ora:getManager(userId)
This extension function is used to get the manager of a user identified by the userId.
This function returns a string identifying the manager of the user. If the user is not
valid, or if the user does not have a manager, then the function returns null.
ora:getReportees(userId)
This function gets the direct reportees of a user identified by the userId. The function
returns a list of nodes. Each node in the list is called user. The namespace URI of the
node is
http://oracle.tip.pc.services.identity/RemoteIdentityService.xsd
If the user does not exist, then the function returns null.
ora:getUsersInGroup(groupId)
This function gets the users in a group. The function returns a list of nodes. Each node
in the list is called user. The namespace URI of the node is
http://oracle.tip.pc.services.identity/RemoteIdentityService.xsd
If the group does not exist, then the function returns null.
ora:getUserRoles(userId, roleType, direct)
This function gets the user roles. The function returns a list of objects, either role
objects or group objects, depending on the roleType. The arguments to the function
are as follows:
■
■
■
userId—String or element containing the user whose roles are to be retrieved.
roleType—The role type, which has one of three values: ApplicationRole,
EnterpriseRole, or AnyRole.
direct—String or element indicating if direct or indirect roles are to be fetched.
This is optional and, if not specified, only direct roles are fetched. It is either
xsd:boolean or string true/false.
The function returns a list of nodes. Each node in the list is called group or role,
depending on the roleType. The namespace URI of the node is
http://oracle.tip.pc.services.identity/RemoteIdentityService.xsd
ora:isUserInRole(userId, roleName)
This function verifies if a user identified by the userId has a given role identified by
roleName. The function returns a Boolean true or false.
ora:getNumberOfTaskApprovals(taskId)
This extension function returns the number of times (an integer) that a task identified
by the given taskId is approved (approved in a generic sense, not the outcome
approve) by users. The function returns null if there is no task with the given
taskId.
ora:getPreviousTaskApprover(taskId)
This extension function returns the previous user who approved (approved in a
generic sense, not the outcome approve) a task identified by the given taskId. The
function returns a string userId that identifies the previous approver. The function
returns null if there is no task with the given taskId. The return of this function can
be used to get the title of the previous approver, for example, as follows:
16-102
Oracle BPEL Process Manager Developer’s Guide
Workflow-Related XPath Extension Functions
ora:getUserProperty(ora:getPreviousTaskApprover(tasked), ‘title’)
ora:getTaskAttachmentsCount(taskId)
This function returns the number of attachments (an integer) in a task that is identified
by the given taskId. The function returns null if there is no task with the given
taskId.
ora:getTaskAttachmentByIndex(taskId, attachmentIndex)
This function returns the attachment for the task identified by the given taskId at the
given attachmentIndex. The function returns an element of the type
{http://xmlns.oracle.com/pcbpel/taskservice/task}attachment. This
type is defined in WorkflowTask.xsd. Each attachment has either content or a URI.
The content, if any, in the element returned by the function is a Base64-encoded string.
The following BPEL code example demonstrates how to use the
getTaskAttachmentsCount and getTaskAttachmentByIndex functions. The
BPEL shown gets all the attachments in the task and writes to a file using the file
adapter.
<process .......
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:task="http://xmlns.oracle.com/pcbpel/taskservice/task">
...
<variables>
...
<variable name="SimpleWorkflowVar1" element="task:task"/>
<variable name="TaskAttachment" element="task:attachment"/>
</variables>
<sequence name="main">
...
<assign name="Assign_1">
<copy>
<from expression="number(0)"/>
<to variable="AttachmentIndex"/>
</copy>
</assign>
<while name="While_1"
condition="bpws:getVariableData
('AttachmentIndex') &lt; ora:getTaskAttachmentsCount
(bpws:getVariableData('SimpleWorkflowVar1','/task:task/task:taskId'))">
<sequence name="Sequence_1">
<assign name="Assign_2">
<copy>
<from expression="ora:getTaskAttachmentByIndex(bpws:getVariableData
('SimpleWorkflowVar1','/task:task/task:taskId'),(bpws:getVariableData
('AttachmentIndex') + number(1)))"/>
<to variable="TaskAttachment" query="/task:attachment"/>
</copy>
<copy>
<from expression="bpws:getVariableData('AttachmentIndex') +
number(1)"/>
<to variable="AttachmentIndex"/>
</copy>
<copy>
<from variable="TaskAttachment"
Oracle BPEL Process Manager Workflow Services
16-103
Workflow-Related XPath Extension Functions
query="/task:attachment/task:content"/>
<to variable="Invoke_1_Write_InputVariable" part="opaque"
query="/ns2:opaqueElement"/>
</copy>
</assign>
<invoke name="Invoke_1" partnerLink="File" portType="ns1:Write_ptt"
operation="Write" inputVariable="Invoke_1_Write_InputVariable"/>
</sequence>
</while>
...
</sequence>
</process>
ora:getTaskAttachmentByName(taskId, attachmentName)
This function returns the attachment for the task identified by the given taskId at the
given attachmentName. The function returns an element of the type
{http://xmlns.oracle.com/pcbpel/taskservice/task}attachment. This
type is defined in WorkflowTask.xsd. Each attachment has either content or a URI.
The content, if any, in the element returned by the function is a Base64-encoded string.
The following BPEL code example demonstrates how to use the
getTaskAttachmentByName function. The BPEL shown gets the attachment with
the name utplan.doc and writes to a file using the file adapter.
<process ........
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:task="http://xmlns.oracle.com/pcbpel/taskservice/task">
...
<variables>
...
<variable name="SimpleWorkflowVar1" element="task:task"/>
<variable name="TaskAttachment" element="task:attachment"/>
</variables>
<sequence name="main">
...
<assign name="Assign_3">
<copy>
<from expression="ora:getTaskAttachmentByName(bpws:getVariableData
('SimpleWorkflowVar1','/task:task/task:taskId'), string('utplan.doc'))"/>
<to variable="TaskAttachment" query="/task:attachment"/>
</copy>
<copy>
<from variable="TaskAttachment" query="/task:attachment/task:content"/>
<to variable="Invoke_2_Write_InputVariable" part="opaque"
query="/ns2:opaqueElement"/>
</copy>
</assign>
...
</sequence>
</process>
ora:getTaskAttachmentContents(taskId, attachmentName)
This function returns the attachment for the task identified by the given taskId at the
given attachmentName. The function returns a Base64-encoded string of either the
16-104
Oracle BPEL Process Manager Developer’s Guide
Approver Functions
attachment content or the URL (each attachment has either a content or a URI). The
difference between this function and the getTaskAttachmentByName function is
that the getTaskAttachmentByName function returns a complex element, whereas
this function returns the contents only. The following BPEL code example
demonstrates how to use the getTaskAttachmentContents functions. The BPEL
shown gets the attachment with the name utplan.doc and writes to a file using the
file adapter.
<process ........
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:task="http://xmlns.oracle.com/pcbpel/taskservice/task">
...
<variables>
...
<variable name="SimpleWorkflowVar1" element="task:task"/>
</variables>
<sequence name="main">
...
<assign name="Assign_4">
<copy>
<from expression="ora:getTaskAttachmentContents(bpws:getVariableData
('SimpleWorkflowVar1','/task:task/task:taskId'), string('utplan.doc'))"/>
<to variable="Invoke_2_Write_InputVariable" part="opaque"
query="/ns2:opaqueElement"/>
</copy>
</assign>
<invoke name="Invoke_3" partnerLink="File" portType="ns1:Write_ptt"
operation="Write" inputVariable="Invoke_2_Write_InputVariable"/>
...
</sequence>
</process>
orcl:get-localized-string(resourceURL,resourceLocation,resourceBundleName,la
nguage,country,variant,messageKey)
This extension function can be used to get localized messages for notifications for
internationalization.
orcl:format-string(string,string,string,string, …..)
The format-string extension function can be used to format strings during
construction of messages for notifications. This can be useful if the localized message
must be formatted with data from the payload.
Approver Functions
In a sequential workflow scenario, the users or groups to whom the task is routed are
captured using functions. The function is stored in the approver element of the task
object. These functions are evaluated at run time to determine the next approvers.
Approver Function Syntax
The approver functions are governed by the following grammar.
Oracle BPEL Process Manager Workflow Services
16-105
Approver Functions
approverFunction := (managementChainFunction | listFunction | adhocFunction
| usersFunction | groupsFunction)*
A comma-separated list of approver functions.
managementChainFunction := managementChain(level, title)
Represents a management chain. The management chain includes users within a
number of levels and up to a user whose title is specified. level is a required
argument and title is an optional argument.
listFunction := list(usersFunction*, groupsFunction*, acquiredByFunction)
Represents a single assignment to multiple users or groups. This function can be used
to assign the task to a mix of users and groups. Optionally, the function can also
specify the acquirer of the task when the task is assigned to a group or multiple users.
The acquiredBy in this function overwrites the acquiredBy in usersFunction
and groupsFunction.
adhocFunction := adhoc()
Allows the current approver to specify who the next approver is. When the user
completes the task without specifying the next approvers, the function is no longer
evaluated.
usersFunction := users(userId*, acquiredByFunction)
Represents a single task assignment to one or more users. Optionally the function can
also specify the acquirer of the task when the task is assigned to multiple users. Each
argument in this function must be a valid user id from the user store (OID, LDAP, and
so on).
groupsFunction := groups(groupId*, acquiredByFunction)
Represents a single task assignment to one or more groups. Optionally, the function
can also specify the acquirer of the task when the task is assigned to groups. Each
argument in this function must be a valid group id from the user store (OID, LDAP,
and so on).
acquiredByFunction := acquiredBy(userId)
Captures the acquirer when the task is assigned to a set of users or groups. The
argument in this function must be a valid user id from the user store (OID, LDAP, and
so on).
Where
■
# userId is a string argument representing the id of the user.
■
groupId is a string argument representing the id of the group.
■
level is a number argument that represents the levels in the management chain.
■
■
All arguments should be wrapped in quotes (" ").
■
The arguments are separated by commas.
■
16-106
title is a string argument that represents the title of the last user in the
management chain.
The management chain function is always evaluated with respect to the previous
approver of the task.
Oracle BPEL Process Manager Developer’s Guide
Approver Functions
Approver Function Examples
The following examples show how to use the approver functions.
■
managementChain("2", "Manager")
Routes the task to users in the management chain. The management chain
includes users within 2 levels and up to a user whose title is Manager.
■
list(users("jcooper", "jstein"), groups("LoanAgentGroup"),
acquiredBy("jcooper"))
Routes the task once to users jcooper and jstein and group LoanAgentGroup
and also sets acquiredBy to jcooper.
■
list(users("jcooper", "jstein")),
list(groups("LoanAgentGroup"))
Routes the task to users jcooper and jstein. When one of those users acquires
and acts on the task, routes the task to the group LoanAgentGroup.
■
adhoc()
The task supports adhoc routing and the next users or groups are specified by the
current approver of the task.
■
users("jcooper", "jstein")
Routes the task once to users jcooper and jstein.
■
users("jcooper", "jstein", acquiredBy("jcooper"))
Routes the task once to users jcooper and jstein. Also sets acquiredBy to
jcooper.
■
users("jcooper"), users("jstein")
Routes the task first to user jcooper, and after jcooper acts on the task, routes
the task to jstein.
■
groups("LoanAgentGroup", "Supervisor")
Routes the task once to the groups LoanAgentGroup and Supervisor.
■
groups("LoanAgentGroup"), groups("Supervisor")
Routes the task first to the group LoanAgentGroup and after a user from the
LoanAgentGroup acts on the task, routes the task to the group Supervisor.
■
groups("LoanAgentGroup", "Supervisor", acquiredBy("jcooper"))
Routes the task once to groups LoanAgentGroup and Supervisor. Sets
acquiredBy to jcooper.
■
managementChain("2", "Manager"), groups("LoanAgentGroup")
Routes the task to users in the management chain. The management chain
includes users within two levels and up to a user whose title is Manager. After the
users in the management chain are exhausted, routes the task to the group
LoanAgentGroup.
■
managementChain(“2”, “Manager”), groups(“LoanAgentGroup”),
adhoc()
Routes the task to users in the management chain. The management chain
includes users within two levels and up to a user whose title is Manager. After the
users in the management chain are exhausted, routes the task to the group
LoanAgentGroup. When a user in the LoanAgentGroup acquires the task and
Oracle BPEL Process Manager Workflow Services
16-107
Vacation Request Example
acts on it, the task can still be routed to other users as specified by the approver of
the task.
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 simple workflow using JDeveloper BPEL Designer
■
Using the Worklist Application to view and respond to tasks
Prerequisites
This example assumes the following:
■
■
You should be familiar with basic BPEL constructs, including BPEL activities and
partner links, and basic XPath functions. Familiarity with JDeveloper BPEL
Designer—the Oracle JDeveloper environment for creating and deploying BPEL
processes—is also assumed.
You must change the e-mail address for the user jstein. If the XML-based JAZN
provider is used, these properties can be changed in
Oracle_Home\integration\orabpel\system\services\config\users-properties.xml
The following XML segment from the users-properties.xml file shows
where the e-mail is configured:
<bpm:BPMUser userName="jstein" >
<bpm:properties>
<bpm:givenName>John</bpm:givenName>
<bpm:sn>Steinbeck</bpm:sn>
<bpm:title>Manager2</bpm:title>
<bpm:manager>wfaulk</bpm:manager>
<bpm:mail>user2@dlsun4254.us.oracle.com</bpm:mail>
<bpm:timeZone>GMT-8</bpm:timeZone>
<bpm:preferredLanguage>en-US</bpm:preferredLanguage>
<bpm:orclWorkflowNotificationPref>Mail</bpm:orclWorkflowNotificationPref>
</bpm:properties>
</bpm:BPMUser>
■
You must configure the e-mail server settings for the account Default, if it is
different from the default values. The Default account is used to send e-mails.
The e-mail server configuration is in
Oracle_Home\integration\orabpel\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>bpm1@dlsun4254.us.oracle.com</FromAddress>
</GeneralSettings>
<OutgoingServerSettings>
16-108
Oracle BPEL Process Manager Developer’s Guide
Vacation Request Example
<SMTPHost>dlsun4254.us.oracle.com</SMTPHost>
<SMTPPort>225</SMTPPort>
</OutgoingServerSettings>
<IncomingServerSettings>
<Server>dlsun4254.us.oracle.com</Server>
<Port>2110</Port>
<Protocol>pop3</Protocol>
<UserName>bpm1</UserName>
<Password ns0:encrypted="false"
xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">welcome
/Password>
<UseSSL>false</UseSSL>
<Folder>Inbox</Folder>
<PollingFrequency>1</PollingFrequency>
<PostReadOperation>
<MarkAsRead/>
</PostReadOperation>
</IncomingServerSettings>
</EmailAccount>
■
■
You must restart Oracle BPEL Process Manager after making any of the preceding
changes.
Verify that the task payload is displayed in the Worklist Application using the XSL
file vacationRequest.xsl. This file is needed to complete the tutorial and is
available in the VacationRequest sample business process.
Getting Started: Modeling the Vacation Request Process
1.
Create a business process called VacationRequest.
2.
When prompted for a template, select Asynchronous BPEL Process.
3.
After creating the new process, change the message structure of the vacation
request in the VacationRequest.wsdl to be more relevant to a vacation request
process. The message structure by default is
<element name="VacationRequestProcessRequest">
<complexType>
<sequence>
<element name="input" type="string"/>
</sequence>
Oracle BPEL Process Manager Workflow Services
16-109
Vacation Request Example
</complexType>
</element>
Replace the element called input with the four elements shown in bold in the
following:
<element name="VacationRequestProcessRequest">
<complexType>
<sequence>
<element name="creator" type="string" />
<element name="fromDate" type="date" />
<element name="toDate" type="date" />
<element name="reason" type="string" />
</sequence>
</complexType>
</element>
4.
Copy vacationRequest.xsl to the project location and add the file to the
project.
5.
Drop a User Task activity between the Receive activity and the callbackClient
activity.
6.
In the Workflow wizard, leave the default selected for Create New Workflow and
click Next.
7.
From Workflow Pattern, select Simple Workflow and click Next.
8.
Use the autocomplete feature to assign a value to the title. For example, use
Vacation Request for
<%bpws:getVariableData('inputVariable','payload','/
client:VacationRequestProcessRequest/client:creator')%>
9.
Use the autocomplete feature to assign the payload as
bpws:getVariableData('inputVariable','payload','/
client:VacationRequestProcessRequest')
10. Leave Auto generate JSP form as the payload display option.
With this option, a JSP is autogenerated based on the XML type of the payload
chosen in the previous step.
11. Leave the Task Creator field blank.
12. Set Expiration Duration Days to 1.
16-110
Oracle BPEL Process Manager Developer’s Guide
Vacation Request Example
13. Click Next.
14. By default, there are two outcomes: accept and reject. Delete ACCEPT and add
APPROVE. Click Next.
15. On the Notification page, select Assigned for Task Status, Assignees for
Recipient, and Email for Notification.
Oracle BPEL Process Manager Workflow Services
16-111
Vacation Request Example
You can also use the e-mail wizard to change default e-mail content.
16. Click New to start the wizard.
17. Click Next.
18. In the Assignees page, select Dynamic user assignment using XPath expression.
Use autocomplete to set the assignee to
ora:getManager(bpws:getVariableData('inputVariable','payload','/
client:VacationRequestProcessRequest/client:creator'))
16-112
Oracle BPEL Process Manager Developer’s Guide
Vacation Request Example
19. Click Next.
20. Click Finish.
You should see a Scope and a Switch activity. The Switch activity has three cases
associated with it. Each of the case statements represents the possible outcome
specified (approve and reject in this tutorial), plus an otherwise section to
represent any other conclusion of the task (errored, expired, and so on). Inside
each of the case activities, you can add activities to complete modeling the
business process. By default, there is an Assign activity named
copyPayloadFromTask in each of the branches. This Assign copies the payload
back to its source.
21. Add an Assign activity to the case for Task outcome is APPROVE.
22. In the Assign window (double-click Assign to invoke this window), click the
Copy Rules tab and click Create.
23. In the Create Copy Rule window, do the following:
a.
In the From section, click Expression and enter string('APPROVED').
b.
In the To section, for Variable, select outputVariable.
Oracle BPEL Process Manager Workflow Services
16-113
Vacation Request Example
c.
Click OK.
24. For both branches in the switch—the case for reject and the case for
otherwise—add an Assign activity with a copy rule, as you did for the approve
case, but set the expression to string('REJECTED') instead of
string('APPROVED').
16-114
Oracle BPEL Process Manager Developer’s Guide
Vacation Request Example
The business process modeling is completed. You can now deploy and test the BPEL
process, which looks as follows:
Running the Example
1.
Log in to Oracle BPEL Console, select the VacationRequest process, and go to the
Initiate tab.
2.
Enter appropriate values in each of the fields.
3.
■
Set the creator to jcooper.
■
The approval task is assigned to jstein, who is the manager of jcooper.
Click Post XML Message.
Oracle BPEL Process Manager Workflow Services
16-115
Summary
4.
Examine the flow of the generated instance. It is still waiting for a response from
the workflow service.
5.
Log in to the Worklist Application as user jstein and with the password
welcome, at
http://localhost:portnumber/integration/worklistapp/Login
You can also select Start, then All Programs, then Oracle - Oracle_Home, then
Oracle BPEL Process Manager 10.1.2, and then Sample Worklist Application.
6.
Perform any action on the task.
You can view the task details and payload information before performing any
action on the task. If the task is approved, then the business process is notified that
the task has been approved. The business process determines that no additional
approval is needed and marks the vacation request as approved. If the task is
rejected, then the business process is notified that the task has been rejected. The
business process in turn marks the vacation request as rejected. The business
process is now completed.
7.
Go to Oracle BPEL Console and confirm that the VacationRequest process has
completed.
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 patterns are described, as are the components of workflow
services—the task action handler, task management service, task routing service,
identity service, worklist service, and notification service.
16-116
Oracle BPEL Process Manager Developer’s Guide
17
Worklist Application
Chapter 16, "Oracle BPEL Process Manager Workflow Services" discussed how BPEL
workflow services enable you to interleave human interactions along with
connectivity to systems and services into an end-to-end process flow. The BPEL
worklist service provides a programmatic interface to view and manage tasks from the
BPEL process. The sample Oracle BPEL Worklist Application described in this chapter
is the Web interface that enables users to access and act on tasks assigned to them. The
tasks displayed depend on the user’s profile, and the actions allowed depend on the
user’s privileges. The Worklist Application is layered on top of the BPEL worklist
service.
This chapter contains the following topics:
■
Use Cases for the Worklist Application
■
Overview of Worklist Application Concepts
■
Accessing the Worklist Application in Local Languages
■
Customizing the Worklist Application
■
Building a Worklist Application Using the Worklist Service APIs
■
Building a Worklist Application Using the Worklist Service Remote APIs
■
Summary
See Also: Appendix F, "Demo User Community" for the
organizational hierarchy of the demonstration user community used
in examples throughout this chapter
Use Cases for the Worklist Application
Consider the scenario where a manager needs to approve a vacation request for an
employee, or a loan agent needs to review a loan application that has been submitted
as part of the BPEL process. These users typically log in to a Worklist Application to
view tasks assigned to them and perform actions on these tasks. Common actions
performed on tasks include updating the payload, attaching documents or comments,
routing the task to other users, and completing the task by providing a conclusion
such as approve or reject.
The Worklist Application is demonstrated in two samples: VacationRequest and
LoanDemoPlusWithWorkflow. In the VacationRequest use case, an employee files a
vacation request that is routed to his manager for approval. The manager sees the task
in the worklist in the My tasks view. In the LoanDemoPlusWithWorkflow use case, a
loan application is assigned to a LoanAgent role and then sent to two levels of
approval through the management chain if the loan amount is greater than $100,000.
Worklist Application 17-1
Overview of Worklist Application Concepts
When any of the loan agents log in to their worklists, they see the task in their My &
Group tasks view. One of the loan agents acquires the task and reviews it. If the loan
agent approves it, the task is routed further, to two levels of management approval, if
the loan amount is greater than $100,000. 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).
See: Oracle_Home\integration\orabpel\samples\demos
for the VacationRequest and LoanDemoPlusWithWorkflow
directories
Two simple applications built using the Worklist Service APIs are also provided that
demonstrate using the most common features such as listing, update, approve, login,
logout, acquire, and others:
See:
■
■
The 132.UserTasks directory in Oracle_
Home\integration\orabpel\samples\tutorials — a
README.txt file describes the process and how to access the
application.
The StarLoanWithWFUI directory in Oracle_
Home\integration\orabpel\samples\utils\AsyncLoanServ
ice — the Oracle_
Home\integration\orabpel\samples\demos\LoanDemoPlusW
ithWorkflow\README.html file (LoanDemoPlusWithWorkflow
uses the StarLoanWithWorkflow process) describes how to access the
application.
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
The Worklist Application enables users to participate in a BPEL process by performing
tasks that require manual intervention. The worklist user interface displays tasks
specific to the logged-in user based on the user’s permissions and assigned groups and
roles. In general, when a user logs in, the following types of tasks that require action
are displayed:
■
■
Tasks assigned to the user—In this case, the user has to act on the task before it is
routed further.
Tasks assigned to the groups or roles that the user belongs to—In this case, one
of the users belonging to the group has to acquire the task before acting on it. If
one user in a group acquires the task, it is not available to other users until it is
released back to the group.
Users can review tasks for their reportees, tasks that were created by them, tasks
owned by them, or any previous task that the user participated in.
A work item or task that is assigned to a user has the following components:
■
17-2
Task attributes—includes task title, number, status, priority, expiration,
identification key, assignees, and other flex fields.
Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
■
■
■
■
Task form—consists of detailed information (the payload) about the task; for
example, a loan application in the LoanDemoPlusWithWorkflow sample or
support ticket details in the HelpDeskRequest 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 as well as 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. Additionally, a user can modify flex fields, task
priority, or include comments or 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.
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. The various system actions allowed on a
task are as follows:
–
Escalate—This operation enables a user to escalate a task to his manager for
further action.
–
Reassign—A manager can delegate a task to reportees. Similarly, the process
owner or a user with BPMWorkflowReassign privileges can delegate a
specific task to any other person in the organization.
–
Request More Information—Any participant in the workflow can request
more information from the task creator or any of the prior assignees of the
task. The user requesting more information can either have the additional
information sent to him, or the user can require that the task be resubmitted
through the intermediate approvers.
–
Submit More Information—This operation enables a user to respond to a
request for additional information. This action is performed after the user has
made the necessary updates to the task or has added comments or
attachments containing additional information.
–
Route—This operation enables a user to enter an outcome and then route the
task in an ad hoc fashion to the next user who must review the task.
–
Suspend—This operation enables process 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).
Worklist Application 17-3
Overview of Worklist Application Concepts
–
Resume—This operation enables process 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.
–
Acquire—This operation enables a user to obtain an exclusive right to work
on a task that is assigned to a group or multiple users. No action can be
performed on a task assigned to a group or multiple users until it is acquired.
Only one user can acquire a task at any given time.
–
Release—This operation enables a user to abandon the exclusive right to work
on a task that is assigned to a group or multiple users. After a task is released,
any other user who is assigned to the task can acquire it.
–
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 modeler has restricted task renewal on the workflow.
–
Withdraw—The creator of the task can withdraw a pending task. A process
owner can also withdraw a task on behalf of the creator.
Logging In to the Worklist Application
Follow these instructions to access the Worklist Application.
1.
Open a Web browser.
For a list of supported browsers, see Oracle Application Server Integration Installation
Guide.
2.
Go to the following URL:
http://hostname:9700/integration/worklistapp/Login
where
■
hostname is the name of the host on which Oracle BPEL Process Manager is
installed
You can also select Start, then All Programs, then Oracle - Oracle_Home, then
Oracle BPEL Process Manager 10.1.2, and then Sample Worklist Application.
3.
Type the username and password, and click Login.
The username and password must exist in the user community provided to JAZN.
See "Configuring Identity Service" on page 16-81 for information on JAZN.
Note: With some browsers, when you log in to the sample Worklist
Application, the username and password fields remain blank without
producing an error message. Refresh the browser so that the login
information is successfully processed.
Features of the Sample Worklist Application
After you log in (see "Logging In to the Worklist Application" on page 17-4), the home
page of the Worklist Application is displayed, as shown in Figure 17–1.
17-4
Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–1
Worklist Application Home
From this page, you can retrieve worklist tasks by using the Search field to do a
keyword search or by using the Task Filter, Priority, and Status fields to specify
search criteria. Table 17–1 describes the salient features of the Worklist Application
home page shown in Figure 17–1.
Worklist Application 17-5
Overview of Worklist Application Concepts
Table 17–1
Contents of the Worklist Application Home
Page Element
Location in
Page
Description
User link
top right of
Figure 17–1
Click the user name link to see the logged-in user’s full name, contact
information, title, manager’s name, reportees’ names, and assigned groups
and roles. The manager and reportee names are also links to the same
information on those individuals.
Search Keyword
field
top center of
Figure 17–1
Enter a keyword to search task titles, comments, identification keys, and
the flex string fields of tasks that qualify for the specified filter criterion.
Task Filter list
top right of
Figure 17–1
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
Reportees—tasks assigned to the users who report to the logged-in
user
Owner—tasks that are owned by the logged-in user by way of process
ownership
■
Creator—tasks that were created or initiated by the logged-in user
■
Previous—tasks that the logged-in user has updated
■
■
Admin—appears only if the logged-in user has been granted the
BPMWorkflowAdmin role
All—tasks from all of the above
Priority list
top right of
Figure 17–1
Select from Any or 1 through 5, where 1 is the highest priority.
Status list
top right of
Figure 17–1
Select from the following:
■
Any
■
Assigned
■
Completed
■
Suspended (can be resumed later)
■
Withdrawn
■
Expired
■
■
Go button
top right of
Figure 17–1
Errored (errored while processing; a user with the
BPMWorkflowAdmin role can troubleshoot the problem.)
Information Requested
Click Go after selecting from the search fields.
Click to go to the Advanced Search page, which provides additional search
filters.
Advanced Search
link
Show (Hide)
Chart button
right side of
Figure 17–1
Shows a bar chart of the listed tasks in the selected task filter, broken down
by status. See Figure 17–2 for an example.
Number column
right side of
Figure 17–1
Displays the task number for the task.
Title column
middle of
Figure 17–1
Tasks associated with a purged or archived process instance do not appear.
Click the column name for ascending or descending sorts.
Priority column
middle of
Figure 17–1
Click the column name for ascending or descending sorts.
17-6
Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Table 17–1
(Cont.) Contents of the Worklist Application Home
Page Element
Status column
Location in
Page
middle of
Figure 17–1
Assignees column middle of
Figure 17–1
Description
Status states are as follows: Assigned, Completed, Errored, Expired, Info
Requested, Stale, Suspended, and Withdrawn. Click the column name for
ascending or descending sorts.
Person or group to whom the task is assigned.
Expiration Date
column
middle of
Figure 17–1
Date and time the tasks expires. Click the column name for ascending or
descending sorts.
Modified Date
column
middle of
Figure 17–1
Date and time the task was modified. Click the column name for ascending
or descending sorts.
Actions column
middle of
Figure 17–1
The possible actions that apply to the task. See"Task Actions" on page 17-10
for more information.
Next or Previous
links
bottom left of
Figure 17–1
Click Previous or Next to go the previous or next page in the list. The
absolute row numbers of the tasks are shown in square brackets. The size
of the page (number of rows per page) is controlled by an optional
parameter, oracle.tip.worklist.sampes.tasklist.maxrows, in
the file pc.properties, which appears in Oracle_
Home\integration\orabpel\system\services\config. The
default value is 20.
If you click Show Chart, a bar chart of the tasks is displayed, as shown in Figure 17–2.
Worklist Application 17-7
Overview of Worklist Application Concepts
Figure 17–2
Worklist Application Home with Chart Displayed
If you click a task in the Title column, the Task Details page is displayed, as shown in
Figure 17–3.
17-8
Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–3
Task Details Page
Table 17–2 describes the Task Details page shown in Figure 17–3, and also references
other figures in this chapter. (The table does not include page elements, such as the
User link or the search fields, already described in Table 17–1.)
Table 17–2
Contents of the Task Details Page
Page Element
Location in Page Description
Task Action list top left of
Figure 17–3
Shows the actions you can perform on a task, such as approving a vacation
request or escalating a purchasing decision, depending on how the process
flow was defined in JDeveloper BPEL Designer. See "Task Actions" on
page 17-10 for more information.
Route... button
top right of
Figure 17–4
Routes the task to another user. The button appears only if the task was
designed to support dynamic routing (that is, no predetermined set of
approvers, for example). See "Routing" on page 17-12 for more information.
Request More
Info... button
top right of
Figure 17–3
Requests more information from the task creator or a previous approver in a
simple or sequential approval process. See "Requesting More Information"
on page 17-13 for more information.
View SubTasks top right of
button
Figure 17–16
View History
button
top right of
Figure 17–16
Click to go to the Subtasks page. This button is available only for a parent
task of a parallel flow. See "Parallel Tasks" on page 17-23 for more
information.
Click to see the complete trail of changes made to a task. See "Task History
and Sequence (Version) Numbers" on page 17-14 for more information.
Worklist Application 17-9
Overview of Worklist Application Concepts
Table 17–2
(Cont.) Contents of the Task Details Page
Page Element
Location in Page Description
Header section
top of Figure 17–3 The header includes the process name, state, and priority, and information
about who created, modified, acquired, or is assigned to the task. It also
displays dates related to task creation, last modification, and expiration. The
task flow pattern is also displayed.
Payload section middle of
Figure 17–3
Click HTML Form View (default) or XML Source View for the display
options. See "The Payload" on page 17-17 for more information.
Comments and bottom of
Attachments
Figure 17–3
section
Click the Add button in the Comments section to add comments. Click the
Change... button in the Attachments area to add or change an attachment.
See "Comments" on page 17-19 and "Attachments" on page 17-20 for more
information.
Reassign
button
lower left of
Figure 17–15
Click this button if you want to change the assignment of a task to other
users. You must have permission to reassign a task, which is granted
through the BPMWorkflowReassign role. See "Reassignment" on
page 17-22 for more information.
Update Fields
button
middle right of
Figure 17–16
Click to go to the edit page for updating task header fields such as priority,
identification key, and flex fields.
The following sections describe activities provided by the Worklist Application.
Task Actions
Figure 17–4 shows the Task Action list. The tasks 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, such as Accept or
Reject, are listed first. Custom actions are defined in JDeveloper BPEL Designer when
you define the business process. System actions, such as Escalate or Suspend, are
listed below a separator line.
17-10 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–4
Task Actions
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.
System actions are described in Table 17–3.
Table 17–3
System Task Actions
Action
Description
Acquire
If a task is assigned to a group or multiple users, then the task must be acquired first.
Acquire is the only action available in the Task Action list. After a task is acquired, 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.
Release
If a task is assigned to a group or multiple users, it can be released if the user who
acquired the task cannot complete the task. Any of the other assignees can acquire
and complete the task.
Worklist Application
17-11
Overview of Worklist Application Concepts
Table 17–3
(Cont.) System Task Actions
Action
Description
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 Oracle_
Home\integration\orabpel\system\services\config. The default value is
P7D (seven days).
Submit More Info
Use this action if another user requests that you supply more information. 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.
Routing
If there is no predetermined sequence of approvers and the actual set of approvers is
determined dynamically, then the task can be routed in an ad hoc fashion. Note that
the process must have been designed for supporting ad hoc routing. For such tasks, a
Route button appears on the Task Details page, as shown in Figure 17–5.
17-12 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–5
Routing a Task
Clicking Route displays the ad hoc Routing page. Like the Reassign page, the user can
look up the next approver by selecting My & Group and providing a complete or
wildcard search string name. The difference between reassign and route is that in the
case of route, the user’s conclusion is added to the task and the task is sent to the new
user as the next approver in the ad hoc sequence. Note that the new user or users are
selected for the next phase of approval only. A chain or sequence of approvals is not
denoted. The user must select a conclusion and can optionally add comments before
routing the task.
Requesting More Information
Figure 17–6 shows where you request more information. 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, as described in
Table 17–3.
Worklist Application
17-13
Overview of Worklist Application Concepts
Figure 17–6
Requesting More Information
Task History and Sequence (Version) Numbers
Figure 17–7 and Figure 17–8 show task history and sequence numbers (versions). Each
time a task is updated or an action is performed, and sequencing (versioning) has been
requested, a new sequence number is created. Task sequence numbers are
automatically created for important actions and changes, such as adding and deleting
attachments and payloads.
17-14 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–7
Task HIstory
Worklist Application
17-15
Overview of Worklist Application Concepts
Figure 17–8
Task Sequence (Version) Numbers
If a task requires sequential approval, the list of approvers is displayed.
You can also view the flow of the corresponding business process by clicking the
Business Process History link at the bottom of the page. Oracle BPEL Console
containing the process flow is displayed, as shown in Figure 17–9.
17-16 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–9
Process Flow
The Payload
Figure 17–10 shows a payload in the HTML form view using a customized XSL
template to render the original XML payload in an HTML format. The HTML form
view can also be displayed using a custom payload JSP page. See Chapter 16, "Oracle
BPEL Process Manager Workflow Services" for information on using an XSL template
or using the autogenerated JSP.
Worklist Application
17-17
Overview of Worklist Application Concepts
Figure 17–10
Task Payload (XSL Transformed Payload)
By default the payload display form is automatically generated. As shown in
Figure 17–10, it consists of a form containing inputs for each of the elements of the
payload and the values corresponding to the original values of the elements when the
task was initiated. Using the Update Fields... button changes the values.
Figure 17–11 shows a payload in the XML source view. Users can edit the payload in
this window, or, for complex payloads, they can copy the XML data into an external
XML editor and paste the edited XML back into the XML payload window.
17-18 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–11
Task Payload—XML Source View
Comments
Figure 17–12 shows where users add comments. To add a comment, users must have
permission to update the task.
Worklist Application
17-19
Overview of Worklist Application Concepts
Figure 17–12
Adding a Comment
A newly added comment and the comment writer’s username are appended to the
existing comments, as shown in Figure 17–3 on page 17-9. A trail of comments is
maintained throughout the life cycle of the task.
Attachments
Figure 17–13 shows where users add attachments. Users can add a file by using an
absolute path name, as shown in the figure, or by using the Browse button. Users can
associate a URL with a task by providing a name and a well-formed address (for
example, http://www.oracle.com).
17-20 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–13
Adding Attachments
Users can select one or more of the attachments and delete them, as shown in
Figure 17–14.
Worklist Application
17-21
Overview of Worklist Application Concepts
Figure 17–14
Deleting an Attachment
Reassignment
Figure 17–15 shows where users reassign a task.
17-22 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–15
Reassigning a Task
The page lists the current assignees and new assignees. Users can use Lookup to find
additional names from the JAZN user community. Names that match the search string
(wildcard search is supported) are added to the list of new assignees. Deselecting an
assignee name drops the user from the list. After a task has been reassigned, it is
available in the worklists of the new assignees.
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, as shown in Figure 17–16. Clicking this button displays the SubTasks page,
which 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.
Worklist Application
17-23
Overview of Worklist Application Concepts
Figure 17–16
The View SubTasks Button
Flex Fields and Task Fields Updates
A task can be associated with a set of flex fields of different types. Each flex field can
have a custom name. The flex fields are displayed in the Task Details page, as shown
in Figure 17–17.
17-24 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–17
Viewing Flex Fields
Clicking Update Fields… displays the Header Fields page. This page allows the user
to update the flex fields and other task header fields, such as priority and
identification key, as shown in Figure 17–18.
See Chapter 16, "Oracle BPEL Process Manager Workflow Services" for information on
how flex fields are defined in the advanced option of the Workflow wizard.
Worklist Application
17-25
Overview of Worklist Application Concepts
Figure 17–18
Updating Flex Fields
Request Status
For every update request (custom or system action) the user submits, the status of the
request is displayed in the left portion of the header. If a request is successful, then the
user sees a confirming message, as shown in Figure 17–19.
17-26 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–19
A Successful Update Request
If a request is not successful, then the user sees a failure message, as shown in
Figure 17–20. Clicking the error message displays the Error Information page. See
"Error Information" on page 17-28 for more information.
Worklist Application
17-27
Overview of Worklist Application Concepts
Figure 17–20
An Unsuccessful Update Request
Error Information
If an error is encountered while processing a request, an error message is displayed, as
shown in Figure 17–21.
17-28 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–21
Error Message Display
The main message of the error is displayed by default. Click Show/Hide Details for
details (mostly useful for application developers or administrators). Clicking Back
displays the previous page where the request was made.
The user error shown in Figure 17–21 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 acquired 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.
The Error Message page also displays system errors, which should be reported to the
administrator.
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 of the Oracle
BPEL Worklist Application.
Worklist Application
17-29
Overview of Worklist Application Concepts
User and Group Information
If a user clicks the link in the header that identifies the logged-in user, the User Info
page appears. This page displays 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 17–22.
Figure 17–22
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, as shown in Figure 17–23. The Group Info page
displays the list of direct and indirect users (users contained in child groups of the
current group).
17-30 Oracle BPEL Process Manager Developer’s Guide
Overview of Worklist Application Concepts
Figure 17–23
Group Information
Advanced Search
The Advanced Search page, shown in Figure 17–24, provides additional filters for
performing a fine-grained search, based on business process, expiration date, and
creation date. The standard search box that appears in the top-right corner is not
displayed in the advanced search option.
Worklist Application
17-31
Overview of Worklist Application Concepts
Figure 17–24
Advanced Search Page
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 acquire, suspend, or
reassign, the worklist service ensures that the requested action is contained in the list
determined by the preceding algorithm.
17-32 Oracle BPEL Process Manager Developer’s Guide
Accessing the Worklist Application in Local Languages
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 has to be acquired first before any actions can be
performed on it.
See "Identity Service" on page 16-77 for information about the identity service and how
privileges can be assigned to users.
How Changes to a Workflow Appear in the Worklist Application
When a BPEL process is aborted, associated tasks are marked as Stale in the Status
column of the Worklist Application home page. When a BPEL process instance is
deleted, all associated tasks are deleted. When a BPEL process is undeployed,
associated tasks are marked as Stale in the Status column of the Worklist Application
home page.
Accessing the Worklist Application in Local Languages
The identity service determines a user’s preferred locale (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 locale and itemizing for the user is set to the system
default.
For example, if you are using the sample worklist configured with the user community
in the JAZN XML file, then you can set the user's preferred language in
users-properties.xml (in Oracle_
Home\integration\orabpel\system\services\config) as follows:
<bpm:timeZone>America/Los_Angeles</bpm:timeZone>
<bpm:preferredLanguage>en_US</bpm:preferredLanguage>
If an LDAP-based provider such as OID is used, then language settings 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. For custom actions, flex
fields, and task titles, the display names come from the message bundle, if specified in
the configuration. If no message bundle is specified, then the values specified in the
wizard at design time are used. See Chapter 16, "Oracle BPEL Process Manager
Workflow Services" for more information on how to specify message bundles so that
custom actions, flex fields, and task titles are displayed in a preferred local language.
The Worklist Application supports the locales shown in Table 17–4.
Table 17–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)
Worklist Application
17-33
Customizing the Worklist Application
Table 17–4
(Cont.) Languages and Java Locales Supported by the Worklist Application
Language
Java Locale
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)
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.
See Also: The WorklistServlets directory in Oracle_
Home\integration\orabpel\samples\hw\worklistxpress\src
Worklist Application Architecture
The Worklist Application follows the standard model-view-controller approach, as
shown in Figure 17–25. A request coming from the browser is handled by a servlet.
The servlet validates the request and calls the appropriate worklist service API to
either fetch the required data from the back end or to update a task. After the API call,
the servlet stores the data required for rendering the next page in the session. The JSP
page picks up the data from the session, renders the data, and removes it from the
session. Hence the servlets and the JSP pages have different functions. The servlets are
responsible for making the back-end API calls and the JSP pages are responsible for
formatting the data.
Figure 17–25
Browser
Worklist Application Architecture
Servlet
(src/WorklistServlets/*.java)
Worklist
Service
JSP
(public_html/*.jsp)
A typical page flow sequence is shown in Figure 17–26. 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 performs a page redirect to the login JSP page that is
sent to the browser. The user enters the username and password and the login servlet
calls the authenticateUser() API. If successful, it sends a redirect to the TaskList
URL. The browser's request then goes to the TaskList servlet that calls the
getWorklistTasks() API for getting the tasks that the user should see. Then it
17-34 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
performs a page redirect to the TaskList JSP page that is sent to the browser. When a
user clicks a task link, the request is handled by the TaskDetails servlet. This calls the
getWorklistTaskDetails() API and performs a page redirect to the TaskDetails
JSP page that is sent to the browser. Page flows for other functionality, such as
updating payload, changing priority, adding an attachment, reassigning a task,
viewing history, and requesting more information, are similar.
Figure 17–26
A Typical Page Flow Sequence
Browser
Servlet
(Login.java)
JSP
(Login.jsp)
User enters
username /
password
Browser
Servlet
(Login.java)
Browser
Servlet
(TaskList.java)
User clicks
on a task
link
Browser
authenticateUser()
Worklist
Service
getWorklistTasks()
Worklist
Service
JSP
(TaskList.jsp)
Servlet
(TaskDetails.java)
getWorklistTaskDetails()
Worklist
Service
JSP
(TaskDetails.jsp)
The separation of responsibility 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 may be sufficient to modify the JSP
pages (and the Java class HTMLFormatter.java used for formatting HTML data).
The following sections discuss how to customize some of the commonly used pages
for a different look and feel to suit various application requirements.
Login Page
A common requirement for customizing the login page is to add corporate branding,
as shown in Figure 17–27. Replace the image tag <img src="img/login.jpg"> in
the Login.jsp page with your image tag, such as <img
src="img/acmeLogin.jpg">. Everything else remains the same.
Worklist Application
17-35
Customizing the Worklist Application
Figure 17–27
Login Page
Header Info
The header section appears on every page above the bread crumb navigation. This
section can be customized by modifying the Header.jsp file, as shown in
Figure 17–28. 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.
17-36 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
Figure 17–28
Header Information
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.
Task Home (Listing) Page
The home (or listing) page lists all the tasks that match the search criteria specified by
the user. It also contains a chart that summarizes the task counts for the category (task)
filter. As shown in Figure 17–28, both the listing and the chart content can be
customized to suit application requirements. You can customize the list by modifying
the displayFilteredTasks() method in the
src/WorklistServlets/HTMLFormatter.java class. Some of the formatting
code is included in this class for modularity and reuse. You can customize the list to
display only those columns that are relevant to the application. The contents of the
columns can be customized as well. You can customize the list of task actions by
modifying the displayTaskActionsDropdown() method in the same class. You
can customize the chart, for example, to show only counts for statuses that are relevant
to the application by modifying the ListChart.jsp file. Customize the overall
layout by modifying the TaskList.jsp file.
Task Details Page
The Task Details page is typically 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. All of these can be customized
by modifying the TaskDetails.jsp file.
Worklist Application
17-37
Customizing the Worklist Application
In the example shown in Figure 17–29, the header section can be customized to display
only the task fields that are relevant to the application. The payload section contains
the autogenerated JSP file based on the payload XSD. See Chapter 16, "Oracle BPEL
Process Manager Workflow Services" for information on how to customize this file.
The footer section can be customized, moved to the top section, or eliminated,
depending on the application requirements.
Figure 17–29
Task Details Page
Additional Pages
The guidelines provided in "Worklist Application Architecture" on page 17-34 can be
used to modify other pages to suit the application requirements.
Configuration Parameters
In addition to customizing pages, you can modify parameters in Oracle_
home\integration\orabpel\system\services\config\pc.properties to
change the behavior of the application as follows:
■
To change the page size on the listing page, change:
oracle.tip.worklist.samples.tasklist.maxrows=5
■
To change the renewal duration for tasks, change:
oracle.tip.worklist.samples.taskaction.renew.duration=P7D
17-38 Oracle BPEL Process Manager Developer’s Guide
Customizing the Worklist Application
Controlling Access to Information and Actions for Different Users
The worklist 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) have 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:
■
ACQUIRE
■
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.
The Worklist Application can be customized so that the information viewed and the
actions performed on a given page can be 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 page, the identity service can be used to check if the user has the granted role
and determine which code path to take.
For example, you can create a new role called BPMProcessingManager in the file
jazn-data.xml (in Oracle_Home
\integration\orabpel\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>
...
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"
Worklist Application
17-39
Building a Worklist Application Using the Worklist Service APIs
import="oracle.tip.pc.services.identity.*"
boolean canEditTaskHeaderPriority = false;
// get info from identity service
try
{
BPMIdentityService mIdentityService =
ServiceFactory.getIdentityServiceInstance();
// lookup user based on worklist context user
BPMUser bpmUser = mIdentityService.lookupUser(ctx.getUser());
// 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 a Worklist Application Using the Worklist Service APIs
The Worklist Application that is included with Oracle BPEL Process Manager provides
a good starting point for building applications from scratch or for building composite
applications.
The typical sequence of calls to the worklist service is as follows:
1.
Get the handle to the worklist service.
2.
Authenticate the user with the username and password and get a handle to the
worklist context.
3.
Set the required filters for retrieving tasks and get the list of tasks that qualify.
4.
Loop through the task list and display tasks.
5.
Perform actions on specific tasks.
A code example for calling the regular (local) worklist service APIs for performing this
sequence of actions is as follows:
// required imports
import oracle.tip.pc.api.worklist.*;
import oracle.tip.pc.services.hw.worklist.WorklistService;
// 1. get a handle to the worklist service
WorklistService wlSvc = WorklistService.getWorklistService();
// 2. get worklist context for current user after authentication
String user = "jstein";
String password = “welcome”;
IWorklistContext ctx = wlSvc.authenticateUser(user, password);
// 3. set filters for retrieving “My” tasks with “Assigned” status
// sorted by task title is ascending order
Map filterMap = new HashMap();
filterMap.put(IWorklistService.FILTER_TYPE_TASK_FILTER,
17-40 Oracle BPEL Process Manager Developer’s Guide
Building a Worklist Application Using the Worklist Service APIs
IWorklistService.TASK_FILTER_MY);
filterMap.put(IWorklistService.FILTER_TYPE_STATUS_FILTER,
IWorklistService.STATUS_FILTER_ASSIGNED);
String keywords = “”;
List tasks = wlSvc.getWorklistTasks(ctx,
keywords,
filterMap,
IWorklistService.SORT_FIELD_TASK_TITLE,
IWorklistService.SORT_ORDER_ASCENDING);
// 4. APPROVE all Vacation Request tasks that are assigned to user
if (tasks != null)
{
for (int i=0; i<tasks.size(); i++)
{
Task task = (Task) tasks.get(i);
String taskId = task.getTaskId();
// check if the task is a vacation request
if (task.getTitle().startsWith("Vacation request"))
{
wlSvc.appendTaskComments(ctx, taskId, "foo");
// now approve the task
String action = "APPROVE";
wlSvc.customTaskOperation(ctx, taskId, action);
}
}
}
See Also: Oracle_
Home\integration\orabpel\docs\workflow\index.html for
Javadoc that describes the worklist service APIs
Worklist Service APIs
The following worklist service APIs are needed for various actions.
/*
* Perform user authentication
*/
public IWorklistContext authenticateUser(String user,
String password)
throws PCException;
/*
* Get information for the specified group
*/
public IWorklistGroup getGroupInfo(IWorklistContext ctx,
String group)
throws PCException;
/*
* Get information for the specified user
*/
public IWorklistUser getUserInfo(IWorklistContext ctx,
String user)
throws PCException;
Worklist Application
17-41
Building a Worklist Application Using the Worklist Service APIs
/*
* getWorklistTasks retrieves qualifying tasks from the start
* row to the last row for the given filter/sort criterion
* and user using the paging
*
*/
public List getWorklistTasks(IWorklistContext ctx,
String keywords,
Map filterMap,
String sortField,
String sortOrder,
int startRow,
int lastRow)
throws PCException;
/*
* getWorklistTaskDetails retrieves the details for the
* specified task
*/
public IWorklistTask getWorklistTaskDetails(IWorklistContext ctx,
String taskId)
throws PCException;
/*
* getWorklistTaskVersionDetails retrieves the details for the
* specified version of the task
*/
public IWorklistTask getWorklistTaskVersionDetails(
IWorklistContext ctx,
String taskId,
int version)
throws PCException;
/*
* getWorklistTaskHistory retrieves the history for the
* specified task
*/
public List getWorklistTaskHistory(IWorklistContext ctx,
String taskId)
throws PCException;
/*
* Return a list of deployed business process names
*/
public List getWorklistTaskBusinessProcesses(IWorklistContext ctx)
throws PCException;
/*
* acquireTask lets the user acquire the task
*/
public IWorklistTask acquireTask(IWorklistContext ctx, String taskId)
throws PCException;
/*
* releaseTask lets the user release the task
*/
public IWorklistTask releaseTask(IWorklistContext ctx, String taskId)
throws PCException;
17-42 Oracle BPEL Process Manager Developer’s Guide
Building a Worklist Application Using the Worklist Service APIs
/*
* escalateTask lets the user escalate the task
*/
public IWorklistTask escalateTask(IWorklistContext ctx,
String taskId)
throws PCException;
/*
* renewTask lets the user renew the task
*/
public IWorklistTask renewTask(IWorklistContext ctx,
String taskId,
String durationDays)
throws PCException;
/*
* withdrawTask lets the user withdraw the task
*/
public IWorklistTask withdrawTask(IWorklistContext ctx,
String taskId)
throws PCException;
/*
* suspendTask lets the user suspend the task
*/
public IWorklistTask suspendTask(IWorklistContext ctx, String taskId)
throws PCException;
/*
* resumeTask lets the user resume the task
*/
public IWorklistTask resumeTask(IWorklistContext ctx, String taskId)
throws PCException;
/*
* requestInfoForTask lets the user request additional info for the task
*/
public IWorklistTask requestInfoForTask(IWorklistContext ctx,
String taskId,
String user,
boolean reapprovalNeeded,
String comments)
throws PCException;
/*
* submitInfoForTask lets the user submit additional info for the task
*/
public IWorklistTask submitInfoForTask(IWorklistContext ctx,
String taskId)
throws PCException;
/*
* delegateTask lets the user delegate (reassign) the task
*/
public IWorklistTask delegateTask(IWorklistContext ctx,
String taskId,
List worklistAssignees)
throws PCException;
Worklist Application
17-43
Building a Worklist Application Using the Worklist Service APIs
/*
* customTaskOperation lets the user perform custom operation on the task
*/
public IWorklistTask customTaskOperation(IWorklistContext ctx,
String taskId,
String operation,
String comments)
throws PCException;
/*
* completeAndRouteTask lets the user route the task to another user
after adding a conclusion
*/
public IWorklistTask completeAndRouteTask(IWorklistContext ctx,
String taskId,
String conclusion,
String comments,
List worklistAssignees)
throws PCException;
/*
* updateTask lets the user update the task
*/
public void updateTask(IWorklistContext ctx, IWorklistTask task)
throws PCException;
/*
* appendTaskComments lets the user appends comments to the task
*/
public IWorklistTask appendTaskComments(IWorklistContext ctx,
String taskId,
String comments)
throws PCException;
/*
* addTaskAttachment lets the user add an attachment to the task
*/
public void addTaskAttachment(IWorklistContext ctx,
String taskId,
String name,
String value,
String type,
InputStream dataStream)
throws PCException;
/*
* removeTaskAttachment lets the user delete attachments from the task
*/
public void removeTaskAttachment(IWorklistContext ctx,
String taskId,
String[] names)
throws PCException;
/*
* lookupAssignees gets a list of assignee of the specified assignee type
* (users/groups/reportees) who match the userLookupList
*/
public List lookupAssignees(IWorklistContext ctx,
String assigneeType,
String userLookupList)
17-44 Oracle BPEL Process Manager Developer’s Guide
Building a Worklist Application Using the Worklist Service Remote APIs
throws PCException;
}
Example: Reassigning a Task in a Worklist Application
"Worklist Service APIs" on page 17-41 lists the API
worklistService.lookupAssignees(), which you use to look up a user. In the
following example, the lookup call searches for users that match the string j* and
then those users are assigned to the task.
List worklistAssignees = worklistService.lookupAssignees(ctx,
IWorklistService.ASSIGNEE_TYPE_USER, "j*");
worklistService.delegateTask(ctx, taskId, worklistAssignees);
In this example, the lookupAssignees call returns jcooper, jaustin, and jstein
(users in the demo user community that match j*). If you want to assign the task to
jcooper, then use jcooper as the lookup string. Alternatively, you can loop through
the worklistAssignees list that is returned and filter out entries that you do not
want. The element of the list contains ITaskAssignee objects.
See Also:
■
■
■
The worklistxpress sample in Oracle_
Home\integration\orabpel\samples\hw
The worklist API available in Oracle_
Home\integration\orabpel\docs\workflow\index.html
"Use Cases for the Worklist Application" on page 17-1 for details
about two simple applications built using the Worklist Service
APIs that demonstrate using the most common features such as
listing, update, approve, login, logout, acquire, and others
Building a Worklist Application Using the Worklist Service Remote APIs
It is possible to build a worklist application that works in a separate container and
uses remote APIs to reference the workflow services in the BPEL container. The
worklist service supports session bean-based remote APIs.
To use this approach, the JNDI and classpath configuration must be set up correctly. In
the client Java program, the first step is to create a
RemoteWorklistServiceClient instance and call its init() method. The
init() method loads the JNDI properties based on the classpath and creates a local
object that enables the client to talk to the remote server (the container where Oracle
BPEL Process Manager is running). After a handle to
RemoteWorklistServiceClient is obtained, most other operations are simple.
For using the Worklist Service Remote APIs, the JAVA classpath of the client program
must contain the following:
oc4jclient.jar;bpm-infra.jar;bpm-services.jar;orabpel.jar;orabpel-common.jar;
orabpel-thirdparty.jar;config_directory
where config_directory is a directory that contains the pc.properties and hw_
worklist_jndi.properties files. A sample hw_worklist_jndi.properties
file is provided in the Oracle_
Home\integration\orabpel\system\services\config directory. The
property settings in the hw_worklist_jndi.properties file are based on the type
of Oracle BPEL Process Manager installation you are using:
Worklist Application
17-45
Building a Worklist Application Using the Worklist Service Remote APIs
■
BPEL Process Manager for OracleAS Middle Tier:
java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
java.naming.provider.url=opmn:ormi://localhost:6003:OC4J_BPEL/hw_services
java.naming.security.principal=admin
java.naming.security.credentials=welcome
dedicated.connection=true
■
BPEL Process Manager for Developers:
java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
java.naming.provider.url=ormi://localhost/hw_services
java.naming.security.principal=admin
java.naming.security.credentials=welcome
dedicated.connection=true
The following example shows a code fragment for using the remote service.
// 1. get a handle to the remove worklist service client
client = new RemoteWorklistServiceClient();
client.init();
// 2. set approver's user and password
String user = "jstein";
String password = globalPassword;
System.out.println("vacationRequestTest: connecting as " + user);
// 3. get worklist context for user
IWorklistContext ctx = client.authenticateUser(user, password);
System.out.println("vacationRequestTest: got Worklist Context");
// 4. set filters for retrieving My tasks with Assigned status
Map filterMap = new HashMap();
filterMap.put(IWorklistService.FILTER_TYPE_TASK_FILTER,
IWorklistService.TASK_FILTER_MY);
filterMap.put(IWorklistService.FILTER_TYPE_STATUS_FILTER,
IWorklistService.STATUS_FILTER_ASSIGNED);
List tasks = client.getWorklistTasks(ctx,
filterMap,
IWorklistService.SORT_FIELD_TASK_TITLE,
IWorklistService.SORT_ORDER_ASCENDING);
// 5. APPROVE all vacationRequest tasks that are assigned to user
if (tasks != null)
{
for (int i=0; i<tasks.size(); i++)
{
Task task = (Task) tasks.get(i);
String taskId = task.getTaskId();
// check if the task is a vacation request
if (task.getTitle().startsWith("Vacation request"))
{
// get custom actions that can be performed
List customActions = client.getCustomActions(ctx, taskId);
for (int j=0; j<customActions.size(); j++)
{
String customAction = (String) customActions.get(j);
}
// get system actions that can be performed
17-46 Oracle BPEL Process Manager Developer’s Guide
Summary
List systemActions = client.getSystemActions(ctx, taskId);
for (int j=0; j<systemActions.size(); j++)
{
String systemAction = (String) systemActions.get(j);
}
// add some comments to the task
client.appendTaskComments(ctx, taskId, "foo");
// now approve the task
String action = "APPROVE";
client.customTaskOperation(ctx, taskId, action);
}
}
}
Note: The remote APIs can retrieve URL and text-based task
attachments. However, retrieving binary task attachments through the
remote APIs can produce unpredictable results and is not
recommended. The remote APIs can only submit URL-based
attachments. Creation or update of text-based or binary task
attachments is not possible with the remote APIs.
See Also: Oracle_
Home\integration\orabpel\docs\workflow\index.html for
Javadoc that describes the worklist service remote APIs
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. This application
is available in many languages. Instructions are provided for customizing the Worklist
Application and for building your own Worklist Application using the worklist service
APIs.
Worklist Application
17-47
Summary
17-48 Oracle BPEL Process Manager Developer’s Guide
18
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 JDeveloper BPEL Designer
■
Sensors and Oracle BPEL Console
■
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: Oracle_
Home\integration\orabpel\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 JDeveloper BPEL
Designer 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
Sensors 18-1
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
activity or how long it takes to complete a scope. Along with the activity sensor,
you can monitor variables of the activity also.
■
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 JDeveloper BPEL Designer, 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 18-3 and "Configuring Sensor Actions" on
page 18-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
List of sensors—the sensors for a sensor action
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
In JDeveloper BPEL Designer, sensors and sensor actions are displayed as part of the
process tree structure, as shown in Figure 18–1.
18-2
Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
Figure 18–1
Sensors and Sensor Actions Displayed in JDeveloper BPEL Designer
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 Oracle_
Home\integration\orabpel\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 JDeveloper BPEL Designer, as shown in Figure 18–2.
Activities that have sensors associated with them are indicated with a magnifying
glass.
Sensors 18-3
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
Figure 18–2
Creating an Activity Sensor
The Evaluation Time attribute shown in Figure 18–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"/>
18-4
Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
</activityConfig>
</sensor>
If you want to record all the incoming loan requests, create a variable sensor for the
variable input, as shown in Figure 18–3.
Figure 18–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 18–4.
Sensors 18-5
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
Figure 18–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"
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 you create a sensor action, as shown in Figure 18–5, and associate it
with the LoanApplicationSensor.
Figure 18–5
18-6
Creating a Sensor Action
Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
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 18–6, and associate it with both
CreditRatingSensor and LoanApplicationSensor.
Figure 18–6
Creating an Additional Sensor Action
A new entry is created in the sensorAction.xml file, as follows:
<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 as
well as 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 18–7.
Sensors 18-7
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
Figure 18–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, and JMS topic, then you can
create a sensor action with the custom publish type, as shown in Figure 18–8. The
name in the Publish Target field denotes a fully qualified Java class name that must be
implemented.
18-8
Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
Figure 18–8
Using the Custom Publish Type
Creating a Custom Data Publisher
To create a custom data publisher, double-click your BPEL project in JDeveloper BPEL
Designer and do the following:
1.
Open Project Properties, then Libraries, then OraBPEL, and add it to the Selected
Libraries list.
This adds the required BPEL libraries to your BPEL project.
2.
Create a new Java class.
The package and class name must match the publish target name of the sensor
action.
Sensors 18-9
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
3.
Select Tools, then Implement Interface, then Available Interfaces, and then
DataPublisher.
This updates the source file and fills in the methods and import statements of the
DataPublisher interface.
18-10 Oracle BPEL Process Manager Developer’s Guide
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
4.
Using the JDeveloper BPEL Designer editor, implement the publish method of the
DataPublisher interface, as shown in the following sample custom data
publisher class.
Sensors
18-11
Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer
5.
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.
18-12 Oracle BPEL Process Manager Developer’s Guide
Sensors and Oracle BPEL Console
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
JDeveloper BPEL Designer 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 Console
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
Console at
http://localhost:portnumber/BPELConsole
You can also select Start, then All Programs, then Oracle - Oracle_Home, then Oracle
BPEL Process Manager 10.1.2, and then BPEL Console.
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 JDeveloper BPEL
Designer. In Oracle BPEL Console, 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 18–9 is displayed.
Sensors
18-13
Sensors and Oracle BPEL Console
Figure 18–9
Sensor Data on the BPEL Processes Tab of Oracle BPEL Console
Viewing Sensor Data
The console provides support to monitor sensors for which a BpelReportsSchema
sensor action is defined. In Oracle BPEL Console, 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 18–10 is displayed.
18-14 Oracle BPEL Process Manager Developer’s Guide
Sensor Integration with Oracle Business Activity Monitoring
Figure 18–10
Sensor Data on the Instances Tab of Oracle BPEL Console
Note: Only sensors associated with a database sensor action are
displayed in the console. Sensors associated with a JMS queue, JMS
topic, or custom sensor action are not displayed.
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
18-15
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. Visit the
Oracle BAM Web site on the Oracle Technology Network for specific details about
Oracle BAM:
http://www.oracle.com/technology/products/integration/bam/index.html
Creating a Connection to Oracle BAM Server
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 JDeveloper BPEL
Designer.
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.
Use secure HTTP protocol
Select this check box if you want to use secure HTTP (HTTPS) 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.
10. Click Finish.
JDeveloper BPEL Designer reserves the following property names. These property
names define values for the Oracle BAM Server connection you just created.
18-16 Oracle BPEL Process Manager Developer’s Guide
Sensor Integration with Oracle Business Activity Monitoring
■
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
runtime 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 Console to update these values.
See Also:
■
■
Chapter 19, "BPEL Process Deployment and
Domain Management"
Appendix E, "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 or an activity sensor containing one sensor variable. This sensor
contains the BPEL variable that you want to monitor. Only one variable is allowed
for the sensor. If the variable has message parts, there must be only one message
part.
An activity sensor that does not have a variable
See Also: "Implementing Sensors and Sensor Actions in JDeveloper
BPEL Designer" on page 18-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 JDeveloper BPEL Designer.
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
18-17
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 18-17 for mapping sensor data to a data
object in Oracle BAM Server.
Data Object
Click the flashlight icon to open the Data Object Chooser window to
select the data object in Oracle BAM Server in which you want to
publish the sensor data.
Enable Batching
The data cached by default by the Oracle BAM component of the Oracle
BPEL Process Manager runtime 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. This
displays the Set Batch Parameters window. Select the check box to use
default batch parameter settings. If you deselect this check box, provide
customized values in the fields below. If you provide customized
values and then select this check box, the settings revert to the default
values.
18-18 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
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.
See the Oracle Business Activity Monitoring Installation Guide for
additional details about these batch process commands:
http://www.oracle.com/technology/products/integration/bam/htd
ocs/1012_support.html#docs
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).
Note: 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.
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 Console.
Use the following public views for SQL access to sensor values from any application
interested in the data. These views are populated when a sensor action is used to
publish to a database.
BPEL Reporting Schema
The database publisher persists the sensor data in a predefined relational schema in
the database. You can use SQL to query the sensor values in the following public
views from clients such as Oracle Warehouse Builder or OracleAS Portal.
Note: In Table 18–1 through Table 18–7, 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_ALL_PROCESSES
This view contains all the deployed BPEL processes across the Oracle BPEL Process
Manager domains.
Sensors
18-19
Sensor Public Views
Table 18–1
BPEL_ALL PROCESSES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
NAME
NVARCHAR2
100
U1,1
N
Name of the BPEL process
REVISION
VARCHAR2
50
U1,2
N
Revision of the BPEL process
DOMAIN_ID
VARCHAR2
50
U1,3
N
Oracle BPEL Process Manager domain
name
BASE_URL
NVARCHAR2
256
--
N
The base URL of the BPEL suite
SENSOR_URL
NVARCHAR2
256
--
N
The URL of the sensor file
SENSOR_
ACTION_URL
NVARCHAR2
256
--
N
The URL of the sensor action file
BPEL_PROCESS_ANALYSIS_REPORT
This view contains all the process instances of Oracle BPEL Process Manager.
Table 18–2
BPEL_PROCESS_ANALYSIS_REPORT View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
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
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
The 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
18-20 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
Table 18–2
(Cont.) BPEL_PROCESS_ANALYSIS_REPORT View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
EVAL_TIME
NUMBER
--
--
Y
Time in milliseconds that a process
takes to complete
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.
NULL means that no SLACompletion
property was set.
BPEL_SENSOR_PROCESS_INSTANCES
This view is a subset of BPEL_PROCESS_ANALYSIS_REPORT and contains those
process instances for which sensors are defined for the corresponding BPEL process
and for which a sensor has fired at least once.
Table 18–3
BPEL_SENSOR_PROCESS_INSTANCES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique instance 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
VARCHAR2
50
U1,3
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
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 instance
Sensors
18-21
Sensor Public Views
Table 18–3
(Cont.) BPEL_SENSOR_PROCESS_INSTANCES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
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
Time in milliseconds that a process
takes to complete
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.
NULL means that no SLACompletion
property was set.
INSTANCE_KEY
NUMBER
--
U1
N
Corresponds to the instance key used
in the Oracle BPEL Process Manager
client APIs
BPEL_ACTIVITY_SENSOR_VALUES
This view contains all the activity sensor values of the monitored BPEL processes.
Table 18–4
BPEL_ACTIVITY_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
PROCESS_
INSTANCE
NUMBER
--
--
N
ID of process instance
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
VARCHAR2
50
U1,3
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
--
N
The name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
The target of the fired sensor
ACTION_NAME
NVARCHAR2
100
--
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
18-22 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
Table 18–4
(Cont.) BPEL_ACTIVITY_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
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 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
Time in milliseconds that an activity
takes to complete
INSTANCE_KEY
NUMBER
--
NU1
N
Corresponds to the instance key used
in the Oracle BPEL Process Manager
client APIs
BPEL_FAULT_SENSOR_VALUES
This view contains all the fault sensor values.
Table 18–5
BPEL_FAULT_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
PROCESS_
INSTANCE
NUMBER
--
--
N
ID of process instance
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
VARCHAR2
50
U1,3
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
--
N
The name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
The target of the fired sensor
ACTION_NAME
NVARCHAR2
100
--
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
Sensors
18-23
Sensor Public Views
Table 18–5
(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 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
CLOB
--
--
Y
The fault message
INSTANCE_KEY
NUMBER
--
NU1
N
Corresponds to the instance key used
in the Oracle BPEL Process Manager
client APIs
BPEL_VARIABLE_SENSOR_VALUES
This view contains all the variable sensor values.
Table 18–6
BPEL_VARIABLE_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
ID
NUMBER
--
PK
N
Unique ID
PROCESS_
INSTANCE
NUMBER
--
--
N
ID of process instance
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
VARCHAR2
50
U1,3
N
Oracle BPEL Process Manager domain
name
SENSOR_NAME
NVARCHAR2
100
--
N
Name of the sensor that fired
SENSOR_TARGET NVARCHAR2
256
--
N
Target of the sensor
ACTION_NAME
NVARCHAR2
100
--
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
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
NUMBER
18-24 Oracle BPEL Process Manager Developer’s Guide
Sensor Public Views
Table 18–6
(Cont.) BPEL_VARIABLE_SENSOR_VALUES View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
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
NUMBER_VALUE
NUMBER
--
--
Y
The value of number-like variables
(such as float, double, and int)
DATE_VALUE
TIMESTAMP
--
--
Y
The value of date-like variables
BLOB_VALUE
BLOB
--
--
Y
The value of binary data variables
CLOB_VALUE
CLOB
--
--
Y
The value of CLOB-like variables
(XML)
INSTANCE_KEY
NUMBER
--
NU1
N
Corresponds to the instance key used
in the Oracle BPEL Process Manager
client APIs
BPEL_ERRORS
This view gives an overview of all the errors from BPEL services.
Table 18–7
BPEL_ERRORS 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
The 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
4000
--
Y
The context of the error
VARCHAR2
VARCHAR2
Sensors
18-25
Sensor Actions XSD File
Table 18–7
(Cont.) BPEL_ERRORS View
Attribute Name
SQL Type
Attribute Indexed or
Size
Unique?
Null?
Comment
COMPONENT
NUMBER
--
--
N
The BPEL component that caused the
error
THREAD_ID
VARCHAR2
200
--
N
The Java thread name where the error
occurred
STACKTRACE
CLOB
--
--
N
The Java stack trace
Sensor Actions XSD File
The section provides a sample sensor action schema that you can import into
JDeveloper BPEL Designer. 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"/>
<!--
18-26 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
the name of the JMS Queue/Topic or custom java API, ignored for other
publishTypes
-->
<xsd:attribute name="publishTarget" type="xsd:string" use="optional"/>
</xsd:attributeGroup>
<!-The sensor action type. A sensor action consists:
+ unique name
+ effective date
+ expiration date - Optional. If not defined, the probe is active
indefinitely.
+ filter (to potentially suppress data publishing even if a sensor marks
it as interesting). - Optional. If not defined, no filter is
used.
+ publishName A name of a publisher
+ publishType What to do with the sensor data?
+ publishTarget Name of a JMS Queue/Topic or custom publisher.
+ potentially many sensors.
-->
<xsd:complexType name="tSensorAction">
<xsd:sequence>
<xsd:element name="sensorName" type="xsd:string" minOccurs="1"
maxOccurs="unbounded"/>
<xsd:element name="property" minOccurs="0" maxOccurs="unbounded"
type="tns:tSensorActionProperty"/>
</xsd:sequence>
<xsd:attributeGroup ref="tns:tSensorActionAttributes"/>
</xsd:complexType>
<!-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">
Sensors
18-27
Sensor Actions XSD File
<xsd:sequence>
<xsd:element name="variable" type="tns:tActivityVariableConfig"
maxOccurs="unbounded" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="evalTime" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tAdapterConfig">
<xsd:annotation>
<xsd:documentation>
The configuration part of a adapter activity extends the activty
configuration with additional attributes for adapters
</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:extension base="tns:tActivityConfig">
<xsd:attribute name="headerVariable" use="required" type="xsd:string"/>
<xsd:attribute name="partnerLink" use="required" type="xsd:string"/>
<xsd:attribute name="portType" use="required" type="xsd:string"/>
<xsd:attribute name="operation" use="required" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tVariableConfig">
<xsd:complexContent>
<xsd:extension base="tns:tSensorConfig">
<xsd:attribute name="outputDataType" use="required" type="xsd:string"/>
<xsd:attribute name="outputNamespace" use="required" type="xsd:string"/>
<xsd:attribute name="queryName" use="optional" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tActivityVariableConfig">
<xsd:complexContent>
<xsd:extension base="tns:tVariableConfig">
<xsd:attribute name="target" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tFaultConfig">
<xsd:complexContent>
<xsd:extension base="tns:tSensorConfig"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tNotificationSvcConfig">
<xsd:complexContent>
<xsd:extension base="tns:tActivityConfig">
<xsd:attribute name="inputVariable" use="required" type="xsd:string"/>
<xsd:attribute name="outputVariable" use="required" type="xsd:string"/>
<xsd:attribute name="operation" use="required" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
18-28 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
<xsd:complexType name="tSensorConfig">
<xsd:sequence>
<xsd:element name="action" type="tns:tInlineSensorAction" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tInlineSensorAction">
<xsd:complexContent>
<xsd:restriction base="tns:tSensorAction"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tSensor">
<xsd:sequence>
<xsd:element name="activityConfig" type="tns:tActivityConfig"
minOccurs="0"/>
<xsd:element name="adapterConfig" type="tns:tAdapterConfig" minOccurs="0"/>
<xsd:element name="faultConfig" type="tns:tFaultConfig" minOccurs="0"/>
<xsd:element name="notificationConfig" type="tns:tNotificationSvcConfig"
minOccurs="0"/>
<xsd:element name="variableConfig" type="tns:tVariableConfig"
minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="sensorName" use="required" type="xsd:string"/>
<xsd:attribute name="kind" use="required" type="tns:tSensorKind"/>
<xsd:attribute name="classname" use="required" type="xsd:string"/>
<xsd:attribute name="target" use="required" type="xsd:string"/>
</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"/>
Sensors
18-29
Sensor Actions XSD File
<xsd:element name="adapterData" minOccurs="0" type="tns:tAdapterData"/>
<xsd:element name="variableData" type="tns:tVariableData" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="notificationData" type="tns:tNotificationData"
minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tFaultData">
<xsd:sequence>
<xsd:element name="activityName" type="xsd:string"/>
<xsd:element name="activityType" type="xsd:string"/>
<xsd:element name="data" type="xsd:anyType" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tActivityData">
<xsd:sequence>
<xsd:element name="activityType" type="xsd:string"/>
<xsd:element name="evalPoint" type="xsd:string"/>
<xsd:element name="errorMessage" nillable="true" minOccurs="0"
type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<!-xml type that will be provided to sensors for variable Datas. Note the
any element represents variable data.
-->
<xsd:complexType name="tVariableData">
<xsd:sequence>
<xsd:element name="target" type="xsd:string"/>
<xsd:element name="queryName" type="xsd:string"/>
<xsd:element name="updaterName" type="xsd:string" minOccurs="1"/>
<xsd:element name="updaterType" type="xsd:string" minOccurs="1"/>
<xsd:element name="data" type="xsd:anyType"/>
<xsd:element name="dataType" type="xsd:integer"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="tNotificationData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="messageID" type="xsd:string" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="fromAddress" type="xsd:string" minOccurs="0"/>
<xsd:element name="toAddress" type="xsd:string" minOccurs="0"/>
<xsd:element name="deliveryChannel" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="tAdapterData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="endpoint" type="xsd:string"/>
<xsd:element name="direction" type="xsd:string"/>
18-30 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
<xsd:element name="adapterType" type="xsd:string"/>
<xsd:element name="priority" type="xsd:string" minOccurs="0"/>
<xsd:element name="messageSize" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-The header of the document contains some metadata.
-->
<xsd:complexType name="tSensorActionHeader">
<xsd:sequence>
<xsd:element name="processName" type="xsd:string"/>
<xsd:element name="processVersion" type="xsd:string"/>
<xsd:element name="processID" type="xsd:long"/>
<xsd:element name="midTierInstance" type="xsd:string"/>
</xsd:sequence>
<xsd:attribute name="actionName" use="required" type="xsd:string"/>
</xsd:complexType>
<!-Sensor Action data is presented in the form of a header and potentially many
data elements depending on how many sensors associated to the sensor action
marked the data as interesting.
-->
<xsd:complexType name="tSensorActionData">
<xsd:sequence>
<xsd:element name="header" type="tns:tHeaderInfo"/>
<xsd:element name="payload" type="tns:tSensorData" minOccurs="1"
maxOccurs="1"/>
</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>
Sensors
18-31
Sensor Actions XSD File
</xsd:complexType>
<!-Extend tActivityData to include more elements
-->
<xsd:complexType name="tProcessActivityData">
<xsd:complexContent>
<xsd:extension base="tns:tActivityData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="evalTime" type="xsd:long" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="retryCount" type="xsd:int" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tVariableData to include more elements
-->
<xsd:complexType name="tProcessVariableData">
<xsd:complexContent>
<xsd:extension base="tns:tVariableData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tFaultData to include more elements
-->
<xsd:complexType name="tProcessFaultData">
<xsd:complexContent>
<xsd:extension base="tns:tFaultData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tAdapterData to include more elements
-->
<xsd:complexType name="tProcessAdapterData">
<xsd:complexContent>
<xsd:extension base="tns:tAdapterData">
18-32 Oracle BPEL Process Manager Developer’s Guide
Sensor Actions XSD File
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Extend tNotificationData to include more elements
-->
<xsd:complexType name="tProcessNotificationData">
<xsd:complexContent>
<xsd:extension base="tns:tNotificationData">
<xsd:sequence>
<xsd:element name="creationDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="modifyDate" type="xsd:dateTime" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-Copy of tSensorData type with some modified types.
-->
<xsd:complexType name="tProcessSensorData">
<xsd:sequence>
<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"/>
Sensors
18-33
Summary
<xsd:element name="instanceId" type="xsd:integer"/>
</xsd:sequence>
</xsd:complexType>
<!-The list of sensor values comprises of a process header describing the
BPEL process with name, cube instance id etc. and a list of sensor values
comprising of sensor metadata information and sensor values.
-->
<xsd:complexType name="tProcessSensorValueList">
<xsd:sequence>
<xsd:element name="process" type="tns:tProcessInstanceInfo" minOccurs="1"
maxOccurs="1"/>
<xsd:element name="sensorValue" type="tns:tProcessSensorValue" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<!-- The sensor list is the root element of the sensor.xml document in the
bpel process suitcase and is used to define sensors. -->
<xsd:element name="sensors" type="tns:tSensorList"/>
<!-- 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.
18-34 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
Console.
This part contains the following chapters:
■
Chapter 19, "BPEL Process Deployment and Domain Management"
■
Chapter 20, "Oracle BPEL Portlets"
■
Chapter 21, "Oracle BPEL Console 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 Console 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
■
Viewing BPEL Processes in Oracle BPEL Console
■
Build and Command Line Tools
■
Summary
See Also: The following documentation for tutorials in which you
deploy BPEL processes:
■
"Compiling and Deploying the BPEL Process" on page 3-16
■
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 Console.
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 Console to view
any currently running BPEL processes before compiling and deploying additional
processes.
BPEL processes can be compiled and deployed in two types of BPEL designer
environments:
■
Compiling and Deploying on JDeveloper BPEL Designer
■
Compiling and Deploying on Eclipse BPEL Designer
BPEL Process Deployment and Domain Management 19-1
Compiling and Deploying a BPEL Process
Note: 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.
Compiling and Deploying on JDeveloper BPEL Designer
To compile and deploy a BPEL process on JDeveloper BPEL Designer, right-click the
BPEL project (for this example, named OrderBooking) and select Deploy in the
Applications Navigator section:
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 the Oracle BPEL Server connection automatically created during
Oracle BPEL Process Manager installation (named LocalBPELServer). You can
create additional server connections by performing the following steps:
1.
Select Connection Navigator from the View main menu in JDeveloper BPEL
Designer.
2.
Right-click BPEL Process Manager Server.
3.
Select New BPEL Process Manager Connection.
This starts the BPEL Process Manager Connection wizard. After completion, this
new connection appears when you right-click the process and select Deploy.
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.
19-2
Oracle BPEL Process Manager Developer’s Guide
Compiling and Deploying a BPEL Process
If the server mode is development, you are not prompted and the version is
automatically overwritten.
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 Applications Navigator and select Deploy, then connection_
name, and then Deploy to default domain. Provide a more descriptive name
when prompted in the Your Version field of the Deploy Properties window (for
example, sales_div_1.0). You can then retire the other process version on Oracle
BPEL Console.
■
If you select Invoke Deployment Tool, the Deploy Properties window opens. This
window enables you to customize your settings by selecting a different or creating
a new Oracle BPEL Console 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 JDeveloper
BPEL Designer displays messages about the status of the deployment. For example,
the following message indicates that deployment was successful.
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.
Caution:
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-8
■
"Changing Oracle BPEL Server Mode" on page 19-8
Compiling Without Deploying on JDeveloper BPEL Designer
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:
Oracle_Home\integration\jdev\jdev\default\mywork\workspace_name\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)
Oracle_Home\integration\orabpel\domains\default\deploy
or
19-4
1.
Log into Oracle BPEL Console using Internet Explorer 6.0 or Mozilla Firefox 1.0.4
by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle
BPEL Process Manager 10.1.2, and then BPEL Console.
2.
Click BPEL Processes.
3.
Click Deploy New Process in the Related Tasks section.
4.
Click Browse to select the process, then click Open.
5.
Click Deploy.
6.
Click the Dashboard tab to view the newly deployed process.
Oracle BPEL Process Manager Developer’s Guide
Compiling and Deploying a BPEL Process
Compiling and Deploying on Eclipse BPEL Designer
To compile and deploy a BPEL process on Eclipse BPEL Designer, you click the Build
BPEL Project icon in the tool bar:
If you want to change the domain to which to deploy the process or the version label
of the process, you must edit properties in the project’s build.xml file. In this
example, the domain is named default and the label version is 1.0.
Name of the domain the generated BPEL suitcase will be deployed to
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<property name="deploy" value="default"/>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What version number should be used to tag the generated BPEL archive?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<property name="rev" value="1.0"/>
As with JDeveloper BPEL Designer, if you overwrite the version, the old version is
made stale, and the new version is made active. You cannot revert to the stale
definition. In addition, the stale version cannot be examined, and all flow and audit
information is lost. If you enter a different version label in the build.xml file (for
example, 2.0), it is deployed to Oracle BPEL Server, while the older, deployed version
(1.0) continues to run simultaneously on Oracle BPEL Server.
After you deploy the BPEL process, the Log Window at the bottom of Eclipse BPEL
Designer displays messages about the status of the deployment. For example, the
following message indicates that deployment was successful.
If deployment is unsuccessful, errors display at the bottom of the window. Click the
error next to the BUILD FAILED message to display the line of code that caused
deployment to fail.
Make corrections and redeploy.
BPEL Process Deployment and Domain Management 19-5
Compiling and Deploying a BPEL Process
See Also: "Creating and Managing a BPEL Domain" on page 19-7
BPEL Suitcase JAR File
You may have noticed the words BPEL suitcase that appeared in the successful
deployment Log Window messages shown for both JDeveloper BPEL Designer and
Eclipse BPEL Designer.
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 following directory. Note that the directory
named default in these directory paths refers to the domain in which you deployed
the suitcase JAR file. If you deploy your BPEL process to a domain named qa, that
name displays instead of default. The concepts of domains are described in later
sections of this chapter.
■
On JDeveloper BPEL Designer
Oracle_Home\integration\orabpel\domains\default\deploy
■
On Eclipse BPEL Designer
c:\orabpel\domains\default\deploy
The suitcase JAR file name follows the convention of bpel_projectname_
versionnumber.jar. For example:
bpel_LoanProcess_1.0.jar
Figure 19–1 shows an example of deployed suitcase JAR files in JDeveloper BPEL
Designer. Note that different version labels of OrderBooking are deployed
simultaneously.
Figure 19–1
19-6
Deployed BPEL Suitcase JAR Files
Oracle BPEL Process Manager Developer’s Guide
Creating and Managing a BPEL Domain
See Also:
■
"Creating and Managing a BPEL Domain" on page 19-7
■
"Deploying a BPEL Suitcase to a Specific Domain" on page 19-9
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. A BPEL domain is
identified by an ID and protected by a password. When Oracle BPEL Process Manager
is installed, an initial domain named default is created. The initial password of the
default domain is set to bpel.
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:
■
Changing the Default Domain Password
■
Changing Oracle BPEL Admin Console Password
■
Creating a BPEL Domain
■
Changing Oracle BPEL Server Mode
■
Deploying a BPEL Suitcase to a Specific Domain
■
Location of BPEL JAR Suitcase Files in a Specific Domain
■
Undeploying a BPEL Process from a Specific Domain
Changing the Default Domain Password
A domain named default is automatically installed with Oracle BPEL Process
Manager. The initial password for this domain is bpel. You can change this password.
1.
Log in to Oracle BPEL Console using Internet Explorer 6.0 or Mozilla Firefox 1.0.4
by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle
BPEL Process Manager 10.1.2, and then BPEL Console.
2.
Click Manage BPEL Domain at the top of the page.
3.
Click Password.
4.
Enter a new domain password and click Apply.
Changing Oracle BPEL Admin Console Password
You create BPEL domains and configure Oracle BPEL Server properties from Oracle
BPEL Admin Console. The initial password for Oracle BPEL Admin Console is listed
BPEL Process Deployment and Domain Management 19-7
Creating and Managing a BPEL Domain
in the Oracle Application Server Integration Installation Guide. You must change this
password immediately after installation.
Follow these instructions to change Oracle BPEL Admin Console password.
1.
Use Internet Explorer 6.0 or Mozilla Firefox 1.0.4 to access Oracle BPEL Admin
Console:
http://locahost:9700/BPELAdmin
You can also access Oracle BPEL Admin Console by clicking Go to BPEL Admin
at the bottom of the login page for Oracle BPEL Console.
2.
Enter the default password.
3.
Click the Password link in the upper left corner of the window.
4.
Enter and re-enter the new administrator password.
5.
Enter the existing administrator password.
6.
Click Apply.
A message appears indicating that the password has been changed.
Creating a BPEL Domain
You can create additional domains by performing the following procedures.
1.
Use Internet Explorer 6.0 or Mozilla Firefox 1.0.4 to access Oracle BPEL Admin
Console:
http://locahost:9700/BPELAdmin
You can also access Oracle BPEL Admin Console by clicking Go to BPEL Admin
at the bottom of the login page for Oracle BPEL Console.
2.
Enter the 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 and a
password. When you log in to Oracle BPEL Console, you can select this domain.
6.
Stop and restart Oracle BPEL Server before deploying a BPEL process.
7.
Return to the Applications Navigator.
8.
Right-click a process.
9.
Select Deploy, and then connection_name (for example, LocalBPELServer), and
then Refresh.
10. Right-click the process again.
11. Select Deploy, and then connection_name (for example, LocalBPELServer).
The new domain is now available for selection.
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
19-8
Oracle BPEL Process Manager Developer’s Guide
Creating and Managing a BPEL Domain
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 JDeveloper BPEL
Designer.
1.
Right-click the BPEL process in the Applications Navigator.
2.
Select Deploy, and then Invoke Deployment Tool.
The Server Mode field of the Deploy Properties window displays the mode.
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 see the current mode of your server in JDeveloper BPEL
Designer.
1.
Use Internet Explorer 6.0 or Mozilla Firefox 1.0.4 to access Oracle BPEL Admin
Console:
http://locahost:9700/BPELAdmin
You can also access Oracle BPEL Admin Console by clicking Go to BPEL Admin
at the bottom of the login page for Oracle BPEL Console.
2.
Enter the password.
3.
Change the productionServer property value to false.
4.
Click Apply.
5.
Return to the Deploy Properties 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:
BPEL Process Deployment and Domain Management 19-9
Creating and Managing a BPEL Domain
<?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 Console to remotely upload and deploy a BPEL JAR. 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 already
deployed the BPEL suitcase locally, you can upload it from your local deployment
directory. See "Location of BPEL JAR Suitcase Files in a Specific Domain" on
page 19-10 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-21 for
additional details about Ant and bpelc
Location of BPEL JAR Suitcase Files in a Specific Domain
For a domain named qa and a default Oracle BPEL Process Manager installation into
the C:\ directory on Windows, BPEL JAR files for the qa domain reside in the
following directories:
■
On JDeveloper BPEL Designer
Oracle_Home\integration\orabpel\domains\qa\deploy
■
On Eclipse BPEL Designer
Orabpel\domains\qa\deploy
If you use the bpelc task with a deploy property value of qa, the BPEL suitcase JAR
file is automatically copied to this directory. If you want to manually or remotely
deploy a BPEL JAR suitcase file to a BPEL domain, you can also copy the JAR file into
that directory. The file is automatically detected and loaded into that domain by the
Oracle BPEL Process Manager.
See Also: "BPEL Suitcase JAR File" on page 19-6
Undeploying a BPEL Process from a Specific Domain
Oracle BPEL Console 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
19-10 Oracle BPEL Process Manager Developer’s Guide
Viewing BPEL Processes in Oracle BPEL Console
stale and their execution is cancelled. Note that every task that can be performed in
Oracle BPEL Console can also be performed programmatically.
Viewing BPEL Processes in Oracle BPEL Console
If compilation and deployment are successful, you can run and manage the BPEL
process from Oracle BPEL Console. This section provides an overview of the main
pages of Oracle BPEL Console.
1.
Log into Oracle BPEL Console using Internet Explorer 6.0 or Mozilla Firefox 1.0.4
by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle
BPEL Process Manager 10.1.2, and then BPEL Console.
2.
Select the domain and enter the password. If this is the default domain, the
password is initially set to bpel.
3.
See the following sections for an overview of Oracle BPEL Console:
■
Dashboard Tab: Viewing Processes
■
BPEL Processes Tab: Managing the Process Life Cycle
■
Instances Tab: Viewing Process Instances
■
Activities Tab: Viewing Process Activities
Dashboard Tab: Viewing Processes
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
Console to view any currently running BPEL processes before compiling and
deploying additional processes. The asterisk indicates that OrderBooking version 1.0
is the default process. Default processes are described later in this chapter.
BPEL Process Deployment and Domain Management
19-11
Viewing BPEL Processes in Oracle BPEL Console
Note that each Oracle BPEL Console page includes links at the top for managing BPEL
domains and accessing the BPEL site on the Oracle Technology Network, and a
drop-down list for switching to another domain.
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.0) is the default
process).
For each BPEL process, Oracle BPEL Console 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.
2.
Click a specific process in the BPEL Process list.
This window enables you to manage the life cycle and state of the BPEL process.
19-12 Oracle BPEL Process Manager Developer’s Guide
Viewing BPEL Processes in Oracle BPEL Console
3.
4.
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.
■
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 State
■
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 Console. When
deployed, a process is marked as default only if it is the first version of a deployed process.
There can be only one default process. Subsequent deployments of an already-deployed
process do not become defaults by virtue of deployment. 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.
BPEL Process Deployment and Domain Management
19-13
Viewing BPEL Processes in Oracle BPEL Console
Process
Description
Undeployed
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 Console, 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:
Oracle_Home\integration\orabpel\domains\domain_name\deploy\bpel_
OrderBooking_*.jar files (for example, bpel_OrderBooking_1.0.jar, bpel_
OrderBooking_2.0.jar, and so on)
Oracle_Home\integration\orabpel\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 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 2 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.
19-14 Oracle BPEL Process Manager Developer’s Guide
Viewing BPEL Processes in Oracle BPEL Console
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 versions of the same processes are created, as shown in
Table 19–1. OrderBooking version 1.0 receives two messages, which results in the
creation of two instances.
Table 19–1
Stage 1: Two Process Versions Created
State
Default Process
On Arrival of New
Message Request
Stage
Action
Life Cycle
1
Deploy
OrderBooking
version 1.0
Active=1.0 On=1.0
Version 1.0
Create an instance for
(automatically set) OrderBooking version
1.0
1
Deploy
OrderBooking
version 2.0
Active=2.0 On=2.0
Version 1.0
Create another instance
for OrderBooking
version 1.0
The life cycle and state of the two OrderBooking versions displays in the BPEL
Processes tab shown in Figure 19–2. Because OrderBooking version 1.0 was the first
deployed version of this process, it automatically became the default process
(indicated by the asterisk). The two messages that resulted in the creation of two
OrderBooking version 1.0 instances have both completed.
Figure 19–2
Stage 1 BPEL Processes
The two completed instances of OrderBooking version 1.0 display in the Instances tab
shown in Figure 19–3.
BPEL Process Deployment and Domain Management
19-15
Viewing BPEL Processes in Oracle BPEL Console
Figure 19–3
Stage 1 BPEL Instances
In stage 2, you change OrderBooking version 2.0 to be the default and retire
OrderBooking version 1.0, as shown in Table 19–2.
Table 19–2
Stage 2 Change the Default Process and Retire a Process
Default
Process
On Arrival of New
Message Request
Stage Action
Life Cycle
State
1
Deploy
OrderBooking
version 1.0
Active=1.0
On=1.0
Version 1.0
Create an instance for
(automatically OrderBooking
set)
version 1.0
1
Deploy
OrderBooking
version 2.0
Active=2.0
On=2.0
Version 1.0
Create another
instance for
OrderBooking
version 1.0
2
Change default
process to
OrderBooking
version 2.0
Active=1.0
On=1.0
Version 2.0
Create an instance for
OrderBooking
version 2.0
2
Retire
OrderBooking
version 1.0
Retired=2.0
On=2.0
Version 2.0
No action
Figure 19–4 shows Mark as Default being selected for OrderBooking version 2.0.
Figure 19–4
Stage 2 Default Revision
19-16 Oracle BPEL Process Manager Developer’s Guide
Viewing BPEL Processes in Oracle BPEL Console
The modified life cycle and state of the two OrderBooking versions displays in the
BPEL Processes tab shown in Figure 19–5. Because OrderBooking version 2.0 was
explicitly selected as the default process, it now displays the asterisk. The message that
resulted in the creation of an OrderBooking version 1.0 instance has completed.
OrderBooking version 1.0 displays as Retired.
Figure 19–5
Stage 2 BPEL Processes
The completed instance of OrderBooking version 2.0 displays in the Instances tab
shown in Figure 19–6.
Figure 19–6
Stage 2 BPEL Instances
If you click the Dashboard tab, the retired OrderBooking version 1.0 no longer
appears. This means you can no longer create an instance for this version.
In stage 3, you make OrderBooking version 1.0 inactive and then undeploy it, as
shown in Table 19–3.
Table 19–3
Stage 3 Deactivate and Undeploy a Process
Default
Process
On Arrival of New
Message Request
Stage Action
Life Cycle
State
1
Deploy
OrderBooking
version 1.0
Active=1.0
On=1.0
Version 1.0
Create an instance for
(automatically OrderBooking
set)
version 1.0
1
Deploy
OrderBooking
version 2.0
Active=2.0
On=2.0
Version 1.0
Create another
instance for
OrderBooking
version 1.0
2
Change default
process to
OrderBooking
version 2.0
Active=1.0
On=1.0
Version 2.0
Create an instance for
OrderBooking
version 2.0
BPEL Process Deployment and Domain Management
19-17
Viewing BPEL Processes in Oracle BPEL Console
Table 19–3
(Cont.) Stage 3 Deactivate and Undeploy a Process
Stage Action
Life Cycle
State
Default
Process
On Arrival of New
Message Request
2
Retire
OrderBooking
version 1.0
Retired=2.0
On=2.0
Version 2.0
No action
3
Make
OrderBooking
version 1.0 inactive
Retired=2.0
Off=2.0
Version 2.0
No action
3
Undeploy
OrderBooking
version 1.0
Retired=2.0
Off=2.0
Version 2.0
No action
The state of OrderBooking version 1.0 is changed to Off.
Figure 19–7
Stage 3 Process State
The state of OrderBooking version 1.0 displays as Off in the BPEL Processes tab
shown in Figure 19–8. 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.
Figure 19–8
Stage 3 BPEL Processes
OrderBooking version 1.0 is then undeployed, as shown in Figure 19–9.
19-18 Oracle BPEL Process Manager Developer’s Guide
Viewing BPEL Processes in Oracle BPEL Console
Figure 19–9
Stage 3 Undeploy
The BPEL Processes tab in Figure 19–10 no longer displays OrderBooking version 1.0.
Note also that the asterisk no longer displays for OrderBooking 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. This indicates
that this is the default process. If you deploy an OrderBooking version 3.0, the asterisk
again appears next to OrderBooking version 2.0.
Figure 19–10
Stage 3 BPEL Processes
The two completed instances of the undeployed OrderBooking version 1.0 display as
disabled in the Instances tab shown in Figure 19–11.
Figure 19–11
Stage 3 Instance of Undeployed Process
Clicking one of the completed instances displays the status as Stale in Figure 19–12.
Figure 19–12
Stage 3 Status Message of Undeployed Process
Instances Tab: Viewing Process Instances
1.
Click the Instances tab to view BPEL process instances.
BPEL Process Deployment and Domain Management
19-19
Viewing BPEL Processes in Oracle BPEL Console
2.
Click an instance in the Instance column (for example, Instance #3 of
OrderBooking). From this page, you can perform the following tasks:
■
■
View the state of the instance (for example, COMPLETED or ACTIVE)
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 code of the BPEL file.
■
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 you created in this instance.
Note: The Flow and Audit links do not provide details about the
actions or states of any header variables you defined during design
time. As a workaround, use the Debug link to view header variable
details.
See Also: The following documentation for additional details about
sensors:
■
Chapter 18, "Sensors"
■
Oracle BPEL Process Manager Order Booking Tutorial
Activities Tab: Viewing Process Activities
1.
Click the Activities tab to view the status of activities in the deployed BPEL
process instance.
19-20 Oracle BPEL Process Manager Developer’s Guide
Build and Command Line Tools
See Also: The following documentation for tutorials in which you
run processes from Oracle BPEL Console and view their results from
the Audit and Flow links:
■
"Testing the BPEL Process" on page 3-16
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
Build and Command Line Tools
When you deploy a BPEL process, several build and compiler command line tools are
automatically invoked. This section provides an overview of these tools, plus an
additional command line tool for generating XML facades:
■
Apache Ant
■
bpelc
■
schemac
Apache Ant
Apache Ant is a Java-based build tool used by Oracle BPEL Process Manager for
compiling and deploying the BPEL process. Ant is similar to a make file. However,
instead of being extended with operating system-dependent, shell-based commands,
Ant is extended using Java classes. The configuration files are XML-based and call out
a target tree where various tasks are executed.
See Also: http://ant.apache.org/
BPEL Process Deployment and Domain Management
19-21
Build and Command Line Tools
bpelc
bpelc (or bpelc.sh for UNIX operating systems) is the Oracle BPEL Process
Manager tool that compiles and deploys BPEL processes. For example, when you
compile and deploy a BPEL process, you see bpelc being invoked as a task inside the
Apache Ant build.xml file in the Log Window of Eclipse BPEL Designer.
Table 19–4 shows the supported bpelc options:
Table 19–4
Parameters
Attribute
Description
Required
home
The orabpel home directory (or whatever you named your
Oracle_Home directory), which is typically available as Ant
property $home
No
input
The deployment descriptor location path, By default, it looks
for bpel.xml under the current directory.
No
rev
The revision (version) tag for the deployed process.
No
deploy
Deploys the BPEL process archive to the specified domain in
No
the local Oracle home. The domain must be accessible through
the file system for this option to work.
keepGenerated
Includes the BPEL process Java classes in the generated BPEL
archive. The value defaults to false.
No
verbose
Generates additional debugging messages about compiler
actions. The value defaults to false.
No
force
Always compiles the process; the compiler does not check the
time stamp of .bpel, .wsdl and .xml files. The value
defaults to false.
No
classpath
Specifies where to find user class files. This attribute is similar
to a PATH structure and can also be set through a nested class
path element.
No
lib
Oracle BPEL Process Manager system lib directory.
No
help
Displays the help message. This value defaults to false.
No
out
Specifies the location in which to deploy the BPEL archive.
No
This option is used when the deploy attribute is not used. For
example:
out=”c:\myproject\bpel\deploy”
Examples
The following Ant task compiles and generates a BPEL archive file in the current
directory using the default bpel.xml deployment descriptor.
Use the following bpelc task sample to deploy a BPEL archive into the default
domain deploy directory:
<bpelc home="${home}" rev="${rev}" deploy="default"/>
To deploy the BPEL archive into the c:\myproject directory:
<bpelc home="${home}" rev="${rev}" out="C:\myproject"/>
Specify a deployment descriptor file name:
<bpelc home="${home}" rev="${rev}" deploy="default" input="orderdd.xml"/>
Specify a user classpath for bpelc:
19-22 Oracle BPEL Process Manager Developer’s Guide
Build and Command Line Tools
<bpelc home="${home}" rev="${rev}" deploy="default"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="${java.class.path}"/>
</classpath>
</bpelc>
schemac
schemac (or schemac.sh for UNIX operating systems) is a schema compiler utility
provided with Oracle BPEL Process Manager. You use this utility to generate XML
facades. XML facades are a set of Java interfaces and classes through which you can
access and modify BPEL (and other XML) variables and map individual XML values
to Java variables with get and set methods. Classes are generated only for the
complexTypes schema types and element with an anonymous complexType. This
is similar to the jaxb compiler.
You can invoke schemac from the operating system command prompt to perform
specific tasks. schemac command line syntax uses the following format.
schemac options filename | classname(s)
where filename is the name of a file ending with .xsd and containing a valid XML
schema definition and classname is the name of a valid Java class (without the
.java suffix). Only use this argument when the -R option is supplied.
Table 19–5 describes the supported options:
Table 19–5
Parameters
Attribute
Description
Required
input
The XML schema is the name of a file (ending with .xsd or
.wsdl) containing a valid XML schema definition.
Yes
out
Specify where to place generated facade class files. This value
defaults to the current directory.
No
doc
Generates Javadoc for the generated classes and redirects it to
the specified location.
No
jar
Archives the generated classes into the specified JAR file name.
No
verbose
Generates more debugging messages about the compiler actions. No
Defaults to false.
noCompile
Generates only the Java source files and does not compile the
generated sources when set to true. This value defaults to
false.
No
help
Displays the help message. This value defaults to false.
No
sourceOut
Specifies the location in which to redirect the generated Java
files. For example:
No
sourceOut=”c:\myproject\bpel\facade\source”
BPEL Process Deployment and Domain Management
19-23
Summary
Table 19–5
(Cont.) Parameters
Attribute
Description
Required
nsMap
To override the default Java package name, specify the
namespace to the Java package mapping file. For example:
No
nsMap="mynsmap.txt"
The content of mynsmap.txt looks as follows:
http://samples.otn.com/xpath/autoloan=boo.foo.g
oo
Note: If it is a name-value property file, you must escape the
colon (:) using a backslash (\). If there is no nsMap attribute, by
default schemac generates the package name from the
namespace. For example, the default Java package name for
http://samples.otn.com/xpath/autoloan is
com.otn.samples.xpath.autoloan.
Examples
Generate the facade classes from an XSD and place them under the current directory:
<schemac input="${basedir}/Order.xsd "/>
Generate the facade classes from a WSDL schema file:
<schemac input="${basedir}/PurchaseOrder.wsdl "/>
Generate the Javadoc into the c:\myjavadoc directory:
<schemac input="${basedir}/Order.xsd" doc="c:\myjavadoc"/>
Archive the generated facade classes into a .jar file:
<schemac input="${basedir}/XPath.wsdl" jar="myorderfacade.jar"/>
Redirect the generated facade classes into a specific directory:
<schemac input="${basedir}/Order.xsd " out="${basedir}/BPEL-INF/classes"/>
Specify the namespace Java package mapping file to override the default behavior:
<schemac input="${basedir}/Order.xsd " out="${basedir}/BPEL-INF/classes"
nsMap="mynsmap.txt"/>
See Also:
■
■
"Using an XML Facade to Simplify DOM Manipulation" on
page 10-4
Oracle_
Home\integration\orabpel\samples\tutorials\702.Bi
ndings for XML facade samples
Summary
This chapter describes how to compile and deploy BPEL processes. It describes key
features of BPEL suitcase JAR files. It also describes how to create and manage BPEL
domains, including changing domain and BPEL Admin Console passwords, creating
domains, changing Oracle BPEL Server modes (production or development),
managing BPEL suitcase JAR files, and undeploying processes. An overview of Oracle
BPEL Console is also provided, including a detailed description of managing different
19-24 Oracle BPEL Process Manager Developer’s Guide
Summary
versions of BPEL processes. Finally, a discussion on how to use the Apache Ant,
bpelc, and schemac build tools is provided.
BPEL Process Deployment and Domain Management
19-25
Summary
19-26 Oracle BPEL Process Manager Developer’s Guide
20
Oracle BPEL Portlets
Oracle BPEL Portlets consist of Oracle BPEL Console report portlets and Oracle BPEL
Worklist Application portlets. This chapter describes how to deploy the Oracle BPEL
Portlets and configure the Oracle Application Server Portal (OracleAS Portal) to
provide access to data from these portlets.
This chapter contains the following topics:
■
OracleAS Portal Introduction
■
Step 1: Installing the Required Oracle Application Server Components
■
Step 2: Deploying the Portlets
■
Step 3: Registering Web Providers with OracleAS Portal
■
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
■
Step 5: Mapping Portlet Parameters with Page Parameters
■
Summary
OracleAS Portal Introduction
OracleAS Portal is a component of Oracle Application Server used for the
development, deployment, administration, and configuration of enterprise class
portals. OracleAS Portal enables you to present information from multiple, unrelated
data sources in a single organized view. This view, a portal page, can contain one or
more components called portlets that can each get their content from different data
sources.
A portlet parameter provides a configurable way of passing a value to a portlet. Using
portlet parameters, the information displayed in a portlet can be specific to a particular
page or user. Portlet parameters are created by the portlet developer and exposed to
the page designer through the user interface. After adding a portlet to a page, page
designers can assign values to the public portlet parameters to make the information
displayed in the portlet specific to the page.
Web providers enable you to deploy portlets to OracleAS Portal. They may reside on
the same application server as OracleAS Portal, on a remote application server, or
anywhere on the network. Web providers use open standards, such as XML, SOAP,
HTTP, or J2EE for deployment, definition, and communication with OracleAS Portal.
Figure 20–1 provides an overview of this integration.
Oracle BPEL Portlets 20-1
Figure 20–1
Oracle Application Server Portal and BPEL Process Integration Overview
OracleAS Portal
Portlet
View
1
2
Portlet
View
3
Oracle BPEL
Console Reports
(Web Provider)
1
2
3
Oracle BPEL
Worklist Application
(Web Provider)
Oracle BPEL Portlets
1
Register Web provider with
OracleAS Portal
2
Portlet parameters are passed
to Web provider on page
refresh
3
Web provider responds with
data based on portlet
parameters and customization
settings
You can configure OracleAS Portal to access the following portlets:
■
Oracle BPEL Console reports portlets
Enables you to access instance state, instance execution time, performance, activity
sensor, and fault sensor reports that describe the behavior of instances of a selected
BPEL process. Oracle BPEL Console reports 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: The following documentation for additional descriptions
of these report types:
■
■
■
"Defining Oracle BPEL Console Report Portlet Parameters and
Accessing Portlet Data Sources" on page 20-9
"Creating Oracle BPEL Console Reports" on page 21-1
Oracle BPEL Worklist Application portlets
Enables you to access Oracle BPEL Worklist Application, a Web interface that
enables users to access and act on tasks assigned to them. The tasks displayed
depend on the user’s profile, and the actions allowed depend on the user’s
privileges. The Oracle BPEL Worklist Application is layered on top of the BPEL
worklist service.
See Also: The following documentation for descriptions of Oracle
BPEL Worklist Application portlets and for additional details about
Oracle BPEL Worklist Application:
■
■
20-2
"Defining Oracle BPEL Worklist Application Portlet Parameters
and Accessing Portlet Data Sources" on page 20-12
Chapter 17, "Worklist Application"
Oracle BPEL Process Manager Developer’s Guide
Step 2: Deploying the Portlets
Note: If you install the identity service demo user community and
run the workflow service samples shipped with Oracle BPEL Process
Manager, you can display data about these users in the Oracle BPEL
Worklist Application portlets.
Step 1: Installing the Required Oracle Application Server Components
OracleAS Portal uses Oracle Internet Directory, an LDAP-compliant directory that
provides a single repository and administration environment for user accounts. Oracle
BPEL Worklist Application also requires the use of Oracle Internet Directory; Oracle
BPEL Console does not require this component. Therefore, to use both of these Oracle
BPEL Portlets, you must install the following installation types to use OracleAS Portal:
■
Install the Identity Management and Metadata Repository installation type of
Oracle Application Server Infrastructure 10g Release 2 (10.1.2).
■
Install Portal and Wireless middle tier 10g Release 2 (10.1.2).
■
Install BPEL Process Manager for OracleAS Middle Tier.
Note: OracleAS Portal cannot be configured for use with the BPEL
Process Manager for Developers installation type. This is because
BPEL Process Manager for Developers does not use Oracle Internet
Directory (required by OracleAS Portal).
Step 2: Deploying the Portlets
You must install Oracle BPEL Process Manager and deploy the Oracle BPEL Portlets
.ear file. Use one of the following methods to deploy the .ear file:
■
■
Deploying Portlets with dcmctl
Deploying Portlets with Oracle Enterprise Manager 10g Application Server
Control Console
Deploying Portlets with dcmctl
Follow these procedures to deploy the portlets with the dcmctl utility.
1.
Change directories to the following location:
Oracle_Home\dcm\bin
2.
Enter the following command to deploy Oracle BPEL Portlets:
dcmctl deployApplication -f Oracle_
Home\integration\orabpel\system\services\lib\BPELPortlet.ear -a
BPELPortlet -co OC4J_BPEL -pa orabpel
When deployment completes successfully, a message similar to the following
appears:
Application:
Component Name:
Component Type:
Instance:
bpelportlet
OC4J_BPEL
OC4J
mark.my-pc.us.oracle.com
Oracle BPEL Portlets 20-3
See Also: Oracle Application Server Administrator’s Guide for
additional information about the dcmctl utility
Deploying Portlets with Oracle Enterprise Manager 10g Application Server Control
Console
Follow these procedures to deploy the portlets with Oracle Enterprise Manager 10g
Application Server Control Console.
1.
Go to the following URL:
http://hostname:port/
where:
■
■
hostname is the name of the host on which the Portal and Wireless and
Oracle BPEL Process Manager middle tier instances are installed.
port is the number assigned during Oracle BPEL Process Manager
installation. The following sources also identify the port number used to
access the Oracle Enterprise Manager 10g Application Server Control Console:
–
The setupinfo.txt file in the install subdirectory of the Oracle
home for your middle tier installation
–
The End of Installation page that displayed during installation
Note: On Windows platforms, you can also start Oracle Enterprise
Manager 10g Application Server Control Console from the Start Menu
by selecting Start, then All Programs, then Oracle - home_name
Enterprise Manager, and then Application Server Control Console.
2.
Enter the following login details when prompted:
Field
Value
Username
Enter ias_admin
Password
Enter the password you specified during Portal and Wireless installation and
Oracle BPEL Process Manager installation for the ias_admin user.
The Oracle Application Server home page appears.
3.
Select OC4J_BPEL from the Name column of the System Components table.
4.
Click the Applications tab.
5.
Click Deploy EAR file.
The Deploy Application window appears.
6.
20-4
Enter the following details:
Field
Description
J2EE Application
Select the Oracle_
Home\integration\orabpel\system\services\lib\BPELPortlet.ear file.
Application Name
Enter BPELPortlet
Parent Application
Select orabpel
Oracle BPEL Process Manager Developer’s Guide
Step 3: Registering Web Providers with OracleAS Portal
7.
Click Continue.
The Deploy Application: URL Mapping for Web Modules window appears.
8.
Accept the default BPELPortlet for Oracle BPEL Process Manager value or enter a
different name in the URL Mapping field.
9.
Click Next.
The Deploy Application: User Manager window appears.
10. Select Use JAZN LDAP User Manager.
The LDAP Location field displays the Oracle Internet Directory instance
associated with the Oracle Application Server Infrastructure.
11. Click Next.
The Deploy Application: Review window appears.
12. Review a summary of the selections you made on previous windows:
■
The EAR file to deploy
■
The deployment destination instance
■
The URL mapping for Web modules
13. Click Deploy.
Messages display indicating that deployment is in progress. When complete, the
following message appears:
Application "BPELPortlet" was successfully deployed.
Step 3: Registering Web Providers with OracleAS Portal
Web providers provide portlet data to OracleAS Portal. You must first register the
Oracle BPEL Process Manager Web provider with the specific OracleAS Portal
instance. This enables you to use the Oracle BPEL Console report portlets and Oracle
BPEL Worklist Application portlets in OracleAS Portal pages.
Once you have registered these Web providers, you can access the data provided by
the portlets.
1.
Go to the OracleAS Portal home page. For example:
http://hostname:port_number/pls/portal
where hostname is the host on which the Portal and Wireless middle tier is
installed and port_number is typically 7777. If you are unsure, see the
setupinfo.txt file in the Oracle_Home\install directory for your Portal
and Wireless installation. You can also access OracleAS Portal from a link on the
Oracle Application Server Welcome page.
2.
Log in to the OracleAS Portal instance using the portal user name and ias_admin
password. This is the same password that you specified during Portal and
Wireless middle tier installation and BPEL Process Manager for OracleAS Middle
Tier installation.
3.
Select the Administrator tab, then the Portlets subtab to access the Portal Builder
window to register the provider.
4.
Click Register a Provider in the Remote Providers section.
5.
Enter the following details on the Provider Information page:
Oracle BPEL Portlets 20-5
Field
Description
Name
Enter a unique and recognizable name.
Display Name
Enter a name to display on the portlet page header.
Timeout
Enter the amount of time a page takes to render if the portlet is
not responding.
Timeout Message
Enter message to display when a timeout occurs.
Implementation Style
Ensure that Web is selected.
6.
Click Next.
7.
Enter appropriate details on the General Properties page. For the URL of the Web
provider, ensure that you enter the following details for Oracle BPEL Process
Manager:
http://bpel_host:bpel_port/BPELPortlet/providers
where bpel_host is the host on which Oracle BPEL Process Manager is installed
and bpel_port is the port. For BPEL Process Manager for OracleAS Middle Tier
installations, the port is typically 7777 or 7778. If you are unsure of the port, see
the Oracle_Home\install\bpelsetupinfo.txt file that was created after
BPEL Process Manager for OracleAS Middle Tier installation.
8.
Select Once Per User Session from the Login Frequency list.
9.
Click Next.
10. Enter your user or group name in the Grantee field of the Control Access page,
click Add, and then click Finish. If you are not sure about the user or group name,
click the appropriate browse icon.
If provider registration was successful, you receive a success message.
11. Click OK.
12. Click Builder, then Build to display the Portal Builder page.
13. Go to the Page Groups section of the Portal Builder page.
14. Select the group from the Page Group list. If a page group does not exist, create
one.
15. Click Create a Page and following the steps that appear.
The new page appears with the display name header you entered when creating
the page.
16. Click the + icon (second icon from the left) to add an instance of the portlet to the
page.
The Add Portlets To Region page appears.
20-6
Oracle BPEL Process Manager Developer’s Guide
Step 3: Registering Web Providers with OracleAS Portal
17. Click Portlet Staging Area in the Portlet Repository section.
18. Click the portlet you previously created in the Available Portlets section.
This displays the Oracle BPEL Portlets in the Available Portlets section.
19. Click the portlets you want.
The selected portlets are added to the Selected Portlets section.
Oracle BPEL Portlets 20-7
20. Click OK.
21. See "Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources" on
page 20-8 for information on setting portlet properties.
See Also: See Oracle Application Server Portal User’s Guide for
additional details about using OracleAS Portal
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
When you access a portlet for the first time, some default settings already appear for
Oracle BPEL Worklist Application. No default settings appear for Oracle BPEL
Console reports. For example, if you selected Instance Execution Time in Step 19 on
page 20-8, the page appears with the following message.
1.
Click the Edit Defaults icon (first icon on the left above the message) to set the
parameter values of the Oracle BPEL Console reports portlets or change the
default settings for Oracle BPEL Worklist Application portlets.
2.
See the following section based on your portlet selection in Step 1.
If You Selected...
Go to Section...
Instance State
"Defining Oracle BPEL Console Report Portlet Parameters
and Accessing Portlet Data Sources" on page 20-9
Instance Execution Time
Performance
Activity Sensor
Fault Sensor
20-8
Oracle BPEL Process Manager Developer’s Guide
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
If You Selected...
Go to Section...
BPEL Worklist Portlet
"Defining Oracle BPEL Worklist Application Portlet
Parameters and Accessing Portlet Data Sources" on
page 20-12
Defining Oracle BPEL Console Report Portlet Parameters and Accessing Portlet Data
Sources
Report portlets provide access to Oracle BPEL Console reports that describe the
behavior of the instances of a selected BPEL process.
Each of the report portlets must be associated with a specific time period. Table 20–1
describes the parameter values to specify for each report type. This window provides a
method for specifying the same parameter values across all report type portlets in a
given page.
1.
Enter the following parameter values.
Table 20–1
Oracle BPEL Console Report Portlet Parameters
Parameter
Description
Title
Enter a report title name or accept the default name. The title that
appears by default is based upon the type of report you selected
in Step 1 on page 20-8.
Domain
Select the domain in which the BPEL process is deployed.
Business Process
Select the BPEL process for which to create reports of its instances.
Time Interval
Select Daily, Hourly, or Weekly as the time interval for
generating data.
End Date
Enter the date at which to stop generating report data.
End Hour
Enter the time at which to stop generating report data.
Number of Time Intervals Enter the time period for creating reports. This is the number of
days, weeks, or hours (according to the Time Interval list
selection) starting from the end date going backwards in time to
determine the start date.
For example, if you enter 7/29/05 as the end date, 22:00 as the end hour, Weekly as
the time interval, and 3 as the number of time intervals, the report is created for
the three weeks between 7/08/05 at 10 PM and 7/29/05 at 10 PM.
2.
Click Apply to apply your values and click OK to create portlet data.
3.
See the following sections based on the portlet type you selected:
Oracle BPEL Portlets 20-9
Portlet
See Section...
Instance State
"Instance State" on page 20-10
Instance Execution Time
"Instance Execution Time" on page 20-10
Performance
"Performance" on page 20-11
Activity Sensor
"Activity Sensor" on page 20-12
Fault Sensor
"Fault Sensor" on page 20-12
Instance State
The instance state report portlet shown in Figure 20–2 provides details about the
number of faulted, completed, and currently running instances of the BPEL process for
the selected time period.
Figure 20–2
Instance State Report
Note: You can edit parameter settings by clicking the Edit icon (first
icon on the left above the portlet title bar).
Instance Execution Time
The instance execution time report portlet shown in Figure 20–3 provides details about
the maximum, minimum, and average execution times aggregated across all closed
instances of the business process during the selected time period.
20-10 Oracle BPEL Process Manager Developer’s Guide
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
Figure 20–3
Instance Execution Time Report
Performance
The performance report portlet shown in Figure 20–4 provides aggregated information
about the percentage of BPEL process instances that meet the service level agreement
(SLA) value associated with a specific BPEL process.
Figure 20–4
Performance Report
See "Creating Performance Reports" on page 21-5 for a description of the SLA
parameter and how to set it.
Oracle BPEL Portlets 20-11
Activity Sensor
The activity sensor report portlet shown in Figure 20–5 provides details about the
activity sensors associated with the BPEL process over a selected time period. This
enables you to analyze activity trends. Activity sensor reports show the activity name,
sensor name, activity type, aggregated values of the minimum, maximum, and
average execution time of the activity, and the number of occurrences of the activity.
This report shows activity information only if activity sensors are defined for the BPEL
process.
Figure 20–5
Activity Sensor Portlet
Fault Sensor
The fault sensor report portal shown in Figure 20–6 provides details about the data
collected by fault sensors associated with a specific BPEL process over the specified
time period. This enables you to analyze trends in faults. The report shows the date
and time of the fault occurrence, the fault message, the activity in which the fault
occurred, and a link to the faulted instance. This report shows activity information
only if fault sensors are defined for the BPEL process. For this example, no fault sensor
data was found.
Figure 20–6
Fault Sensor Reports
Defining Oracle BPEL Worklist Application Portlet Parameters and Accessing Portlet
Data Sources
These portlets integrate Oracle BPEL Worklist Application with OracleAS Portal. There
are two types of portlets:
■
Listing portlet
■
Analysis portlet
Details about the parameter values to specify for these portlets are provided below.
See Also: Chapter 17, "Worklist Application" for additional details
about Oracle BPEL Worklist Application
20-12 Oracle BPEL Process Manager Developer’s Guide
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
Listing Portlet Customization
The listing portlet displays a list of tasks that satisfy the data filtering criterion. This
portlet provides considerable flexibility in terms of which tasks to display and how to
display them.
Figure 20–7
BPEL Worklist Portlet Filter and Display Customization Options
The listing portlet exposes two portlet parameters: Task Category and Task Status.
The values for these can be set from the page. If no value is set, then the default values
of My & Group and Any are used. Figure 20–8 on page 20-14 shows the Page
Parameter Properties page where these default values are set. See "Step 5: Mapping
Portlet Parameters with Page Parameters" on page 20-19 for instructions on editing
this page.
Oracle BPEL Portlets 20-13
Figure 20–8
Page Parameter Properties
The portlet task filter and display customization options shown in Figure 20–7 on
page 20-13 are described in Table 20–2. The first part provides data filter customization
options and the second part provides display customization options.
1.
Enter the following parameter values.
Table 20–2
BPEL Worklist Portlet Task Filter and Display Customization Options
Parameter
Description
Task Filter Customization
■
Category
Select one of the following:
■
■
■
■
■
My & Group—tasks assigned to the user and the groups to
which the logged-in user belongs
Reportees—tasks assigned to the users who report to the
logged-in user
Owner—tasks that are owned by the logged-in user by way
of process ownership
Creator—tasks that were created or initiated by the
logged-in user
Previous—tasks that the logged-in user has updated
■
Status
Select the status state: Assigned, Completed, Errored, Expired,
Withdrawn, Suspended, and Any.
■
Created
Select the previous x days: (leave blank (that is, no restriction), 1
day, 7 days, 14 days, and 30 days).
■
Expiration
Select the next x days: (leave blank (that is, no restriction), 1 day,
7 days, 14 days, and 30 days).
■
Priority
Select from Any or 1 through 5, where 1 is the highest priority.
20-14 Oracle BPEL Process Manager Developer’s Guide
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
Table 20–2
(Cont.) BPEL Worklist Portlet Task Filter and Display Customization Options
Parameter
■
Business Process
Description
Select one of the deployed business processes or Any.
Display Customization
■
Title
Select the portlet title.
■
Layout
Select the size of the portlet as a ratio of the maximum size
(Small, Medium, Large, or Full).
■
Show Header/Footer
Set this flag to Yes (default option) if the header (category and
user name) and footer (page generation time) are to be
displayed.
Column Layout
(Columns 1 through 8)
Select the columns to display and the order in which to display
them. There can be up to eight columns: Title, Number,
Assignee, Status, Priority, Expiration, Last Modified, Created,
Conclusion, Last Modifier, Creator, Acquirer, Task Key, and
Business Process. Note that the first column is always Title.
■
Sort Column
Select the order in which to sort and display the following
columns: Title, Number, Priority, Expiration, Conclusion, Last
Modified, and Last Modifier.
■
Sort Order
Select Ascending or Descending.
■
Page Size
Select 5, 10, 20, or 50
■
Locale Source
Select the locale for the portlet based on the specified source:
Portlet (resolved from the browser and set language portlet) or
Directory Service.
■
Style Source
Select the style (background color, font color, and font style) for
the portlet based on the specified source: Portlet (based on page
style used in the portal page) or Default (Oracle BPEL Console
or Oracle BPEL Worklist Application style).
2.
Click Apply to apply your values and click OK to create portlet data.
■
Listing Portlet View
Figure 20–9 shows the task listing portlet. The category of tasks and the current user
name displays at the top. The table displays the columns chosen in the Display
Customization options described in Table 20–2. The actual set of tasks that display
depends on the Task Filter Customization options chosen in Table 20–2. The title
column contains a link for clicking down into the worklist application for the task
details. Paging information and the last page refreshed time are displayed at the
bottom.
Figure 20–9
Worklist Portlet View
Oracle BPEL Portlets 20-15
Figure 20–10 shows the worklist application that you access by clicking a task entry
under the Title column in Figure 20–9 on page 20-15. The worklist application
recognizes that the user is clicking down from the portlet and sets the header
information and home link accordingly. The search option is skipped and the home
link points back to the portal page. All other behavior is the same as if the user had
logged into the worklist application.
Figure 20–10
Accessing the Worklist Application
Analysis Portlet Customization
Figure 20–11 shows the analysis listing portlet. The analysis portlet provides a status
breakdown chart based on the category of tasks chosen and other filter options. It also
provides the ability to group the results based on the assignee, business process, or the
creator of tasks. The Listing Portlet exposes a portlet parameter for Task Category. The
value for this can be set from the page. If no value is set, then the default value of My
& Group is used. Figure 20–8 on page 20-14 shows the Page Parameter Properties
page where this default value is set. See "Step 5: Mapping Portlet Parameters with
Page Parameters" on page 20-19 for instructions on editing this page.
20-16 Oracle BPEL Process Manager Developer’s Guide
Step 4: Defining Portlet Parameters and Accessing Portlet Data Sources
Figure 20–11
BPEL Worklist Analysis Portlet Filter and Display Customization Options
Table 20–3 shows the analysis portlet task filter and display customization options.
The first part provides data filter customization options and the second part provides
display customization options.
1.
Enter the following parameter values.
Table 20–3
BPEL Worklist Analysis Portlet Filter and Display Customization Options
Parameter
Description
Task Filter Customization
■
Category
Select one of the following:
■
■
■
■
■
■
Created
My & Group—tasks assigned to the user and the groups to
which the logged-in user belongs
Reportees—tasks assigned to the users who report to the
logged-in user
Owner—tasks that are owned by the logged-in user by way
of process ownership
Creator—tasks that were created or initiated by the
logged-in user
Previous—tasks that the logged-in user has updated
Select the previous x days: (leave blank (that is, no restriction), 1
day, 7 days, 14 days, and 30 days).
Oracle BPEL Portlets 20-17
Table 20–3
(Cont.) BPEL Worklist Analysis Portlet Filter and Display Customization
Parameter
Description
■
Expiration
Select the next x days: (leave blank (that is, no restriction), 1 day,
7 days, 14 days, and 30 days).
■
Priority
Select from Any or 1 through 5, where 1 is the highest priority.
■
Business Process
Select one of the deployed business processes or Any.
Display Customization
■
Title
Select the portlet title.
■
Layout
Select the size of the portlet as a ratio of the maximum size
(Small, Medium, Large, or Full).
■
Show Header/Footer
Set this flag to Yes (default option) if the header (category and
user name) and footer (page generation time) are to be
displayed.
Show Statuses with
Zero Count
Select Yes to compact the portlet by skipping statuses for which
there are no qualifying tasks
Group By
Select to group by Assignee, Business Process, Creator, or All
(status summary of all tasks).
Show options for
various statuses
Select only those statuses you want to see: Assigned,
Completed, Expired, Errored, Suspended, Withdrawn, and
Requested.
■
Locale Source
Select the locale for the portlet based on the specified source:
Portlet (resolved from the browser and set language portlet) or
Directory Service.
■
Style Source
Select the style (background color, font color, and font style) for
the portlet based on the specified source: Portlet (based on page
style used in the portal page) or Default (Oracle BPEL Console
or Oracle BPEL Worklist Application style).
2.
Click OK.
■
■
■
Analysis Portlet View
Figure 20–12 shows the analysis portlet. The category of tasks and the current user
name display at the top. The table displays the group by column, the corresponding
statuses, and count. If there are multiple assignees (reportee category, for example), the
status breakdown is repeated for each assignee. If the business process is chosen as the
Group By column, the status breakdown is repeated for each deployed business
process. The last page refreshed time displays at the bottom.
20-18 Oracle BPEL Process Manager Developer’s Guide
Step 5: Mapping Portlet Parameters with Page Parameters
Figure 20–12
Analysis Portlet View
Step 5: Mapping Portlet Parameters with Page Parameters
Time-related properties of the portlets are also exposed as parameters and can be
mapped to page parameters. This enables you to override the parameter values you
set:
■
■
1.
In Step 1 on page 20-9 of "Defining Oracle BPEL Console Report Portlet
Parameters and Accessing Portlet Data Sources"
In Step 1 on page 20-14 of "Listing Portlet Customization" and Step 1 on page 20-17
of "Analysis Portlet Customization"
Click Page: Properties at the top of a report portlet. For this example, the Instance
State report of the Oracle BPEL Console reports portlets is shown.
Oracle BPEL Portlets 20-19
The Edit page appears.
2.
Click the Parameters tab.
a.
If the Parameters tab does not display, return to the portlet reports page
shown in Step 1 on page 20-19 to enable it.
b.
Click Page Group: Properties at the top of the report portlet.
c.
Click the Configure tab.
The Edit Page Group page appears.
d.
Click Edit in the Parameters and Events section.
e.
Select Enable Parameters and Events.
f.
Click OK.
g.
Return to the Edit page shown in Step 1 on page 20-19.
h.
Click the Page: Properties tab.
i.
Click the Parameters tab on the Edit page.
20-20 Oracle BPEL Process Manager Developer’s Guide
Step 5: Mapping Portlet Parameters with Page Parameters
3.
Add the page parameters and map the page parameters to the portlet parameters.
■
■
For Oracle BPEL Console reports portlets, the following page parameter
properties are available:
For Oracle BPEL Worklist Application portlets, the following page parameter
properties are available:
Oracle BPEL Portlets 20-21
When you save these changes, the portlet picks up the property values from the
page parameters instead of the ones set during the edit process.
Summary
This chapter describes how to deploy the Oracle BPEL Portlets and configure
OracleAS Portal to provide access to data from these portlets.
20-22 Oracle BPEL Process Manager Developer’s Guide
21
Oracle BPEL Console Reports
This chapter provides an overview of Oracle BPEL Console reports. It provides
descriptions of the types of reports you can create, how to create them, and how to
analyze the results.
This chapter contains the following topics:
■
Creating Oracle BPEL Console Reports
■
Summary
Creating Oracle BPEL Console Reports
You can create reports in Oracle BPEL Console 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
Perform the following steps to create reports. The examples shown in this section
describe how to create reports for the LoanFlowPlus sample BPEL process that is
available under the Oracle_
Home\integration\orabpel\samples\demos\LoanDemoPlus\LoanFlowPlus
directory. To automatically build this sample in JDeveloper BPEL Designer, create a
workspace with an empty project and click the LoanFlowPlus.jpr file in the
LoanFlowPlus directory.
1.
Click a specific process to create reports for all its instances in the Deployed BPEL
Processes column of the Dashboard tab of Oracle BPEL Console (for this example,
LoanFlowPlus is selected).
The Initiate tab appears by default.
Oracle BPEL Console Reports 21-1
Creating Oracle BPEL Console Reports
2.
Enter specific details to initiate an instance and click Post XML Message.
3.
Click Reports on the BPEL Processes tab.
The Reports tab appears:
This page enables you to generate several report types. The fields to complete in
order to create reports are described in the following table:
Page Element
Location in Page Description
Report Type list
upper right
Select the type of report to create:
■
Process
■
Performance
■
Activity Sensor
■
Fault Sensor
■
Process Time Distribution
Descriptions of these report types are provided in the
sections that follow.
End Date field
upper left
Enter the date at which to stop generating report data.
End Hour list
upper left
Select the hour at which to stop generating report data.
Time Interval list
upper middle
Select Daily, Hourly, or Weekly as the time interval for
generating data.
Number of Time
Intervals field
upper middle
Enter the time period for creating reports. This is the
number of days, weeks, or hours (according to the
Time Interval list selection) starting from the end date
going backwards in time to determine the start date.
Go button
upper middle
Click to create the selected report type.
For example, if you enter 7/29/05 as the end date, 22:00 as the end hour, Weekly as
the time interval, and 3 as the number of time intervals, the report is created for
the three weeks between 7/08/05 at 10 PM and 7/29/05 at 10 PM.
4.
See the following sections for details about creating the available report types:
■
21-2
Creating Process Reports
Oracle BPEL Process Manager Quick Start Guide
Creating Oracle BPEL Console Reports
■
Creating Performance Reports
■
Creating Activity Sensor Reports
■
Creating Fault Sensor Reports
■
Creating Process Time Distribution Reports
Notes:
■
■
After creating any report type, you can save the report details to a
comma-separated value (CSV) file by selecting Export to CSV.
You can then review these reports in Microsoft Excel.
You can also execute and view Oracle BPEL Console reports from
Oracle Application Server Portal. See Chapter 20, "Oracle BPEL
Portlets" for instructions.
Creating Process Reports
Process reports display data on the state of selected BPEL process instances and
execution times of these instances. The data is grouped along the time line (X-Axis)
into the number of time intervals based on the specified query criteria.
1.
Select Process from the Report Type list.
2.
Enter appropriate time period query details as described in the table in Step 3 on
page 21-2 and click Go.
The report results appear:
3.
Review the Instance State section of the process report (the left side).
The graph shows the number of BPEL process instances initiated, faulted,
successfully completed, and currently running. For this example, which uses the
LoanFlowPlus sample BPEL process, the graph shows how many loans were
Oracle BPEL Console Reports 21-3
Creating Oracle BPEL Console Reports
requested (initiated), how many stopped abnormally due to faults in the system,
how many were successfully processed, and how many are still pending.
4.
Hold your cursor over a specific bar to display information. For this example, the
information that displays identifies the series as faulted instances, the group (date)
in which this information was gathered as 7/28/05, and the value (number) of
faulted instances as four.
5.
Click this bar to display the list of instances that faulted.
This displays the list of four faulted instances on the Instances tab.
6.
Click a specific instance from the list to debug.
You can then debug the instance and take appropriate corrective actions.
7.
Return to the process report results shown in Step 2 on page 21-3.
8.
Review the Instance Execution Time section of the process report (the right side).
This graph shows the maximum, minimum, and average execution times
aggregated across all closed instances of the business process during the selected
time interval. By default, process reports display all successfully and
unsuccessfully completed processes (known as All Closed).
9.
21-4
If you want to display only successfully completed (known as Closed
Successfully) or unsuccessfully completed (known as Faulted) process instances,
make an appropriate selection from the View Execution Time for list above the
graph.
Oracle BPEL Process Manager Quick Start Guide
Creating Oracle BPEL Console Reports
10. Click one of the minimum or maximum data points in the graph to show
additional details. For example, click the maximum execution time to view
information about the instance that took the longest amount of time to execute.
This displays the Instances tab for this instance.
11. Click the specific instance in the list.
You can then debug the instance and take appropriate corrective actions.
Creating Performance Reports
Performance reports display the percentage of BPEL process instances that meet the
Completion Time SLA field value. This enables you to identify bottlenecks in instance
performance. You assign this value to the SLACompletionTime parameter in the
Configurations tab of the Deployment Descriptor Properties window in JDeveloper
BPEL Designer. You specify an SLACompletionTime parameter value using the P0YT
format. P0YT conforms to the PnYnMnDTnHnMnS convention, where:
Oracle BPEL Console Reports 21-5
Creating Oracle BPEL Console Reports
■
■
T is the date and time separator
nY, nM, nD, nH, nM, and nS correspond to the number of years, months, days,
hours, minutes, and seconds, respectively
For example, P0YT1.5S corresponds to 0 years, 1.5 seconds. The letter P and at least
one unit of time must always be present.
If you define the completion time service level agreement (SLA) value for the
LoanFlowPlus process as P0YT450S seconds (450 seconds), the report graph shows the
percentage of instances that completed and did not complete within that time period.
This assignment adds this parameter to the bpel.xml file.
<configurations>
<property name="SLACompletionTime">P0YT450S</property>
</configurations>
1.
Select Performance from the Report Type list.
2.
Enter appropriate time period query details as described in the table in Step 3 on
page 21-2 and click Go.
The report results appear:
This graph shows the percentage of instances that completed and did not complete
within this time period.
3.
21-6
Hold your cursor over a specific bar to display information. For this example, the
information that displays below identifies the series of instances that satisfied the
SLACompletionTime parameter value, the group (date) in which this information
was gathered as 7/29/05, and information about the percentage and number of
successfully completed instances and total number of instances for that day.
Oracle BPEL Process Manager Quick Start Guide
Creating Oracle BPEL Console Reports
4.
Click a specific bar to display the Instances tab. For example, click the red bar for
instances that did not satisfy the SLA value. Holding your cursor over this bar
before clicking displays specific information about these instances.
5.
Click the specific instance in the list.
You can then debug the instance and take appropriate corrective actions.
6.
If you want to override the SLACompletionTime parameter value in the
bpel.xml file, change the value in the Completion Time SLA field above the
graph and click Go to re-execute the report.
The report results display details based on the new parameter value entered. Note
that a Default link now displays to the right of the value you entered in Step 6.
7.
Click Default to re-execute the report with the initial SLACompletionTime
parameter value set during design time in the Configurations tab of the
Deployment Descriptor Properties window.
See Also: Appendix E, "Deployment Descriptor Properties"
Creating Activity Sensor Reports
Activity sensor reports show data for the activity sensors associated with the selected
BPEL process over a specified time span. This enables you to analyze activity trends.
Activity sensor reports show the activity name, sensor name, activity type, aggregated
values of the minimum, maximum, and average execution time of the activity, and the
number of occurrences of the activity. This report shows activity execution time only if
activity sensors are defined for the BPEL process.
1.
Select Activity Sensor from the Report Type list.
2.
Enter appropriate time period query details as described in the table in Step 3 on
page 21-2.
3.
Make a selection from the Activity Sensor list. Only activities with sensors display
in this list.
■
Select All to create a report for all activities in the BPEL process.
Oracle BPEL Console Reports 21-7
Creating Oracle BPEL Console Reports
■
4.
Select a specific activity for which to create a report.
Click Go.
The report results appear (for this example, All was selected from the Activity
Sensor list):
5.
Click Show Details on the far left side to view additional information about an
activity sensor.
This displays details about all the variables associated with that activity sensor. It
also shows a graph for the minimum, maximum, and average execution times, as
collected by the chosen activity sensor over the selected time span.
6.
21-8
Click the variable name in the Variable Name column (for this example, named
input) to display the detailed values of the variable collected during the selected
time period.
Oracle BPEL Process Manager Quick Start Guide
Creating Oracle BPEL Console Reports
7.
Click a specific instance ID on the Variable Details window to display the Flow
diagram of that instance.
You can then debug the instance and take appropriate corrective actions.
Creating Fault Sensor Reports
Fault sensor reports show the data collected by fault sensors over a specified time
interval. This enables you to analyze trends in faults while processing loan
applications. The report shows the date and time of the fault occurrence, the activity in
which the fault occurred, and a link to the faulted instance. For this example, the
LoanFlowPlus sample BPEL process is used. There are two types of faults for which
data is provided in this sample:
■
Bankruptcy reports — the fault occurs when the customer has a negative credit
rating
■
The social security number of the customer requesting the loan was not found
1.
Select Fault Sensor from the Report Type list.
2.
Enter appropriate time period query details as described in the table in Step 3 on
page 21-2 and click Go.
The report results display the types of fault messages.
Oracle BPEL Console Reports 21-9
Creating Oracle BPEL Console Reports
3.
Click a specific instance ID in the Instance ID column to display the Flow diagram
for the activity of the instance that faulted.
4.
Debug the activity and take appropriate corrective actions.
Creating Process Time Distribution Reports
Process time distribution reports enable you to view the distribution of execution
times across the activities of BPEL process instances. For example, you may have two
activities, one for each loan application company returning a loan offer. You can see
which activity is taking the longest amount of time to process the loan offer. You do not
need to create sensors in activities to use this report. This report enables you to
identify which activities are taking the most time to process.
1.
Select Process Time Distribution from the Report Type list.
21-10 Oracle BPEL Process Manager Quick Start Guide
Summary
2.
Enter appropriate time period query details as described in the table in Step 3 on
page 21-2 and click Go.
The report results appear:
3.
Note which activities take the longest to complete.
4.
Debug the activity and take appropriate corrective actions.
Summary
This chapter provides an overview of Oracle BPEL Console reports. It provides
descriptions of the types of reports you can create, how to create them, and how to
analyze the results.
Oracle BPEL Console Reports
21-11
Summary
21-12 Oracle BPEL Process Manager Quick Start Guide
Part V
Reference Information
This part provides reference details about troubleshooting issues, activities,
deployment descriptor properties, demo user communities, XPath extension functions,
and Oracle Workflow integration.
This part contains the following appendices:
■
Appendix A, "Troubleshooting and Workarounds"
■
Appendix B, "Workflow and Notification Reference"
■
Appendix C, "JDeveloper BPEL Designer Activities"
■
Appendix D, "User Task 2.0 Macro"
■
Appendix E, "Deployment Descriptor Properties"
■
Appendix F, "Demo User Community"
■
Appendix G, "XPath Extension Functions"
■
Appendix H, "Oracle BPEL Process Manager and Oracle Workflow Integration"
A
Troubleshooting and Workarounds
This appendix describes Oracle BPEL Process Manager troubleshooting methods.
This appendix contains the following topics:
■
Troubleshooting General Issues
■
Troubleshooting Sensors—The Custom Data Publisher
■
Troubleshooting Oracle BPEL Worklist Application
■
Summary
Troubleshooting General Issues
The following sections describe possible issues and solutions.
Correcting Validation Errors in Complex Processes
If you have complex processes with validation errors (for example, assign activities
with multiple copy rules that are embedded inside several scopes), the recommended
method for accessing and correcting these errors is as follows:
1.
Right-click the error and select Go to Source to access the source code that errored.
2.
Review the source code to identify the error.
3.
Click Diagram View and go to the graphical view of the error.
4.
Make corrections in the graphical view.
Handling Long-Running Processes
When a process has long-standing activity and the server time-out value is set to less
than the time that has elapsed since the previous dehydration point has been reached,
you can see exception messages similar to the following in the Oracle BPEL Server
window.
Message handle error.
An exception occurred while attempting to process the message
"com.collaxa.cube.engine.dispatch.message.invoke.InvokeIns
tanceMessage"; the exception is: Transaction was rolled back: timed out;
nested exception is: java.rmi.RemoteException:
No Exception - originate from:java.lang.Exception: No Exception - originate
from:; nested exception is:
java.lang.Exception: No Exception - originate from:
Troubleshooting and Workarounds A-1
Troubleshooting Sensors—The Custom Data Publisher
As a workaround, increase the transaction-config timeout value in the
Oracle_
Home\integration\orabpel\system\appserver\oc4j\j2ee\home\server.
xml file.
<transaction-config timeout="30000"/>
Oracle Application Server Integration Installation Guide for a detailed description on
setting this parameter.
Creating an Empty BPEL Process and Importing a Schema
If you create an empty project (which is common with adapter endpoint projects) and
import an XSD file, you cannot deploy the project without editing the project_
name.bpel file.
As a workaround, perform the following steps:
1.
Create an asynchronous project.
2.
Leave the client partner link alone (it enables you to import XSDs because it refers
to the process_name.wsdl file that has the necessary imports).
3.
Edit the receiveInput receive activity of the client partner link and have it point to
the new adapter inbound endpoint in the Partner Link field.
Troubleshooting Sensors—The Custom Data Publisher
The following sections describe possible issues and solutions.
Poor JMS Performance When Creating or Destroying Connections
Problem
Due to a bug, you can experience poor JMS performance when creating or destroying
connections. This can cause a slowdown in the execution of BPEL processes that have
JMS data publishers associated with them.
Solution
Use the rollup patch included on the software CD. See the readme file.
Data Publisher Is Not Working
Problem
The custom data publisher is not working.
Solution
■
Make sure that the class file has been generated and that it is in the system
classpath. See the obsetenv.bat file for this definition, or the BPEL suitcase.
■
■
Ensure that you have implemented the data publisher interface.
If you compile your data publisher into the system classpath, then you must
restart Oracle BPEL Process Manager. You may have made changes to the data
publisher without restarting Oracle BPEL Process Manager.
A-2 Oracle BPEL Process Manager Developer’s Guide
Troubleshooting Sensors—The Custom Data Publisher
■
It is possible that an exception is being thrown in your data publisher. Check the
log file for any exceptions, or temporarily add a try/catch block around all your
code. In the catch, print the stack trace. These messages display on the text
window that opens when you start Oracle BPEL Process Manager.
Data Publisher Works, But Business Process Runs Slowly
Problem
The data publisher works fine, but the business process runs very slowly.
Solution
There are a couple of options.
First, you can attempt to profile your code. The do-user-sensor-callback statistic in
Oracle BPEL Console records how much time is spent publishing sensor data.
Second, you can switch from a custom data publisher to a JMS Publisher. Then, you
can deploy a message-driven bean to the application server to publish data whenever
data is sent to that particular JMS destination. This decouples data publishing from
process execution.
Caching Data in the Data Publisher Is Not Supported
Problem
To improve performance, I want to cache data in my data publisher. Is this supported?
Solution
This is not supported. Data publishers must be stateless.
Unexpected Errors in the Data Publisher
Problem
My data publisher works fine most of the time, but sometimes I get a weird error.
It is possible that your data publisher is experiencing concurrency issues.
Solution
Data publishers must be coded in a thread-safe manner. This means that the Java code
must be thread safe as well as the utilization of resources, such as databases or files.
Data Extracted to XML Is Difficult to Work With
Problem
The data I extract is complex XML. It is difficult to work with. Can I do anything to
make it simpler?
Solution
While the W3C DOM model is somewhat cumbersome, there are third-party models
(such as DOM4J) that make things easier. It is easy to create a DOM4J object from its
corresponding W3C DOM object. Another option is to generate JAX-B objects or
Troubleshooting and Workarounds A-3
Troubleshooting Oracle BPEL Worklist Application
schema objects for the data you extract. Then you can use the generated Java classes to
manipulate data more easily.
Troubleshooting Oracle BPEL Worklist Application
The following sections describe possible issues and solutions.
Not Able to Log In to the Worklist Application
You cannot log in to the Worklist Application if your information is not available in the
identity service. Check with an administrator to verify that your user information is
present in the identity system (a file based on LDAP, such as Oracle Internet
Directory).
Information Is Displayed in a Different Language
The Worklist Application gets a user’s language (locale) preferences from the identity
service and displays the information in that locale. If information is displayed in the
wrong language, make sure that the user’s preference is set to a supported locale. See
"Accessing the Worklist Application in Local Languages" on page 17-33 for more
information.
Dates and Times Are Displayed Incorrectly
The Worklist Application gets a user’s timezone preference from the identity service
and displays the information in this timezone. Also, the date and time is formatted to
suit the language (locale) preference. Make sure that these preferences are correctly
specified in the identity service. See "Identity Service" on page 16-77 for more
information.
The User Is Not Permitted to Perform an Action
You may see an error message that says something like:
"User jcooper is not permitted to perform the action Update on task Loan
application for John with id...."
Check if the user has permission to perform the action or if the action can be
performed on the task in its current state. You can also check for the following:
■
■
The task expired between the time the user loaded the page and actually
performed the action.
The task was updated by another user (such as a manager, owner, or admin)
between the time the user loaded the page and actually performed the action.
Expected Task Is Not Listed Under Task Titles
On the Worklist Application home page, under the Title column, if you do not see a
task listed that you expected to see, then it may have been modified by another user or
by the system.
Another user, such as a manager or group member, may have modified the task by
performing any of the following actions:
■
Complete
■
Suspend
A-4 Oracle BPEL Process Manager Developer’s Guide
Summary
■
Request More Information
Also, the filer of the task may have withdrawn (cancelled) the task.
The system can modify a task in the following situations:
■
If the process instance associated with a task was purged or archived, the task is
also purged or archived and may not be accessible.
■
If a task expires
■
If a task encounters a system error such as an incorrect assignee
In most of the preceding cases, you can view the task by changing the filters to a
broader category (such as Any or All).
Summary
This appendix describes Oracle BPEL Process Manager troubleshooting methods.
Troubleshooting and Workarounds A-5
Summary
A-6 Oracle BPEL Process Manager Developer’s Guide
B
Workflow and Notification Reference
This appendix describes operations that can be invoked from a BPEL business process.
This appendix contains the following topics:
■
Task Manager Service WSDL Operations
■
Task Routing Service WSDL Operations
■
Notification WSDL Operations
■
Identify Service Operations
■
Task Action Handler Business Process
■
Summary
Task Manager Service WSDL Operations
The task manager service exposes operations that can be invoked from the BPEL
business process to orchestrate the workflow. The task manager service also provides
state management and persistency for the tasks. The task manager service exposes the
following operations. All the operations are exposed on the WSDL port type
TaskManager.
■
initiateTask—initiates a task by persisting the task in the database
■
reinitiateTask—reinitiates a task to continue an existing task
■
updateTask—updates the task
■
renewTask—renews the task with a specified duration
■
notifyTaskExpiration—notifies the task manager service that the task is
expired. This operation is invoked from the task action handler business process,
which manages the expiration of the task.
■
initiateSubTask—initiates a subtask in a parallel workflow pattern
■
completeTask—completes the task with a specified conclusion
■
■
■
sendTaskReminder—notifies the task manager service to send a reminder for
the task. This operation is invoked from the task action handler business process,
which manages task reminders.
releaseTask—releases a previously acquired task
errorTask—notifies the task manager service that the task is in an errored state
and that the task should be marked as errored
The WSDL for TaskManagerService is available at
Workflow and Notification Reference B-1
Task Routing Service WSDL Operations
http://hostname:port/orabpel/xmllib/workflow/TaskManagerService.wsdl
The XSD used by TaskManagerService is available at
http://hostname:port/orabpel/xmllib/workflow/WorkflowTask.xsd
Task Routing Service WSDL Operations
The task routing service exposes operations that can be invoked from the BPEL
business process to perform task routing operations. The task manager service exposes
the following operations. All the operations are exposed on the WSDL port type
TaskRoutingService.
■
■
■
■
routeTask—routes the task to a specified participant
routeTaskToNextApprover—routes the task to the next approver as
determined by evaluating the approver function
escalateTask—escalates the task to the manager
escalateTaskOnExpiration—escalates the task when the task is expired. The
operation also renews the task by a specified duration.
The WSDL for TaskRoutingService is available at
http://hostname:port/orabpel/default/TaskActionHandler/TaskRoutingService.wsdl
The XSD for the service is available at
http://hostname:port/orabpel/xmllib/workflow/TaskRoutingService.xsd
Notification WSDL Operations
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. The notification service exposes the following
operations on the WSDL port type NotificationService.
■
sendVoiceNotification—sends an instance messenger notification
■
sendSMSNotification—sends an instance messenger notification
■
sendEmailNotification—sends an e-mail notification
■
■
sendNotificationToUser—sends a notification to a user. The notification
channel used is determined by the orclWorkflowNotificationPref attribute
in Oracle Internet Directory (OID) or JAZN-XML. If no preference is specified,
then e-mail is used. The input message to this operation contains two parts—the
group ID and the generic notification payload. The generic payload contains a
common payload that applies to all the channels and a payload for each of the
channels. The message that is actually sent is evaluated from the generic payload.
sendNotificationToGroup—sends a notification to a group using the e-mail
channel. If the group does not have an e-mail address associated with it, then the
notification is sent to each member of the group using their preferred notification
channel. The input message to this operation contains two parts—the group ID
and the generic notification payload. The generic payload contains a common
payload that applies to all the channels and a payload for each of the channels.
The message that is actually sent is evaluated from the generic payload.
B-2 Oracle BPEL Process Manager Developer’s Guide
Summary
Identify Service Operations
The identity service exposes the following operations that can be invoked from the
BPEL business process. All the operations are exposed on the WSDL port type
IdentityService.
■
■
getManager—gets the manager of a user, which can also be obtained using the
ora:getManager() XPath extension function.
getManagementChain—gets the management chain based on the input message
The WSDL for the IdentityService is available at
http://hostname:port/orabpel/xmllib/workflow/LocalIdentityService.wsdl
The XSD for the service is available at
http://hostname:port/orabpel/xmllib/workflow/LocalIdentityService.xsd
Task Action Handler Business Process
The task action handler business process receives updates from Oracle BPEL Worklist
Application through the task manager service or the task routing service. The main
task of the process is to keep the task synchronized in the BPEL process with its
database state. Based on the state of the task, the process determines if the parent BPEL
process should be called back with the task. An instance of the task action handler
process is created for each participant for a given task. Participants who participate in
the task when the current participant performs operations like reassign, escalate, and
so on reuse the same process.
In addition, the task action handler process manages the following timer events:
■
Task expiration
■
Reminder durations for the task
■
Task release durations when the task is acquired
Summary
This appendix describes workflow and notification service WSDL operations.
Workflow and Notification Reference B-3
Summary
B-4 Oracle BPEL Process Manager Developer’s Guide
C
JDeveloper BPEL Designer Activities
This appendix describes the activities available for use when designing a BPEL process
in JDeveloper BPEL Designer.
This appendix contains the following topics:
■
Validating when Loading a Process Diagram
■
Activities Overview
■
Summary
Validating when Loading a Process Diagram
As you create and open activities such as scope, assign, and others for the first time in
JDeveloper BPEL Designer, the message Invalid Settings appears at the top of
the activity window. This is because you have not yet entered details. If the Validate
process when loading diagram option is selected, the message always appears. You
can ignore this message. As you enter and correctly apply your details, the message
disappears.
To turn this option off for the current project, perform the following steps:
1.
Right-click in the JDeveloper BPEL Designer Diagram View and select Diagram
Properties.
2.
Deselect the Validate process when loading diagram option on the Diagram
Properties window.
3.
Click OK.
4.
Select Save All from the File main menu.
To disable this message for all new projects going forward, perform the following
steps:
1.
Select Preferences > BPEL Editor from the Tools main menu in JDeveloper BPEL
Designer.
2.
Deselect the Validate process when loading diagram option.
3.
Click OK.
Any projects created after this point do not display the Invalid Settings
message.
JDeveloper BPEL Designer Activities C-1
Activities Overview
Activities Overview
JDeveloper BPEL Designer includes a series of activities that are available for dragging
and dropping into a BPEL process. These activities enable you to perform specific
tasks within a process. This section provides a brief overview of these activities and
provides references to other documentation that describes how to use these activities:
This section contains the following topics:
■
Assign Activity
■
Catch Activity
■
Compensate Activity
■
Empty Activity
■
Flow Activity
■
FlowN Activity
■
Invoke Activity
■
Java Embedding Activity
■
Notification Activity
■
PartnerLink Activity
■
Pick Activity
■
Receive Activity
■
Reply Activity
■
Scope Activity
■
Sequence Activity
■
Switch Activity
■
Terminate Activity
■
Throw Activity
■
Transform Activity
■
User Task
■
Wait Activity
■
While Activity
See Also: The following documentation for additional details about
activities:
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Business Process Execution Language for Web Services Specification
■
The contents of the c:\Oracle_
Home\integration\orabpel\samples\references
directory
C-2 Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Tabs Common to Many Activities
While each activity performs specific tasks, many activities include tabs that enable
you to perform similar tasks. This section describes these common tabs.
■
■
■
■
The Sensors tab displays on all activities and enables you to create sensors for
capturing details about an activity.
The Correlation Sets tab displays in invoke, receive, and reply activities, the
onMessage branch of pick activities, and the OnMessage variant of event handlers.
Correlation sets address complex interactions between a process and its partners
by providing a method for explicitly specifying correlated groups of operations
within a service instance. A set of correlation tokens is defined as a set of
properties shared by all messages in the correlated group.
The Adapters tab displays in invoke, receive, and reply activities, and the
onMessage branch of pick activities. You create header variables for use with the
Advanced Queuing (AQ), File, FTP, and Java Message Service (JMS) adapters.
The Annotations tab displays on all activities and enables you to provide
descriptions in activities in the form of code comments and name and pair value
assignments.
See Also:
■
■
■
The Online help for these tabs for additional details about their
use
Chapter 18, "Sensors"
Oracle Adapters for Files, FTP, Databases, and Enterprise Messaging
User’s Guide
Assign Activity
This activity provides a method for data manipulation, such as copying the contents of
one variable to another. This activity can contain any number of elementary
assignments.
When you double-click the assign icon, the Assign window appears. You can perform
the following tasks:
■
■
Click the General tab to provide the assign activity with a meaningful name.
Click the Copy Rules tab and the Create icon shown in Figure C–1 to access the
Create Copy Rule window. This enables you to copy the contents of the source
element (variable, expression, XML fragment, or partner link) in the From field to
the contents of the destination element in the To field. You can also select a part
(typically the payload) and an XPath query (a language for addressing parts of an
XML document).
JDeveloper BPEL Designer Activities C-3
Activities Overview
Figure C–1
Copy Rules Tab of Assign Activity WIndow
If an assign activity contains more than one bpelx:append setting, it must be split
into two assign activities. Otherwise, JDeveloper BPEL Designer moves the
bpelx:append to the end of the list each time, which can cause problems. As a
workaround, move it manually.
See Also: The following documentation for many examples of using
the assign activity:
■
"Using the Assign Activity to Assign Values to Variables" on
page 3-11
■
"Adding an Assign Activity to the Process Map" on page 3-11
■
Chapter 4, "Manipulating XML Data in BPEL"
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle_
Home\integration\orabpel\samples\references\Assig
n
Catch Activity
This activity enables you to create optional fault handling logic to catch and manage
exceptions. Fault handling is associated with a scope activity. Fault handling’s goal is
to undo the incomplete and unsuccessful work of a scope activity in which a fault has
occurred.
Fault handlers in a scope activity enable you to create a set of custom fault-handling
activities, which are defined as catch activities. Each catch activity is defined to
intercept a specific type of fault.
Figure C–2 shows the Add Catch Branch icon inside a scope activity that you click to
create a catch activity. Figure C–3 shows an example of a catch activity on the right
side of the scope activity. Within the area defined as Drop Activity Here, you drag and
drop additional activities to create fault handling logic to catch and manage
exceptions.
C-4 Oracle BPEL Process Manager Developer’s Guide
Activities Overview
For example, a client provides a social security number to a Credit Rating service
when applying for a loan. This number is used to perform a credit check. If a bad
credit history is identified or the social security number is identified as invalid, an
assign activity inside the catch activity notifies the client of the loan offer rejection. The
entire loan application process is terminated with a terminate activity.
Figure C–2
Creating an Add Catch Activity
Figure C–3
Catch Activity Icon
See Also: The following documentation for examples of using the
catch activity:
■
"Using a Fault Handler within a Scope" on page 9-8
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\references\Catch
Compensate Activity
This activity invokes compensation on an inner scope activity that has already
successfully completed. This activity can be invoked only from within a fault handler
or another compensation handler. Compensation occurs when a process cannot
complete several operations after already completing others. The process must return
and undo the previously completed operations. For example, assume a process is
designed to book a rental car, a hotel, and a flight. The process books the car and the
hotel, but is unable to book a flight for the correct day. In this case, the process
performs compensation by unbooking the car and the hotel.
JDeveloper BPEL Designer Activities C-5
Activities Overview
The compensation handler is invoked with the compensate activity, which names the
scope on which the compensation handler is to be invoked.
When you double-click the compensate icon, the Compensate window shown in
Figure C–4 appears. You can perform the following tasks:
■
Click the General tab to provide the activity with a meaningful name and select
the scope activity on which the compensation handler is to be invoked.
Figure C–4
Compensate Activity
See Also: "Using Compensation after Undoing a Series of
Operations" on page 9-9
Empty Activity
This activity enables you to insert a no-operation instruction into a process. This
activity is useful when you need to use an activity that does nothing (for example
when a fault needs to be caught and suppressed). Figure C–5 shows the empty activity.
C-6 Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–5
Empty Activity
See Also: "Using the Empty Activity to Insert No-Op Instructions
into a Business Process" on page 9-8
Flow Activity
A flow activity enables you to specify one or more activities to be performed
concurrently. A flow activity completes when all activities in the flow have finished
processing. Completion of a flow activity includes the possibility that it can be skipped
if its enabling condition is false.
For example, assume you use a flow activity to enable two loan offer providers
(United Loan service and Star Loan service) to start in parallel. In this case, the flow
activity contains two parallel activities – the sequence to invoke the United Loan
service and the sequence to invoke the Star Loan service. Each service can take an
arbitrary amount of time to complete their loan processes.
Figure C–6 shows an initial flow activity with its two panels for parallel processing.
You drag and drop activities into both panels to create parallel processing. When
complete, a flow activity looks like that shown in Figure C–7.
Figure C–6
Flow Activity (At Time of Creation)
JDeveloper BPEL Designer Activities C-7
Activities Overview
Figure C–7
Flow Activity (After Design Completion)
See Also: The following documentation for examples of using the
flow activity:
■
"Defining a Parallel Flow" on page 7-2
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\references\Flow
FlowN Activity
This activity enables you to create activities within a flow. You specify the number of
branches of these activities to create.
Figure C–8 shows a flowN activity.
Figure C–8
FlowN Activity
C-8 Oracle BPEL Process Manager Developer’s Guide
Activities Overview
See Also:
■
■
"Customizing the Number of Flow Activities by Using the flowN
Activity" on page 7-4
Oracle_
Home\integration\orabpel\samples\references\FlowN
Invoke Activity
This activity enables you to specify an operation you want to invoke for the service
(identified by its partner link). The operation can be one-way or request-response on a
port provided by the service. You can also automatically create variables in an invoke
activity. An invoke activity invokes a synchronous service or initiates an asynchronous
Web service.
The invoke activity opens a port in the process to send and receive data. It uses this
port to submit required data and receive a response. For synchronous callbacks, only
one port is needed for both the send and the receive functions.
When you double-click the invoke icon, the Invoke window shown in Figure C–9
appears. You can perform the following tasks:
■
Provide the activity with a meaningful name.
■
Select the partner link for which to specify an operation
■
Select the operation to be performed
■
Automatically create a variable or select an existing variable in which to transport
the data (payload)
Figure C–9
Invoke Activity
JDeveloper BPEL Designer Activities C-9
Activities Overview
See Also: The following documentation for many examples of using
the invoke activity:
■
"Using the Invoke Activity to Perform a Request" on page 5-5
■
"How the Invoke and Receive Activities Work" on page 6-6
■
"Step 2: Adding an Invoke Activity" on page 6-11
■
"Returning a Fault in an Asynchronous Interaction" on page 9-7
■
Chapter 13, "Interaction Patterns"
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\references\Invok
e
Java Embedding Activity
This activity enables you to add custom Java code to a BPEL process using the Java
BPEL exec extension <bpelx:exec>. This is useful when you already have Java
code that can perform a function, and want to use this existing code instead of starting
over.
When you double-click this activity, the Edit Java Embedding window shown in
Figure C–10 appears.
Figure C–10 Java Embedding Activity
If you use this activity, ensure that you add the JAR files to the JDeveloper BPEL
Designer classpath or put them in the Oracle_
Home\integration\jdev\jdev\lib\ext directory to ensure that your project
compiles properly during design time.
In addition, place the corresponding class files in the Oracle_
Home\integration\orabpel\system\classes directory.
Perform the following Java JAR file configuration steps to ensure correct run time
behavior. This example describes the configuration steps for Windows operating
systems. Perform similar steps for UNIX operating systems.
1.
Add the files into the BPEL client bpelc CLASSPATH:
a.
C-10
Open Oracle_Home\integration\orabpel\bin\obsetenv.bat. For
UNIX operating systems, the file is named obsetenv.sh.
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
b.
Edit the file as follows:
@REM set MY_CLASSES_DIR=%CLASSPATH%
set MY_CLASSES_DIR=%OB_HOME%\system\classes
set MY_CLASSPATH=%MY_CLASSES_DIR%;your_jar_files
2.
Add the files into the Oracle BPEL Server bpelc CLASSPATH in either of two
ways:
a.
Open Oracle_
Home\integration\orabpel\domains\default\config\domain.xml
(if the default domain is being used).
b.
Edit the file as follows:
<property id="bpelcClasspath">
<name>BPEL process compiler classpath</name>
<value>your_jar_files;...</value>
<comment>...</comment>
</property>
c.
Restart Oracle BPEL Server.
or
3.
a.
Go to Manage BPEL Domain > Configuration on Oracle BPEL Console.
b.
Go to the bpelcClasspath property.
c.
Enter your_jar_files; in the Value field.
d.
Click Apply.
e.
Restart Oracle BPEL Server.
Add the files into the Oracle Application Server CLASSPATH:
a.
Open Oracle_
Home\integration\orabpel\system\appserver\oc4j\j2ee\home\c
onfig\application.xml.
b.
Edit the file as follows:
<!-- ORABPEL -->
<library path="your_jar_files"/>
<library path="C:\OraBPELPM_1\integration\orabpel\system\classes"/>
See Also:
■
■
"Using Java Embedding in JDeveloper BPEL Designer" on
page 10-6
Oracle_
Home\integraton\orabpel\samples\tutorials\111.Cal
lingSessionBeans for an example of using the Java
Embedding activity
Notification Activity
This activity enables you to send notification 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).
For example, an Online Shopping business process of an online bookstore sends a
courtesy notification message to you after the items are shipped. The business process
JDeveloper BPEL Designer Activities
C-11
Activities Overview
calls the notification service with your user ID and notification message. The
notification service gets the notification address (e-mail address in this case) from
Oracle Internet Directory and sends the message to your e-mail address.
When you drag and drop a notification activity into JDeveloper BPEL Designer, a
Notification wizard starts and prompts you for the above information.
Figure C–11 shows the Notification wizard.
Figure C–11 Notification Activity
See Also:
■
■
Oracle BPEL Process Manager Order Booking Tutorial for an example
of using the notification activity
Chapter 15, "Oracle BPEL Process Manager Notification Service"
PartnerLink Activity
This activity enables you to define the external services with which your process
interacts. 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. For example, if you are creating a process to interact with
a Credit Rating Service and two loan provider services (United Loan and Star Loan),
you create partner links for all three services.
When you double-click the partnerlink icon, the Partner Link window shown in
Figure C–12 appears. You can provide the following details:
C-12
■
A meaningful name for the service
■
The Web services description language (WSDL) file of the external service
■
The actual service type (defined as Partner Link Type)
■
The role of the process requesting the service (defined as My Role)
■
The role of the service (defined as Partner Role)
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–12 PartnerLink Activity
See Also: The following documentation for many examples of using
the PartnerLink activity:
■
"Establishing the Partner Link" on page 5-2
■
"partnerLinkTypes for Asynchronous Services" on page 6-3
■
"Step 1: Adding a Partner Link for an Asynchronous Service" on
page 6-10
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
Pick Activity
This activity waits for the occurrence of one event in a set of events and performs the
activity associated with that event. The occurrence of the events is often mutually
exclusive (the process either receives an acceptance or rejection message, but not both).
If more than one of the events occurs, then the selection of the activity to perform
depends on which event occurred first. If the events occur nearly simultaneously, there
is a race and the choice of activity to be performed is dependent on both timing and
implementation.
The pick activity provides two branches, each one with a condition. When you
double-click the pick icon, the pick activity shown in Figure C–13 appears and
displays these two branches: onMessage (on the left) and onAlarm (on the right). The
onMessage branch contains the code for receiving a reply, for example, from a loan
service. The onAlarm branch contains the code for a timeout, for example, after one
minute. Whichever branch completes first is executed; the other branch is not. The
branch that has its condition satisfied first is executed.
JDeveloper BPEL Designer Activities
C-13
Activities Overview
Figure C–13 Pick Activity
If you add correlations to an OnMessage branch of a Pick activity in JDeveloper BPEL
Designer, the correlations syntax is placed after the assign activity syntax. The
correlation syntax must go before the assign activity.
As a workaround, perform the following steps:
1.
Create a correlation set in JDeveloper BPEL Designer.
2.
Assign this to the OnMessage branch.
3.
Complete the remaining design tasks.
4.
Before making or deploying the BPEL process, move the correlation syntax before
the assign activity in the BPEL source code.
See Also:
■
"Using the Pick Activity to Select Between Continuing a Process or
Waiting" on page 11-2
■
"Defining a Timeout in JDeveloper BPEL Designer" on page 11-4
■
Chapter 13, "Interaction Patterns"
■
Oracle_
Home\integration\orabpel\samples\references\Pick
for an example of using the pick activity
Receive Activity
This activity specifies the partner link from which to receive information and the port
type and operation for the partner link to invoke. This activity waits for an
asynchronous callback response message from a service, such as a loan application
approver service. While the BPEL process is waiting, it is dehydrated (compressed and
stored) until the callback message arrives. The contents of this response are stored in a
response variable in the process.
When you double-click the receive icon, the Receive window shown in Figure C–14
appears. You can perform the following tasks:
■
Provide the receive activity with a meaningful name.
■
Select the partner link service for which to specify an operation
■
Select the operation to be performed
■
C-14
Automatically create a variable or select an existing variable in which to transport
the callback response
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–14 Receive Activity
See Also: The following documentation for many examples of using
the receive activity:
■
"How the Invoke and Receive Activities Work" on page 6-6
■
"Step 3: Adding a Receive Activity" on page 6-13
■
Chapter 13, "Interaction Patterns"
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle_
Home\integration\orabpel\samples\references\Recei
ve
Reply Activity
This activity allows the process to send a message in reply to a message that was
received through a receive activity. The combination of a receive activity and a reply
activity forms a request-response operation on the WSDL port type for the process.
Figure C–15 shows the reply activity.
JDeveloper BPEL Designer Activities
C-15
Activities Overview
Figure C–15 Reply Activity
See Also:
■
"Using the Reply Activity to Send Messages in Response to a
Receive Activity" on page 6-9
■
"Returning a Fault in a Synchronous Interaction" on page 9-7
■
Chapter 13, "Interaction Patterns"
■
Oracle_
Home\integration\orabpel\samples\references\Reply
for an example of using the reply activity
Scope Activity
This activity consists of a collection of nested activities that can have their own local
variables, fault handlers, compensation handlers, and so on. A scope activity is
analogous to a { } block in a programming language.
Each scope has a primary activity that defines its behavior. The primary activity can be
a complex structured activity, with many nested activities within it to arbitrary depth.
The scope is shared by all the nested activities.
When you double-click the scope icon, the Scope window shown in Figure C–16
appears. Define appropriate activities inside the scope activity.
C-16
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–16 Scope Activity
See Also: The following documentation for many examples of using
the scope activity:
■
"Using the Scope Activity to Manage a Group of Activities" on
page 9-4
■
Chapter 13, "Interaction Patterns"
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
Sequence Activity
This activity enables you to define a collection of activities to be performed in
sequential order. For example, you may want the following activities performed in a
specific order:
■
A customer request is received in a receive activity.
■
The request is processed inside a flow activity that enables concurrent behavior.
■
A reply message with the final approval status of the request is sent back to the
customer in a reply activity.
A sequence activity makes the assumption that the request can be processed in a
reasonable amount of time, justifying the requirement that the invoker wait for a
synchronous response (because this service is offered as a request-response operation).
When this assumption cannot be made, it is better to define the customer interaction as
a pair of asynchronous message exchanges.
When you double-click the sequence icon, the sequence activity shown in Figure C–17
appears. Define appropriate activities inside the sequence activity.
JDeveloper BPEL Designer Activities
C-17
Activities Overview
Figure C–17 Sequence Activity
See Also:
■
"Defining a Parallel Flow" on page 7-2
■
Chapter 13, "Interaction Patterns"
Switch Activity
This activity consists of an ordered list of one or more conditional branches defined in
a case branch, followed optionally by an otherwise branch. The branches are
considered in the order in which they appear. The first branch whose condition is true
is taken and provides the activity performed for the switch. If no branch with a
condition is taken, then the otherwise branch is taken. If the otherwise branch is not
explicitly specified, then an otherwise branch with an empty activity is assumed to be
available. The switch activity is complete when the activity of the selected branch
completes.
A switch activity differs in functionality from a flow activity. For example, a flow
activity enables a process to gather two loan offers at the same time, but does not
compare their values. To compare and make decisions on the values of the two offers,
a switch activity is used. The first branch is executed if a defined condition (inside the
case branch) is met. If it is not met, the otherwise branch is executed.
Figure C–18 shows a switch activity with two defined branches.
Figure C–18 Switch Activity
C-18
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
See Also: The following documentation for examples of using the
switch activity:
■
"Using a Switch Activity to Define Conditional Branching" on
page 8-2
■
Chapter 13, "Interaction Patterns"
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle_
Home\integration\orabpel\samples\references\Switc
h
Terminate Activity
A terminate activity enables you to end the tasks of an activity (for example, the fault
handling tasks in a catch branch). For example, if a client’s bad credit history is
identified or a social security number is identified as invalid, a loan application
process is terminated, and the client’s loan application document is never submitted to
the service loan providers.
Figure C–19 shows a terminate activity at the end of a catch branch of a scope activity.
Figure C–19 Terminate Activity
See Also: The following documentation for examples of using the
terminate activity:
■
"Using the Terminate Activity to Stop a Business Process Instance"
on page 9-10
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle BPEL Process Manager Quick Start Guide
■
Oracle_
Home\integration\orabpel\samples\references\Termi
nate
Throw Activity
This activity generates a fault from inside the business process.
JDeveloper BPEL Designer Activities
C-19
Activities Overview
When you double-click the throw icon, the Throw window shown in Figure C–20
appears.
Figure C–20 Throw Activity
See Also: The following documentation for examples of using the
throw activity:
■
■
"Throwing Internal Faults" on page 9-6
Oracle_
Home\integration\orabpel\samples\references\Throw
Transform Activity
This activity enables you to create a transformation that maps source elements to
target elements (for example, incoming purchase order data into outgoing purchase
order acknowledgment data).
When you double-click the transform icon, the Transform window shown in
Figure C–21 appears. This window enables you to perform the following tasks:
■
Define the source and target variables and parts to map
■
Specify the transformation mapper file
■
C-20
Click the second icon (the Create Mapping icon) to the right of the Mapper File
field to access a window for graphically mapping source and target elements. This
window enables you to drag and drop (map) a source element to a target element.
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–21 Transform Activity
See Also: The following documentation for examples of using the
transform activity:
■
Chapter 14, "XSLT Mapper and Transformations"
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\demos\XSLMapper
User Task
This activity enables you to start the Workflow wizard. A workflow describes the
tasks, input or output information, and procedural steps that must be performed by
users or groups as part of the end-to-end business process. For example, an insurance
company can design a workflow application to ensure that a claim is handled
consistently from initial call to final settlement. The workflow application ensures that
each person handling the claim uses the correct online form and successfully
completes their step before enabling the process to proceed to the next person and
procedural step.
This wizard enables you to create a workflow model to manage and enforce the
consistent handling of work. After wizard creation, you can also further customize a
workflow pattern by directly modifying the configuration files. At run time, the
workflow results in the creation of tasks that can be accessed through the Oracle BPEL
Worklist Application.
When you drag and drop a user task, the Welcome window shown in Figure C–22
appears.
JDeveloper BPEL Designer Activities
C-21
Activities Overview
Figure C–22 User Task Activity
See Also: The following documentation for examples of using the
user task activity and workflows:
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\demos\HelpDeskSe
rviceRequest
■
Oracle_
Home\integration\orabpel\samples\demos\TimeOffReq
uestDemo
■
Oracle_
Home\integration\orabpel\samples\demos\VacationRe
quest
■
Chapter 16, "Oracle BPEL Process Manager Workflow Services"
■
Chapter 17, "Worklist Application"
Wait Activity
This activity allows a process to specify a delay for a certain period of time or until a
certain deadline is reached. A typical use of this activity is to invoke an operation at a
certain time. This activity allows you to wait for a given time period or until a certain
time has passed. Exactly one of the expiration criteria must be specified.
When you double-click the wait icon, the Wait window shown in Figure C–23 appears.
C-22
Oracle BPEL Process Manager Developer’s Guide
Activities Overview
Figure C–23 Wait Activity
See Also: The following documentation for examples of using the
wait activity:
■
"Using the Wait Activity to Set an Expiration Time" on page 11-4
■
Oracle BPEL Process Manager Order Booking Tutorial
■
Oracle_
Home\integration\orabpel\samples\references\Wait
While Activity
This activity supports repeated performance of a specified iterative activity. The
iterative activity is repeated until the given while condition is no longer true.
When you double-click the while icon, the While window shown in Figure C–24
appears. You can enter expressions in this window.
JDeveloper BPEL Designer Activities
C-23
Summary
Figure C–24 While Activity
See Also: The following documentation for examples of using the
while activity:
■
■
■
"Using a While Activity to Define Conditional Branching" on
page 8-4
Oracle BPEL Process Manager Order Booking Tutorial
Oracle_
Home\integration\orabpel\samples\references\While
Summary
This appendix describes the activities you can drag and drop into a BPEL process with
JDeveloper BPEL Designer.
C-24
Oracle BPEL Process Manager Developer’s Guide
D
User Task 2.0 Macro
This appendix describes the User Task 2.0 macro.
This appendix contains the following topics:
■
Introduction to User Task 2.0 Macro
■
BPEL User Task Use Case
■
The TaskManager Service
■
Additional Capabilities of the TaskManager Service
■
Summary
Introduction to User Task 2.0 Macro
The User Task 2.0 macro supports user tasks from release 2.0. The User Task 2.0 macro
is available for backward compatibility and is replaced in this release. See Chapter 16,
"Oracle BPEL Process Manager Workflow Services" to learn about the new system for
handling user tasks.
BPEL processes compose multiple services into one process flow. There are frequently
tasks in that flow that require user input. For example:
■
A customer fills out a form
■
A loan offer approves an application
■
An error appears that requires a human decision to resolve
This appendix discusses the tools available for adding user tasks to a BPEL process, as
well as designing interfaces to collect data from users.
BPEL User Task Use Case
This appendix uses an example of a loan officer reviewing a loan application and then
approving or denying it.
See Also: The following samples:
■
■
Oracle_
Home\integration\orabpel\samples\tutorials\110.Us
erTasks (for JDeveloper BPEL Designer)
C:\orabpel\samples\tutorials\110.UserTasks (for
Eclipse BPEL Designer)
User Task 2.0 Macro D-1
The TaskManager Service
The TaskManager Service
Oracle BPEL Process Manager provides a TaskManager service to help model user
interactions with the BPEL process. The asynchronous TaskManager service has a
WSDL interface so that a BPEL process can initiate a user task by calling the
TaskManager, and receive a response, just as with any other Web service. The
TaskManager has a Java Worklist API that you can use to build graphical user interface
applications that show users which information is needed and return user input to the
TaskManager (and then on to the BPEL process). The WSDL interface also allows the
BPEL process to update a task in process, for example, to assign it to a different user if
the first user is unavailable. Figure D–1 provides an overview.
Figure D–1
TaskManager Service
BPEL Process
<receive>
Custom
Web
Application
TaskManager
(Service)
WSDL
Interface
Worklist Java API
<invoke>
initiateTask
(task)
Minutes, hours
or days
listTasksByAssignee
(assignee)
lookupTask
(taskId)
Worklist
Page
<JSP>
Display
Task
<JSP>
<receive>
onTaskResult
(task)
completeTask
(taskId)
Complete
Task
<JSP>
<invoke>
A task document includes all information about a task. The task document in wrapped
in a taskMessage, and all inbound and outbound operations use the same taskMessage
to exchange information about the task. Figure D–2 provides an overview.
D-2 Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
Figure D–2
taskMessage
Task.xsd at
http://localhost:9700/orabpel/default/TaskManager/Task.xsd
is a sample task document.
<xs:element name="task">
<xs:complexType>
<xs:sequence>
<xs:element name="taskId" type="xs:string" minOccurs="0"/>
<xs:element name="title" type="xs:string" minOccurs="0"/>
<xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="creator" type="xs:string" minOccurs="0"/>
<xs:element name="modifyDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="modifier" type="xs:string" minOccurs="0"/>
<xs:element name="assignee" type="xs:string" minOccurs="0"/>
<xs:element name="status" minOccurs="0">
<xs:simpleType>
<xs:restriction base="xs:string">
User Task 2.0 Macro D-3
The TaskManager Service
<xs:enumeration value="active"/>
<xs:enumeration value="completed"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="expired" type="xs:boolean" minOccurs="0"/>
<xs:element name="expirationDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="duration" type="xs:duration" minOccurs="0"/>
<xs:element name="priority" type="xs:int" minOccurs="0"/>
<xs:element name="template" type="xs:string" minOccurs="0"/>
<xs:element name="customKey" type="xs:string" minOccurs="0"/>
<xs:element name="conclusion" type="xs:string" minOccurs="0"/>
<xs:element name="attachment" type="xs:anyType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Table D–1 describes the fields in the task document.
Table D–1
Task Document Fields
Field
Description
taskId(string)
ID used to identify a task; automatically set by the TaskManager
service when the task is created.
See Also: customKey (string)
title(string)
Typically used when you are presented with a list of the tasks
you need to complete, for example, Approval for order
#223.
creationDate
(dateTime)
Automatically set by the TaskManager service when the task is
created.
creator (string)
ID of the application, system, or (sometimes) user initiating the
task; typically used by the graphical user interface to partition
the complete worklist into categories. When the BPEL designer
(Eclipse BPEL Designer or JDeveloper BPEL Designer) is used to
integrate the TaskManager service into a process, it sets this
value to the name of the process initiating the task.
modifyDate (dateTime) Managed by the TaskManager service; defines when the task
was last modified.
modifier (string)
ID of the user or role performing the task update or completion
operation. The semantics of the ID are owned by the application.
assignee (string)
ID of the user, role, or group responsible for completing the task.
The semantics of the ID are opaque to both Oracle BPEL Process
Manager and the TaskManager service: the BPEL process sets
the assignee ID, and the graphical user interface queries the list
of tasks, passing in the ID.
status (active |
completed)
Managed by the TaskManager service; equal to active or
completed.
expired (boolean)
Managed by the TaskManager service; indicates whether or not
the task has expired.
expirationDate
(dateTime)
Optional; defines when the task expires.
duration (duration)
Optional; the duration after which the task expires. When both
an expirationDate and a duration are provided, the
expirationDate prevails.
See Also: duration (duration)
D-4 Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
Table D–1
(Cont.) Task Document Fields
Field
Description
priority (int)
Optional; an integer marking the priority of the task. The
semantics are left to the BPEL process and graphical user
interface application.
customKey (string)
Optional; an application-specific key. The BPEL process and
graphical user interface application can use either taskId or
customKey when looking up a specific task.
conclusion (string)
Optional; an application-specific field used to tell the BPEL
process how the task was completed; for example, Approved,
Refused, or Canceled. A common pattern in the BPEL process
is that the step after the completion of the task is a switch
activity that keys off the conclusion field. Note that this kind of
information can also be passed through the attachment field.
attachment (anyType)
Optional; application-specific data of any type, for any purpose
of the application.
Note: Correlation and callback address information is not in the
taskMessage, but instead is in a WS-Addressing header.
Integrating the TaskManager Service into a BPEL Process
The general steps for integrating the TaskManager service into a BPEL process are:
1.
Define a partner link for the TaskManager service.
2.
Declare and initialize the task document.
3.
Invoke the initiateTask operation of the TaskManager service just like any
other standard Web service, using an invoke activity.
4.
Wait for the onTaskResult callback from the TaskManager service, using a
receive activity.
5.
Read the updated task document from the callback message.
Defining a Partner Link for the TaskManager Service
You need a partner link in your process to indicate that you are calling the
TaskManager service from your BPEL process (just as for any other Web service). The
WSDL file for the TaskManager service can be found on your local Oracle BPEL
Process Manager installation at this location:
http://localhost:9700/orabpel/default/TaskManager/TaskManager.wsdl
The outcome of adding the partner link is as illustrated in the TaskSample process
referenced in the See Also note on page D-1. The deployment descriptor bpel.xml
file references the TaskManager service WSDL file, as shown below.
<properties id="reviewManager">
<property name="wsdlLocation">
http://localhost:9700/orabpel/default/TaskManager/TaskManager?wsdl
</property>
</properties>
The BPEL process definition in the TaskSample.bpel file uses this property to
define a partner link for the TaskManager.
User Task 2.0 Macro D-5
The TaskManager Service
xmlns:task="http://services.oracle.com/bpel/task"
.
<partnerLink name="reviewManager"
partnerLinkType="task:TaskManager"
partnerRole="TaskManager"
myRole="TaskManagerRequester"/>
Declare and Initialize the Task Document
Before the TaskManager service can be invoked, a taskMessage must be constructed.
The following BPEL code from TaskSample.bpel shows how to construct this
message using the BPEL assign activity.
<scope name="review" variableAccessSerializable="no">
<variables>
<variable name="reviewTask"
element="task:task"/>
...
</variables>
<sequence>
...
<assign name="configureTask">
<!-- Assign 'title' in task document -->
<copy>
<from variable="input" part="payload"
query="/stockReviewSheet/symbol"/>
<to variable="reviewTask" query="/task/title"/>
</copy>
<!-- Assign 'assignee' in task document -->
<copy>
<from expression="string('jsmith@finance.com')"/>
<to variable="reviewTask" query="/task/assignee"/>
</copy>
<!-- ... See the full source for the other field settings -->
<!-- Assign 'attachment' in task document -->
<copy>
<from variable="input" part="payload"/>
<to variable="reviewTask" query="/task/attachment"/>
</copy>
</assign>
Initiate the Task
The next step in your BPEL process is to initiate the TaskManager by invoking its
initiateTask operation, passing the data defined above. Specifically, you pass a
taskMessage that you set up as a wrapper around the task document.
<scope name="reviewUserInteraction" variableAccessSerializable="no">
<variables>
<variable name="taskRequest" messageType="task:taskMessage"/>
...
</variables>
<sequence>
<!-- Assign task document to taskMessage -->
<assign name="setPayload">
<copy>
<from variable="reviewTask"/>
<to variable="taskRequest" part="payload"/>
</copy>
</assign>
<!-- Initiate task -->
D-6 Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
<invoke name="initiateTask"
partnerLink="review"
portType="task:TaskManager"
operation="initiateTask"
inputVariable="taskRequest"/>
...
</sequence>
</scope>
This creates the task and assigns it to the assignee specified in the task document. The
task is available to you through the Worklist Java API.
Task Completion
At this point, the task is created and assigned to the assignee specified in the task
document and is available through the Worklist Java API.
The BPEL process waits for the TaskManager service to call it back. The callback passes
back an updated taskMessage, indicating that the task has been completed or has
expired.
<variable name=" taskResponse"
messageType="task:taskMessage"/>
...
<!-- Receive the outcome of the task -->
<receive name="receiveTaskResult"
partnerLink="review"
portType="task:TaskManagerCallback"
operation="onTaskResult"
variable="taskResponse"/>
<!-- Read task document from taskMessage -->
<assign name="readPayload">
<copy>
<from variable="taskResponse" part="payload"/>
<to variable="reviewTask"/>
</copy>
</assign>
The receive activity shown above does not complete until a callback is received from
the TaskManager service. As with all asynchronous activities, the BPEL process is
dehydrated reliably during this time, and rehydrated and executed when the task
completion (or expiration) event occurs.
The type for the TaskManager service response data is the same taskMessage message
type that was used for the initiate message. However, because the type for the
attachment field is an XML schema anyType and is application-defined, the
attachment data returned can be any type and specifically does not need to be the
same type as the initiate message attachment.
Typically, the conclusion field contains information that tells the BPEL process how the
task was completed (for example, Approved, Rejected, or Canceled). This kind of
information can also be passed through the attachment; it is up to the programmer to
pass task data in the preferred manner.
Using Eclipse BPEL Designer to Integrate the TaskManager Service
This section reviews how to integrate the TaskManager service into a BPEL process
using Eclipse BPEL Designer (based on version 0.6). It assumes you are already
familiar with the basics for creating an asynchronous process, as discussed in Tutorial
User Task 2.0 Macro D-7
The TaskManager Service
2, Developing a Credit Flow BPEL Process at
http://www.oracle.com/technology/bpel.
Eclipse BPEL Designer simplifies matters considerably for you by generating much of
the code described earlier in this chapter. This enables you to drag a user task from the
BPEL Palette into your process. The following steps describe how to add a user task
named review to a new asynchronous BPEL process (called TestTask) created in
Eclipse BPEL Designer; in actual practice, of course, your starting point is a process
that you are developing.
1.
In the Process Map view of the BPEL file, drag a user task from the BPEL Palette
(specifically, the last item in the More Activities list) to the transition arrow
between the initiate (client) receive activity and the onResult (client) invoke
callback activity.
2.
In the User Task window that appears, enter review as the task name and click
Done.
A scope activity named review appears in Eclipse BPEL Designer. This scope is
the currently selected element, so the BPEL Inspector displays information about
it. For example, it defines an XML variable named reviewTask (which is the task
document).
Note: All names beginning with review in this example generally
begin with the task name you specify in the User Task window.
3.
Expand the newly created scope by clicking the + icon to the left of it in the
Process Map view. Within the expanded scope, you see an assign activity (named
configureTask) and a task that can be expanded further.
The configureTask assignment initializes the task document; however, before
going to that level, you do one more expansion, to get an overview of the process.
4.
Expand the task (reviewUserInteraction) by clicking its + icon and notice that it
expands into a scope containing the invoke and receive activities for the task,
along with two assign activities. Click the label along the left edge of this scope.
This selects the scope and enables you to see its contents in the BPEL Inspector.
D-8 Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
5.
Scroll back in the Process Map if necessary to the outer scope (named review) and
click the configureTask assignment within it. Listed under Copy Rules in the
BPEL Inspector are the fields of the reviewTask task document.
You can view the Copy Rule window for each field either by selecting Edit Rule in
its drop-down list or by clicking the field name (which is a link). For every field
except the last one, attachment, the Copy Rule window shows an assignment
being made to that field. In actual practice, you change the values being assigned
to the fields title through priority as appropriate, and optionally pass custom data
to the task through the attachment field (as in the next step).
6.
To pass data to the task, click Edit Rule in the drop-down list for the attachment
field in the BPEL Inspector (or click attachment) and complete the From part of
the Copy Rule window (for example, to pass the payload part of the input variable
as described in "Declare and Initialize the Task Document" on page D-6). If you do
not want to pass anything in the attachment field, you must click Delete Element
in the field's drop-down list (or the process does not compile because of the
incomplete assignment).
User Task 2.0 Macro D-9
The TaskManager Service
7.
Click Done to complete the configuration of the attachment copy rule.
8.
Click the next assign activity in the Process Map: setPayload, inside the
reviewUserInteraction scope. You see that only payload is listed under Copy
Rules. If you look at the Copy Rule window, reviewTask (the task document from
the outer scope) is assigned to the payload part of the taskRequest variable as the
final step before initiating the task.
9.
Click the final assign activity (readPayload).
10. Explore this activity in the BPEL Inspector to see that this is where the task data
returned in a taskMessage (that is, in the payload part of the taskResponse
variable) is read and stored in the variable reviewTask.
Note that while the above may seem complex at first, it is because the TaskManager
service is a complex service. The Designer User Task Palette entry is merely a
preconfigured template that encapsulates the normal patterns for use of the
TaskManager service in a BPEL flow. However, Eclipse BPEL Designer continues to
D-10
Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
improve as a means of integrating the TaskManager service into a BPEL process. You
also have the option of working directly in the BPEL source code.
Creating a User Interface for the Task
On the other side of a TaskManager service is typically a user interface in which the
assigned users can view, update, and complete tasks. Figure D–3 provides an
overview.
Figure D–3
TaskManager and a Custom Web Application
Custom Web Application
TaskManager
(Service)
WSDL
Interface
Worklist Java API
initiateTask
(task)
listTask
(assignee)
lookupTask
(taskId)
onTaskResult
(task)
completeTask
(taskId)
Worklist
Page
<JSP>
Display
Task
<JSP>
Complete
Task
<JSP>
The typical steps for accessing task information from the user side are:
1.
A graphical user interface uses the Java Worklist API to list the tasks assigned to a
user or role.
2.
The user selects a task and reviews its detail information.
3.
The user updates any editable data associated with the task and saves or
completes the task.
List the Assigned Tasks
Using the Java Worklist API to the TaskManager service from the client perspective
involves the following high-level steps. The code shown in this section is taken from
C:\orabpel\samples\tutorials\110.UserTasks\TaskSampleUI\listTask
s.jsp.
1.
Use the com.oracle.bpel.client.Locator class to return a worklist service
handle (an IWorklistService).
<%@page import="com.oracle.bpel.client.Locator" %>
<%@page import="com.oracle.bpel.services.task.IWorklistService" %>
...
// Obtain a reference to BPEL domain ‘default’ using password ‘bpel’
User Task 2.0 Macro
D-11
The TaskManager Service
Locator locator=new Locator("default", "bpel");
IWorklistService worklist =
(IWorklistService)
locator.lookupService(IWorklistService.SERVICE_NAME);
2.
Use the com.oracle.bpel.services.task.IWorklistService interface to
fetch com.oracle.bpel.services.task.ITask objects, manipulate them,
complete them, and so on.
<%@page import="com.oracle.bpel.services.task.ITask" %>
...
ITask[] tasks=
worklist.listTasksByAssignee("jsmith@finance.com");
...
You can fetch tasks by other criteria as well. For example, you can look up a task by its
unique taskId assigned by the TaskManager service or based on a specified creator
attribute (which is programmer-defined). You can also build an arbitrary search
criterion using the com.oracle.bpel.client.util.WhereCondition utility
class (for example, to fetch all the expired tasks assigned to a particular user). For more
information, including full documentation on the interfaces for the classes used in the
code in this section, see Oracle BPEL Process Manager API Javadocs (located at
C:\orabpel\docs\apidocs\index.html).
The code below shows how to iterate through the list of tasks in the JSP page and, for
each task, display some basic descriptive information and a link that displays a details
page (displayTask.jsp) for the task.
<h1>My Custom Task List Page</h1>
<table border="1">
<tr>
<th>Title</th>
<th>Due Date</th>
<th>Priority</th>
</tr>
<%
// Iterate through the list of tasks
for (int i=0; i < tasks.length; i ++)
{
ITask thisTask=tasks[i];
// We are interested in tasks assigned to "jsmith@finance.com"
// and generated by the TaskSample BPEL process. Often the BPEL
// process initiating a task will assign its name to the
// creator field of the task document. This is at least the
// case with the TaskSample BPEL process.
if (! "TaskSample".equals(thisTask.getCreator()))
{
// This task has been generated by another BPEL process
// and should therefore not be in the list.
continue;
}
// Read the title assigned to the task. The title is to
// a task what a subject would be to an email.
String title=thisTask.getTitle();
// Get the unique ID/key associated with this task.
// This is passed from page to page to identify the
// task the user is reviewing and completing.
String taskId=thisTask.getTaskId();
D-12
Oracle BPEL Process Manager Developer’s Guide
The TaskManager Service
// Read the expiration date assigned to the task.
Date expiration=null;
if (thisTask.getExpirationDate() != null)
expiration=thisTask.getExpirationDate().getTime();
// Read priority associated with the task
int priority=thisTask.getPriority();
%>
<tr>
<td>
<a href="displayTask.jsp?taskId=<%= taskId %>">
<%= title %></a>
</td>
<td>
<%= expiration %>
</td>
<td>
<%= priority %>
</td>
</tr>
<%
}
%>
</table>
Display the Payload Data for a Task
The displayTask.jsp page invoked from the hyperlink in the code above gets
passed a taskId (again, a unique string identifier generated by the TaskManager
service) and uses the same Locator and IWorklistService objects as above to
fetch the task associated with that taskId. Then, to manipulate the payload data
associated with a task, it uses the facade capability, which provides a thin Java
interface on top of arbitrary XML data. Note that facades are not at all like JAXB-style
bindings because they do not attempt to fully map XML to Java. They merely provide
a Java envelope for XML data that is then accessed through JavaBeans-style getter
and setter functions. This enables facades to avoid all of the problems associated
with JAXB bindings as schemas get complex.
The facade construct is described in more detail in "Using an XML Facade to Simplify
DOM Manipulation" on page 10-4; however, at a very high level, the basic steps for
working with the XML facade are as follows:
1.
Use the schemac Ant task (or command-line tool) in your build.xml script to
generate facade classes for XML schema types. For example:
<schemac input="${basedir}/TaskSample.wsdl"
out="${basedir}/TaskSampleUI/WEB-INF/classes"/>
This command generates the facade classes for the XML schema types described in
TaskSample.wsdl, namely:
<element name="stockReviewSheet" type="finance:StockReviewSheetType" />
<complexType name="StockReviewSheetType">
<sequence>
<element name="symbol" type="string" />
<element name="targetPrice" type="float" />
<element name="currentPrice" type="float" />
<element name="action" type="string" />
<element name="quantity" type="int" />
</sequence>
</complexType>
User Task 2.0 Macro
D-13
The TaskManager Service
The facade classes generated include a factory for creating new instances of the
StockReviewSheet element and then getter and setter methods for
manipulating the data fields within the instances. If you want to review the exact
interfaces exposed by the generated classes, you can either view the generated
Java classes or create Javadocs for them by using the -j option to the schemac
command.
2.
Within your code, you can use the generated classes to manipulate instances of
XML data types through a simple Java interface. The code below from
C:\orabpel\samples\tutorials\110.UserTasks\
TaskSampleUI\displayTask.jsp uses the Locator and
IWorklistService objects to fetch a particular task by taskId. It then gets the
payload of the task, which is a W3C DOM element type, and uses that and the
facade StockReviewSheetFactory class to instantiate a StockReviewSheet
facade instance. Finally, the facade class getter and setter methods are used to
fetch appropriate data fields from the payload and display them in the JSP page.
<%@ page import="com.otn.samples.finance.StockReviewSheet" %>
<%@ page import="com.otn.samples.finance.StockReviewSheetFactory" %>...
Locator locator=new Locator("default", "bpel");
IWorklistService worklist=(IWorklistService)
locator.lookupService(IWorklistService.SERVICE_NAME);
ITask task=worklist.lookupTask(taskId);
// Get a reference to the XML StockReviewSheet document attached to the
// task. If you look at the implementation of the TaskSample BPEL
// process, you will notice that a StockReviewSheet element is assigned
// to the task as an attachment.
Element rsElement=(Element) task.getAttachment();
StockReviewSheet srs =
StockReviewSheetFactory.createFacade(rsElement);
// Use the friendly bean interface of the XML facade to access the data
// contained in the XML attachment.
String symbol=srs.getSymbol();
float targetPrice=srs.getTargetPrice();
float currentPrice=srs.getCurrentPrice();
...
<tr>
<td>Symbol</td>
<td><input type="text" name="Symbol"
value="<%= symbol %>"/></td>
<td>(String)</td>
</tr>
...
The displayTask JSP page provides an HTML form that enables the user to fill
in the action and quantity fields for the stock review sheet, as well as to edit any of
its other fields. When the form is submitted, it passes these values, along with the
taskId, to completeTask.jsp.
Update the Payload Data and Complete the Task
The final step is to use the generated facade classes to create the appropriate
attachment data element (the task document) to be returned to the task and then pass
D-14
Oracle BPEL Process Manager Developer’s Guide
Additional Capabilities of the TaskManager Service
it to the TaskManager service along with an indication that the task has been
completed.
In this example, this is done in completeTask.jsp, which creates a new instance of
the StockReviewSheet element and fills it in with the form data passed to it. It then
looks up the task by taskId, as before. What is new about this code from
completeTask.jsp is shown below. It sets some fields of the task object (including
the updated attachment) and then informs the worklist service that the task has been
completed.
StockReviewSheet srs=StockReviewSheetFactory.createFacade();
// Populate symbol from data submitted as part of the post
srs.setSymbol(request.getParameter("symbol"));
..
ITask task=worklist.lookupTask(taskId);
task.setAttachment(srs.getRootElement());
// Conclusion is user-defined – here it is “buy” or “sell”
task.setConclusion(strAction);
worklist.completeTask(task);
out.println("This task has been successfully completed.");
At this point, the TaskManager service calls back asynchronously to the process that is
waiting for this task, passing it the updated task attributes and attachment data.
Additional Capabilities of the TaskManager Service
This final section looks at some additional capabilities related to working with the
TaskManager service: expirations and timeouts, notification to the assignee, task
reassignment, and task assignment to groups (and role resolution).
Enabling Expiration/Timeouts for Tasks
The TaskManager service has a built-in expiration and timeout capability. You can
specify the timeout period for a task as a period of time (duration field) or a specific
point in time (expirationDate field). In either case, when the specified time is
reached and the task has not yet been completed, an expiration event is sent as a BPEL
event to the process that is waiting for completion of that TaskManager service. The
waiting BPEL process then uses a BPEL event handler. At that point, the process can
take any desired action (including sending a reminder e-mail, reassigning the task to
someone else, canceling the task, and so on).
The duration and expirationDate fields are specified as having the XML schema
types duration and dateTime, respectively. For example, a duration of one hour is
specified as PT1H (meaning a period of time of 1 hour). In addition to H for hours, you
can also use M for minutes, S for seconds, and so on. For more information on the
format of the duration and dateTime data types, see the XML schema specification:
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#duration
and
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#dateTime
First, in the BPEL source you specify a duration or expiration date, as follows:
User Task 2.0 Macro
D-15
Additional Capabilities of the TaskManager Service
<!-- Assign 'duration' in task document -->
<copy>
<from expression="string('PT5M')"/>
<to variable="reviewTask" query="/task/duration"/>
</copy>
After initiating the task, do the following:
1.
Wrap the TaskManager service receive activity in a scope.
2.
Add an event handler to the scope to handle onTaskExpired events.
3.
Within that event handler, do whatever you like in response to the expiration
event. The code below reassigns the task to someone else and sets a new
expiration time of one more hour.
<invoke name="initiateTask" partnerLink="review" portType="task:TaskManager"
operation="initiateTask" inputVariable="taskRequest"/>
<!-- Receive the outcome of the task -->
<scope name="reviewTask">
<eventHandlers>
<onMessage partnerLink="review" portType="task:TaskManagerCallback"
operation="onTaskExpired" variable="taskRequest">
<sequence>
<assign name="reassignTask">
<!-- Assign NEW 'assignee' in task document -->
<copy>
<from expression= "string('director@oracle.com')"/>
<to variable="taskRequest" part="payload"
query="/task/assignee"/>
</copy>
<!-- Assign NEW 'duration' in task document -->
<copy>
<from expression="string('PT1H')"/>
<to variable="taskRequest" part="payload"
query="/task/duration"/>
</copy>
<copy>
<from expression="string('Escalated')"/>
<to variable="taskRequest" part="payload"
query="/task/status"/>
</copy>
</assign>
<invoke name="reassign" partnerLink="review" portType="task:TaskManager"
operation="updateTask" inputVariable="taskRequest"/>
</sequence>
</onMessage>
</eventHandlers>
<receive name="receiveTaskResult" partnerLink="review"
portType="task:TaskManagerCallback" operation="onTaskResult"
variable="taskResponse"/>
</scope>
If you want to run the entire example, see the from the TimeOffRequestFlow
sample available in c:\orabpel\samples\demos\TimeOffRequestDemo.
Sending Notifications
It is common to send a notification message to a user when a task is assigned to that
user (or when the timeout duration is reached, when the task is reassigned, or in other
D-16
Oracle BPEL Process Manager Developer’s Guide
Summary
situations). This notification can be done in BPEL at the same time that the
TaskManager service is initiated; therefore, anything that can be done in BPEL
(invoking a Web service, sending an e-mail message or a JMS message, executing some
Java code, and so on) can be done to notify a user of a task-related event.
The TimeOffRequestFlow sample includes a code example of using the Oracle BPEL
Process Manager Mail Service to send an e-mail notification to a user when a time-off
request approval task has been assigned to that user. In this case, the e-mail includes
an XML document attachment describing the time-off request and contains a link to a
JSP page where the request can be approved or rejected.
Reassigning Tasks
Reassigning a task is as simple as changing the assignee field in the task document and
then invoking the updateTask operation on the TaskManager service. A code
example of this is shown in the "Enabling Expiration/Timeouts for Tasks" on
page D-15. If the application requires that once a task is reassigned it cannot be
completed by the original assignee, then the user interface that completes a task must
first fetch the task document and check that the assignee has not changed before
completing a task.
Assigning Tasks to Groups and Resolving Roles
The TaskManager service has a very simple construct for the assignee attribute of a
task: it is a string identifier that is not interpreted by the TaskManager service to have
any special meaning. Although simple, this construct is powerful and flexible. In
particular, it allows for role resolution and the concept of group worklists to be
implemented in a straightforward manner.
When a task is assigned to a group, this typically means that several users can see the
task in their worklists. When one of them selects the task on which to work, it
disappears from the worklists of the other users in the group. Additionally, it is
common to set up a timeout period such that if the individual working on the task
does not complete it within a specified time, it may revert back to group assignment
and then reappear on the group worklists.
The most common way to implement this use case with the TaskManager service is as
follows:
1.
The task is assigned to the group identifier.
2.
The worklist user interfaces for members of the group show all tasks assigned to
the group.
3.
When a user selects a task on which to work, it is checked to ensure it has not
already been reassigned. If not, it is reassigned to the individual’s user ID.
4.
Optionally, notifications and timeouts can be used effectively here.
Role resolution works in much the same way. Because special interpretation is not
given to the assignee for a task, the assignee can actually be a role, and resolution can
happen on the user interface side. Alternatively, it is fairly simple to integrate a BPEL
process with directory services such as LDAP and perform dynamic role resolution at
the time the task is created.
Summary
BPEL includes a TaskManager service that acts as an intermediary between BPEL and
a user interface for performing user tasks. This appendix discusses how to create a
User Task 2.0 Macro
D-17
Summary
partner link to the TaskManager service, and how to build a JSP user interface to view
task information and complete the task.
D-18
Oracle BPEL Process Manager Developer’s Guide
E
Deployment Descriptor Properties
This appendix discusses deployment descriptor preference properties and deployment
descriptor configuration properties.
This appendix contains the following topics:
■
Deployment Descriptor Preference Properties
■
Deployment Descriptor Configuration Properties
■
Summary
Deployment Descriptor Preference Properties
Preferences are simple name-value pair properties that are defined in the deployment
descriptor of a BPEL process, and which are accessed at run time by the BPEL process.
You can change the value of a preference from Oracle BPEL Console at run time,
without having to redeploy the BPEL process.
Preferences enable BPEL process designers to externalize literal values from a process,
enabling them to be altered without having to redeploy the entire BPEL process.
For example, if you design a process that automatically rejects expense requests that
exceed 1000 dollars, and business requirements later change so that the maximum
amount is increased to 1500 dollars, then you normally need to edit the process
definition and redeploy. By defining a preference for the maximum amount in the
deployment descriptor, the change can be performed at run time, without redeploying
the process.
Defining a Preference Property
You can define preference values at run time from JDeveloper BPEL Designer. Click
the Deployment Descriptor Properties icon shown in Figure E–1. This icon is located
just above and to the left of the Diagram View.
Figure E–1
Deployment Descriptor Properties Icon
Deployment Descriptor Properties
E-1
Deployment Descriptor Preference Properties
In the Deployment Descriptor Properties window, click the Preferences tab, as shown
in Figure E–2.
Figure E–2
Deployment Descriptor Preference Properties in Oracle BPEL Console
Click Create and enter a preference name. Edit the value in the Property Value field
and click OK. The change takes effect immediately. Preferences you create in this way
are reflected in bpel.xml, inside the preferences tag, as follows:
...
<preferences>
<property name="MAX_AMOUNT">1000</property>
<property name="DEFAULT_COSTCENTER">US23</property>
</preferences>
...
Updating a Preference at Run Time
You can update preference values at run time in Oracle BPEL Console, as shown in
Figure E–3. Select the process, then select the Descriptor tab to display the deployment
descriptor for the process, including any preferences. Update the preference value, and
click Update descriptor. The change takes effect immediately.
E-2 Oracle BPEL Process Manager Developer’s Guide
Deployment Descriptor Preference Properties
Figure E–3
Updating BPEL Process Preferences at Run Time
Getting the Value of a Preference within a BPEL Process
The value of a preference can be read by a BPEL process using the XPath extension
function ora:getPreference(String preferenceName). This function can be
used as part of a simple assign statement, used in condition expressions, or used as
part of a more complex XPath expression.
Encrypting a Preference Value
You can encrypt the contents of a preference property. Encryption uses DES with the
sunJCE security provider. The contents do not appear encrypted in JDeveloper BPEL
Designer