ActiveWebflow Designer User s Guide

Transcription

1 ActiveWebflow Designer User s Guide Version 1.5 Revised January 2005

2 ActiveWebflow Designer User s Guide Copyright 2005 Active Endpoints, Inc. Printed in the United States of America ActiveWebflow and Web References are trademarks of Active Endpoints, Inc. All other trademarks, registered trademarks, and services marks are the property of their respective company.

3 ActiveWebflow Designer User s Guide 1 Online Help Conventions Tips and Tricks 13 XML Syntax 23 Technical Support 24 Installation and System Requirements 24 Documentation Conventions 24 Chapter 1: Welcome to ActiveWebflow Designer About ActiveWebflow Designer 25 Working in the Eclipse Environment 27 Introducing Business Process Execution Language 28 A Little BPEL History 28 BPEL Resources 28 Links to BPEL4WS Specification 28 What is a BPEL Process? 29 BPEL Process Definition Elements 31 ActiveWebflow Feature Tour 32 Printing ActiveWebflow Designer User s Guide 33 Chapter 2: ActiveWebflow Tutorial Introduction to ActiveWebflow Tutorial 36 Tutorial Part 1: Starting a New Process 37 Tutorial Part 2: Planning and Designing a Process 41 Tutorial Part 3: Adding Web References 44 Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities 49 Tutorial Part 5: Adding Process Activities and Properties 56 Tutorial Part 6: Adding Fault Handling 63 Tutorial Part 7: Adding Compensation and Correlation 67 Tutorial Part 8: Simulating the Process 67 Tutorial Part 9: Deploying the Process 79 Version Chapter : 3

4 Tutorial Part 10: Running the Process on the Server 84 Tutorial Part 11: Debugging Your Process Remotely 88 Chapter 3: Using ActiveWebflow for the First Time Launching ActiveWebflow Designer 95 Using the Workspace to Store Projects 96 Creating Projects and Folders 97 Starting a New Process 98 Importing an Existing BPEL Process into ActiveWebflow 99 Using the ActiveWebflow Samples 99 Chapter 4: Getting Started in ActiveWebflow Designer About ActiveWebflow Designer and the Eclipse Workbench 101 Navigating Through ActiveWebflow Designer 102 Windows, Perspectives, Views, and Editors 102 ActiveWebflow Perspectives 103 ActiveWebflow Designer Perspective 104 BPEL File Navigator 104 Web References 106 Outline View 106 Properties View 107 Process Variables 107 Error Log 108 Problems View 109 Tasks View 110 Thumbnail View 111 Bookmarks View 111 Status Bar 112 ActiveWebflow Debug Perspective 113 Using the ActiveWebflow Process Editor 113 Process Editor Process Tab 114 Process Editor Fault Handlers Tab 114 Process Editor Event Handlers Tab 115 Process Editor Compensator Tab Version

5 Process Editor Source Tab 115 Using Process Editor Tool Palettes 115 Displaying Swimlanes 116 Setting Visual Properties and Using Your Own Library of Images 117 Adding Tasks and Bookmarks to the Process 120 Adding Comments to the Process 121 Tips for Designing on the Process Editor Canvas 122 Customizing the ActiveWebflow Perspective 122 ActiveWebflow Preferences 123 Auto Layout Preferences 124 Swimlane Appearance Preferences 124 Tasks and Problems Preferences 124 Add Task Tag 125 Additional Preferences 126 Accessing ActiveWebflow Online Help 126 Dialog Button 127 Image Location Dialog 127 Chapter 5: Web References What is a Web Reference? 129 Viewing, Adding, and Removing Web References 130 Viewing Key Elements of a WSDL Tree 130 Web References Toolbar Options 131 Adding a Web Reference 131 Removing a Web Reference 132 Viewing, Editing, and Resolving Web References 133 Refreshing Web References 133 Filtering the Web References View by Reference Set 134 Viewing WSDL Namespaces, Messages, Partner Link Types, and Schema 134 Using WSDL Operations in BPEL Activities 135 Creating a WSDL File with Extensions for BPEL 135 Using Sample Data for WSDL Messages 136 Creating a Sample Data File 136 Adding a Sample Data File in Web References 137 Version Chapter : 5

6 Selecting a Default Sample Data File 138 Viewing the XML Structure of a Sample Data File 138 Removing a Sample Data File 139 Selecting Sample Data From Web References 139 Finding Where a WSDL Component is Used 139 Using Web References Search 141 Validation Error Message Dialog 142 Viewing Sample Data File Errors 143 Chapter 6: Planning Your BPEL Process Using Top-Down or Bottom-Up Process Design 145 Using WSDL References for Efficient Design 146 Creating WSDL Extensions for BPEL 146 Starting a Process by Dropping an Operation onto the Process Editor 147 Importing WSDL Locations and Namespaces 147 Automatically Importing WSDL Location 147 Manually Importing WSDL Locations 148 Refreshing Imports 149 Deleting an Import 149 Namespace Prefix and Declaration 149 Deleting a Namespace 150 Understanding BPEL Process Structure and Properties 150 Process Element and Properties 150 Partner Links 152 Variables 152 Activities 153 Fault Handlers 153 Compensation Handlers 153 Understanding BPEL Process Lifecycle 153 Creating an Abstract vs. an Executable Process 154 Chapter 7: Partner Link Types, Partner Links, and Partners What are Partner Link Types, Partner Links, and Partners? 157 Partner Link Type Version

7 Partner Link 162 Partner Links and Endpoint References 163 Partner 163 Adding a New Partner 164 Deleting a Partner 165 Showing and Hiding Swimlanes 165 Showing and Hiding Lanes for Partner Definitions 165 Showing and Hiding Lanes for Partner Link Definitions 166 Exporting a Partner Link or Partner to an Abstract Process 167 Chapter 8: Creating an Activity Overview of Activities 169 Defining an Activity and Its Properties 170 Selecting Values for Activity Properties 172 Selecting Activity Labels 173 Standard Properties for Activities 174 Receive 175 Invoke 177 Reply 179 Assign 183 Tips for Copy Operations 186 Copy Operation Examples 186 Copy Operation Dynamic Endpoint Reference Example 188 Throw 189 Terminate 191 Wait 192 Empty 194 Compensate 195 Creating a Custom Activity 197 Creating an Activity by Starting with a Web Reference 198 Using the Expression Builder 200 BPEL Functions 202 String Functions 202 Number Functions 204 Version Chapter : 7

8 Boolean Functions 204 Node Set Functions 205 Example Expressions 207 Using the Query Builder 207 Creating a Join Condition for an Incoming Link 209 Deadline and Duration Expressions 210 Chapter 9: Structuring Activities Different Ways of Structuring Activities 212 Defining a Container and its Branches and Properties 212 Defining Container Branches 213 Defining Container and Branch Properties 213 Sequence 215 Flow 216 While 218 Pick 219 Switch 221 Scope 224 Using Variable Access Serializable in a Scope 226 Lifecycle of a Scope 227 Selecting Activities for Containment 227 Chapter 10: Using Variables Overview of Variables 229 Adding a Variable 230 WSDL Message Types 231 XML Schema Simple Type 232 XML Schema Element 232 Viewing Variables 233 Quick View of Variables Used in Activities 233 Using the Process Variables View Options 234 Opening a Variable to View its Definition 234 Understanding Icons, Symbols, and Descriptions of Variable Parts 235 Deleting a Variable Version

9 Using Sample Data 236 Finding Variables Where Used 238 Using Variables in a Copy Operation 239 Creating a Copy Operation Using a Context Menu 239 Creating a Copy Operation Using Drag and Drop 240 Selecting a Copy Operation to Edit 241 Using Variables Based on WSDL Fault Messages 241 Chapter 11: Using Links What is a Link? 243 Adding a Link Between Activities 244 Adding a Link with no Transition 244 Adding a Link with a Transition Condition 245 Using the Add Link Dialog 245 Link Examples 246 Execution Rules for Links 248 Designing With Links vs. Structured Activities 248 Links and the Join Condition 249 Chapter 12: Compensation What is Compensation? 251 Compensation Handlers and Compensate Activities 253 Default-Order Compensation Example 254 Specified Compensation Example 255 Adding a Compensation Handler to a Scope 255 Compensating an Invoke Activity 256 Enabling Instance Compensation 256 Chapter 13: Correlation What is Correlation? 257 What is a Correlation Set? 258 WSDL Syntax for Property Names and Aliases 260 Global and Local Correlation Sets 260 Creating Message Properties and Property Aliases 261 Version Chapter : 9

10 Creating a Message Property Definition 261 Creating a Message Property Alias 262 Adding a Correlation Set 264 Deleting a Correlation Set 265 Adding Correlations to an Activity 266 Initiating and Setting Patterns for Correlation 267 Adding Correlation to a Receive, Reply, or OnMessage 268 Adding Correlation to an Invoke Activity 269 Adding Missing Correlation 270 Rules for Declaring and Using Correlation Sets 271 Chapter 14: Event Handling What is Event Handling? 273 Adding Event Handlers 274 Adding an OnMessage Event Handler 274 Adding an OnAlarm Event Handler 277 Processing Rules for Events 280 Chapter 15: Fault Handling What is BPEL Fault Handling? 281 Defining Catch and CatchAll Fault Handlers 282 Fault Handling for Service Invocations 284 Adding a Fault Handler 285 Adding a Fault Handler for the Process 286 Adding a Fault Handler for a Scope 287 Adding an Inline Fault Handler for an Invoke Activity 288 Fault Handling Processing Rules 289 Tips on Fault Handling 291 Chapter 16: Simulating and Debugging What is the ActiveWebflow Debug Perspective? 293 Opening the ActiveWebflow Debug Perspective 294 Switching Between ActiveWebflow Perspectives 294 ActiveWebflow Debug Perspective Views and Menus 295 Using the ActiveWebflow Debug View Version

11 Using Breakpoints in BPEL Process Simulation 297 Using the ActiveWebflow Debug Console 299 Simulating Execution of a BPEL Process 301 Prerequisites for Simulation 301 Starting and Ending Simulation of a BPEL Process 301 Running to a Breakpoint in a BPEL Process 303 Stepping to the Next Activity in a BPEL Simulation 304 Viewing the Execution State of an Activity or Link 305 Modifying a BPEL Process During Simulation 305 Terminating and Removing BPEL Process Simulations 305 Clearing the Process Execution State 306 Using and Inspecting Sample Variable Data During Simulation 307 Setting up Sample Data Values for Input, Output, and Fault Messages 307 Inspecting Process Variables during Simulation 309 Selecting Simulation Paths and Properties 310 Simulating Event Handlers 311 Simulating Fault Handlers 312 Inspecting Standard Faults During Simulation 312 Simulation Preferences 313 Disable bpws:selectionfailure Fault Example 314 Auto Create Target Path for Copy/To Example 315 Disable bpws:selectionfailure Fault and Auto Create Target Path for Copy/ To Example 317 Setting Debug Preferences 318 Debugging Remote Processes Running on the Server 319 Configuring a Remote Process Connection 320 Selecting Processes for Remote Debugging 322 Setting Breakpoints on a Process for Remote Debugging 324 Using the Debug View, Process Editor, and Variable View for Remote Debugging 324 Remote Debugging Preferences 326 Selecting a Launch Configuration from the Toolbar 327 Checking for an Out of Sync Process 327 Server Interactions During a Remote Debugging Session 328 Setting Options for Console Output 328 Version Chapter : 11

12 Chapter 17: Deploying Your Processes What is Deployment? 331 Preparing for Deployment 332 Preparing BPEL Files for Deployment 332 Selecting an ActiveWebflow Server Platform for Deployed Processes 332 Endpoint References and WS-Addressing Considerations 333 Endpoint References Requiring Credentials for Access 334 Overview of Process Deployment Steps 335 Creating a Process Deployment Descriptor File 336 Deployment Platforms 337 Partner Role Endpoint Types 339 My Role Binding, Service Name, and Allowed Roles Options 340 Selecting a Service for a Deployment Descriptor Partner Link 340 Editing a Process Deployment Descriptor File 341 Creating a Partner Definition File 344 Creating a Business Process Archive File 347 Using a BPRD Script to Regenerate and Deploy a BPR File 349 Deploying Your Process to the ActiveBPEL Server 350 Deploying Your Process to ActiveWebflow Enterprise or Standard 352 Deployment Complete 353 Starting the Server and Running a Process 354 What is Process Versioning? 355 Chapter 18: Creating and Using Custom Functions Custom Functions Technical Requirements and Sample Files 359 Adding Custom Functions to Expression and Query Builders 360 Specifying Custom Function Simulation Setup 362 Adding Custom Functions to the ActiveWebflow Server 364 Appendix A: BPEL Standard Faults 12 Version

13 Online Help Conventions XML Syntax Tips and Tricks Documentation Conventions How Do I Get Started? Spend about 30 minutes with a hands-on tutorial that guides you through process creation, simulation, deployment, and remote debugging. Read the ActiveWebflow Online Help Welcome for a tour of ActiveWebflow features I ve Already Got BPEL Processes. What Do I Do First? See Importing an Existing BPEL Process into ActiveWebflow I Don t Have Any WSDL Files. What Do I Do? Version 1.5 Online Help Conventions 13

14 Use the tools palette of the Process Editor to diagram and annotate a BPEL process without using any WSDL files. This technique is good for a top-down design. However, a WSDL file is required in order to create a valid BPEL process. The WSDL definition must include a target namespace, types, messages, and port types. It must also include partner link types, which ActiveWebflow can add for you. To deploy a BPEL process, you must also include binding and service location details in the WSDL. Look in the Samples\Other Samples\ WSDL folder for examples. Jump-Start a New BPEL Process with Web References TM Add a WSDL file to Web References before creating any BPEL activities. ActiveWebflow catalogs WSDL for automated activity creation. 14 Online Help Conventions Version 1.5

15 If you have several WSDLs, or one main WSDL that imports other WSDLs, be sure to add all the WSDLs to Web References. Display Partner Link Type View. Tip: If no partner link types exist, create them, as described in the next tip. Partner link types are required BPEL extensions to a WSDL definition. Drag an operation to the Process Editor canvas to start the activity wizard. Create Partner Link Types Add a WSDL file to Web References. Expand a port type that contains the operation you want to invoke, receive from, or reply to. Drag an operation to the Process Editor canvas to start the partner link type wizard. Version 1.5 Chapter : 15

16 Create Message Properties and Property Aliases Message properties are WSDL extensions for BPEL that allow you to correlate messages for a long-running, asynchronous process. Select Add Correlation Set to create message properties and property aliases. After you create message properties and property aliases, they are added to Process Variables and WSDL files. Then you can create correlation sets. Add a correlation set to each activity that should correlate messages. Filter Web References with Reference Sets Create a set of Web References to filter the view. Reference sets heighten your efficiency when you are working on one project at a time. 16 Tips and Tricks Version 1.5

17 Use the Convenient Repository of Sample Data Add a WSDL file to Web References. From the drop-down arrow, View Messages. Right-mouse click on a message part and add sample data: instance documents for a complex type or values for a simple type. Create the instance documents outside of ActiveWebflow. Data is automatically loaded into process variables for use during simulation of process execution. Data is available for reuse with other processes. Add the Target Namespace to a BPEL process manually If you start a process with a Web Reference, the target namespace is automatically added. Manually add a target namespace in the Outline view by rightmouse clicking Imports and selecting Add Import. Version 1.5 Chapter : 17

18 Customize BPEL Process Settings ActiveWebflow has extensive settings for global customization of BPEL processes. Set preferences for all processes, such as suppressing join failure and providing a default target namespace. Override the defaults for individual processes as needed. See ActiveWebflow Preferences for details. Create Variable Assignments Automatically Drag a like-typed process variable or variable part onto another process variable to automatically create a Copy operation. Blue color and from/to arrows differentiate variable parts in use. Process Viewing Tips 18 Tips and Tricks Version 1.5

19 Use Thumbnail view to select and pan a section of the process. To display the Thumbnail view, select Window> Show View>Thumbnail View a process full screen by double-clicking the process s titlebar. To view process properties and to activate the main toolbar, click anywhere on the Process Editor canvas to put it in focus. Significantly Shorten Design Time with BPELets Version 1.5 Chapter : 19

20 Save any BPEL activity or set of activities as a BPELet -- a custom activity. Drag a BPELet from the Custom palette to the canvas for any process. Discover and Fix Problems with Automatic Task Creation Save your BPEL file and then view a list of tasks for invalid activities. Complete the task, and it automatically disappears. Activity Creation Tips Add a link between activities by selecting the source activity and then selecting the target. Select Link Activities from the right mouse menu. 20 Tips and Tricks Version 1.5

21 Contain a group of activities in a Scope, Sequence, or While by selecting them and then right mouse clicking on Create Container. Add an Assign then add/edit copy operations the Assign by double-clicking the activity or by selecting from the right mouse menu of the activity. Add fault handling to an invoke or scope by selecting Show Fault Handlers. Version 1.5 Chapter : 21

22 Note that a fault activity is in a catch container. A catch container is inside a fault handler. The activity, catch, and fault handler are separately selectable. Synchronize Variables in Scopes If your process has two scopes inside a flow, make them variable access serializable. This is especially important if the scope has OnMessage event handlers using shared variables. Press F1 for Context Help on Dialogs For help on the dialog or view in focus, press the F1 key. Tip: If no help appears, try clicking within a text box on the dialog before pressing F1. 22 Tips and Tricks Version 1.5

23 Starting the ActiveBPEL Server For remotely debugging your processes, complete the deployment steps and then start the server engine. Starting the server: [ActiveWebflow install folder\server\activebpel_ Tomcat\bin\startup.bat Start the server by double-clicking Viewing the server Administration Console: startup.bat in the Server\ActiveBPEL_ Tomcat\bin folder. View the ActiveBPEL Administration Console by typing the console URL in your browser. XML Syntax Table 1 lists the symbols and their meaning for Business Process Execution Language (BPEL) XML syntax. The symbols indicate the allowable code according to the BPEL schema. For more information on the schema, see BPEL Resources. Table 1: BPEL XML Syntax and Examples Symbol Meaning Example + One or more of this element is allowed <correlation set= ncname initiate= yes no?>+? Zero or one element is allowed abstractprocess= yes no? * Zero or many of this element is allowed <onalarm (for=duration-expr until= deadline-expr )>* Version 1.5 Chapter : 23

24 Technical Support Active Endpoints, Inc. provides the following support options for ActiveWebflow Professional: Registered users may obtain free support by visiting the forums at forums.active-endpoints.com Purchase incident support. See the Active Endpoints Web site for details. Installation and System Requirements For installation, system requirements, and other late-breaking help topics, please review the ActiveWebflow Professional Release Notes in the ActiveWebflow Professional installation folder. Documentation Conventions Table 2: The following table describes the documentation conventions used in the content. Convention Bold Code Description Indicates names of buttons, check boxes, menus, menu choices, and tabs Indicates Business Process Execution Language code or commands you type 24 Technical Support Version 1.5

25 1 Welcome to ActiveWebflow Designer What s in this chapter About ActiveWebflow Designer Introducing Business Process Execution Language Links to BPEL4WS Specification What is a BPEL Process? BPEL Process Definition Elements ActiveWebflow Feature Tour About ActiveWebflow Designer The ActiveWebflow product family is built from the ground up to support the creation, testing, deployment and execution of composite software applications. In contrast with monolithic systems architectures of the past, composite applications are based on a services-oriented computing model. The interfaces to all application components are described using standard services conventions (in particular, Web Services Description Language, or WSDL), and then components are woven into coherent process "compositions". The goal of composite applications is to deliver an information architecture that is highly adaptive to evolving user needs. A hypothetical process composition might automate purchase order management: Receive and validate a purchase order Access an Accounts Receivable function to perform a customer credit check Access a database to check on-hand inventory Access an Order Entry transaction Send a purchase order confirmation/rejection Version 1.5 Chapter 1: Welcome to ActiveWebflow Designer 25

26 Until recently, the information technology community has lacked the necessary standards and technologies to build composite applications such as the one above in an efficient, repeatable, scalable manner. A critical standard has recently emerged to address many of these challenges: Business Process Execution Language (BPEL). In a nutshell, BPEL defines the standard constructs and semantics required to implement complex services-oriented application compositions. Although BPEL is a very rich notation for describing process compositions, it is arduous and error-prone to write by hand. Fortunately, you do not have to! Using ActiveWebflow, you can build, test and deploy standard, BPEL-based process compositions quickly and easily. ActiveWebflow s visual interfaces allow you to focus on describing the "big picture" of your applications, not the coding minutia. ActiveWebflow automatically handles all of the BPEL coding chores for you. And once you have defined your BPEL processes, ActiveWebflow allows you to visually simulate their execution using your own sample data. Using ActiveWebflow, you can define sophisticated, bullet-proof process compositions in the shortest possible time frames. ActiveWebflow Designer (Designer, for short) is a visual environment for creating, testing and deploying BPEL-based process compositions. Designer frees you from the tedious, error-prone chores of writing BPEL by hand. Using Designer, you build processes by choosing partners, services and operations, and defining how data flows among those entities. As you organize icons on the Process Editor canvas, ActiveWebflow constructs valid BPEL (XML) for you. Here is a typical picture of an ActiveWebflow BPEL process. 26 About ActiveWebflow Designer Version 1.5

27 Here is a snippet of the BPEL code corresponding to the illustration above, as generated by ActiveWebflow Designer. Working in the Eclipse Environment The ActiveWebflow Designer is a plugin to the Eclipse integrated development environment. Eclipse is an open platform for tool integration built by an open community of tool providers. ActiveWebflow takes advantage of the Eclipse Workbench features to provide BPEL building capabilities. For more information about the Eclipse community, see Version 1.5 Chapter 1: Welcome to ActiveWebflow Designer 27

28 Introducing Business Process Execution Language Business Process Execution Language for Web Services (BPEL, for short) is a special-purpose XML notation for defining process compositions based on Web services protocols. The BPEL specification is an important standard in the Web service architecture. It describes process-specific language constructs and defines how disparate Web services can be composed into coherent information systems. BPEL builds upon other standards in the Web services architecture, most notably Web Services Description Language (WSDL). A Little BPEL History BPEL4WS primarily represents the merging of two earlier specifications (WSFL from IBM and XLANG from Microsoft), combining the best of both specifications. The conflicting elements of those earlier specifications have been resolved and merged into a graph-oriented process notation. The initial BPEL4WS specification was released in The specification is now under the stewardship of OASIS, a leading software industry standards organization. BPEL Resources The BPEL4WS specification is available on several Web sites. For current versions, refer to Links to BPEL4WS Specification. BPEL4WS depends on the following XML-based specifications: Web Services Description Language Version 1.1. See wsdl. XPath expression language. See XML Schema. See WS Addressing. See the WS-Addressing specification at the Web site of any of the specification s contributors, including IBM, BEA Systems, and Microsoft. Links to BPEL4WS Specification Also find the specification at: Introducing Business Process Execution Language Version 1.5

29 bpel1-1.asp What is a BPEL Process? A BPEL process is a collection of Web services whose interactions are choreographed in a defined manner. Each service is a "black box" that performs some type of processing that is needed by the process. Services can be highly granular (e.g., calculate a rate) or very large in scope (e.g., process an order). BPEL defines two primary types of processes: executable and abstract. An executable process exposes the details of the services that execute within that process. An abstract process only exposes the interface to the process itself, hiding the execution details from users of that process. In the supply chain example illustrated below, the Seller's process exposes services (Check on Supply, Check Customer Credit) that are executable by the Seller. However, the Seller will probably expose only the process-level interface to Buyers. Thus, the Seller's process is executable to the Seller and abstract to Buyers. To facilitate the semantic use of executable and abstract processes, BPEL also introduces process concepts called Partners and Partner Links. These concepts are described in more detail in other topics. Supply Chain Example In a typical supply chain, if you are the seller of goods, you might begin a business process by accepting a purchase order through an input message of a Web service. Then you would return an acknowledgement to the buyer if the order could be fulfilled. Here is a picture of the process. Version 1.5 Chapter 1: Welcome to ActiveWebflow Designer 29

30 After you send the acknowledgement, you could send other messages to the buyer, such as shipping notices and invoices. Because you want to have this type of interaction with the buyer for many purchase orders, as well as with other buyers, you build one business process, and it acts as a template for business process instances. The business process you build has a setting to "create an instance" so that each time a new purchase order arrives, you create a new process. The new process handles all the related interactions for it, keeping interactions separated for each purchase order for each buyer. The BPEL process definition uses as input the definitions from Web Services Description Language (WSDL) files. These files contain the interface information that can be shared with the outside world. A process developer selects information, such as port types, partner link types, and message variables to define the process steps, as shown in the following illustration. 30 What is a BPEL Process? Version 1.5

31 A BPEL process coordinates these interactions and composes them into a straightthrough or long-running flow. During execution, when exceptions occur, some activities may need reversal or undo, and a BPEL process provides the techniques for correlation, compensation, fault and event handling. BPEL Process Definition Elements The main sections of a Business Process Execution Language (BPEL) definition are shown in the following code sample. <process> <!-- Definition of roles of process participants --> <partners>... </partners> <!-- Data and state variables used within the process --> <variables>... </variables> <!-- Correlation comment --> <correlationsets>... </correlationsets> <!-- Exception management --> <faulthandlers>... </faulthandlers> <!-- Message and timeout event handler --> <eventhandlers>... </eventhandlers> <!-- Processing steps --> activities* </process> For details on each BPEL section, see Understanding BPEL Process Structure and Properties. Version 1.5 Chapter 1: Welcome to ActiveWebflow Designer 31

32 ActiveWebflow Feature Tour ActiveWebflow offers the following features. Simultaneously displayed diagrammatic and nized Outline view to see a hierarchical element structure of the Create a process diagrammatically on the canvas. Use the synchro- hierarchical view of process. Source view is also available to view BPEL 1.1 code that process ActiveWebflow generates. Process Editor Canvas Drag and drop icons onto a canvas to create a process. ActiveWebflow creates valid BPEL code and generates a task list for missing and invalid activity properties. Web References Add your WSDL files to the Web References view for automatic discovery and organization of all pertinent information stored in existing WSDL. Comprehensive searching is available to locate namespaces, messages, and other elements. Drag and drop operations to the Process Editor canvas for automated activity creation. Management of Sample Data Automatic Task Generation (static analysis) Create Partner Link Types Swimlanes Automatic Variable Assignment Expression and Query Builders Activity Properties Add sample data files for all WSDL messages for a convenient repository of test data across all processes using the messages. Add multiple files for various test scenarios. During simulation, test various execution paths using different data. ActiveWebflow generates a problem list for all incomplete or invalid BPEL constructs so that you can fix problems without hunting for them. This feature works on imported BPEL files as well as native ones. Add partner link types to an existing or new WSDL file by using the partner link type wizard. Partner link types are WSDL extensions required for BPEL processes. Visual display of each partner s role in the process to show a service is being invoked, received from or replied to. Export information to share with partners. Create Copy Operations automatically for new or existing Assign activities. Drag the Copy FROM variable to the Copy TO variable. Icons and colors indicate at a glance how a variable is used. ActiveWebflow gives you visual expression editing controls for building a wide range of scripts. In addition, you can readily extend ActiveWebflow's expression editor to include your own custom functions. Built-in BPEL functions are automatically added to expressions as appropriate. Required and optional activity attributes are grouped for easy selection in the Properties view. Pertinent selections are in drop-down lists. Add comments, if desired. Add correlation properties, compensation, and fault handling. Create BPELets to re-use Select one or more activities on the Process Editor canvas and save a selection of activities in them to the Custom Palette for later use. Significantly shorten design other processes time by reusing modular elements. 32 ActiveWebflow Feature Tour Version 1.5

33 Simulation and Debugging Process Deployment Simulate process execution using sample data. Set breakpoints, step through or run the process. Remotely debug a process running on the server. Deployment wizards guide you to provide endpoint references for services used in your process. A process deployment descriptor provides error-free techniques for binding your services. Process are automatically deployed to the appropriate server location within a package that contains all required files. Printing ActiveWebflow Designer User s Guide The ActiveWebflow Designer User s Guide is available as a PDF file. To open and print the guide, select the Windows Start menu. Then select All Programs>Active Endpoints>ActiveWebflow Professional>ActiveWebflow User Guide. Version 1.5 Chapter 1: Welcome to ActiveWebflow Designer 33

34 34 Printing ActiveWebflow Designer User s Guide Version 1.5

35 2 ActiveWebflow Tutorial What s in this chapter Introduction to ActiveWebflow Tutorial Tutorial Part 1: Starting a New Process Tutorial Part 2: Planning and Designing a Process Tutorial Part 3: Adding Web References Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities Tutorial Part 5: Adding Process Activities and Properties Tutorial Part 6: Adding Fault Handling Tutorial Part 8: Simulating the Process Tutorial Part 9: Deploying the Process Tutorial Part 10: Running the Process on the Server Tutorial Part 11: Debugging Your Process Remotely The ActiveWebflow tutorial presents the how-to s and why-to s of creating, deploying, and debugging a Business Process Execution Language (BPEL) process using ActiveWebflow Designer. The purpose of the tutorial is to familiarize you with using ActiveWebflow and not to teach you the BPEL specification or the other specifications that BPEL relies on, such as the Web Services Description Language and schema. ActiveWebflow is rigorously based on the BPEL4WS 1.1 specification and schema. The product generates valid BPEL4WS 1.1 code for your process as it guides you with easy-to-use icons, wizards and dialogs to provide the right information. For an introduction to BPEL, refer to help topics in Welcome to ActiveWebflow Designer. Introduction to ActiveWebflow Tutorial The ActiveWebflow tutorial guides you through creating a Business Process Execution Language (BPEL) process, testing the process in simulation mode without Version 1.5 Chapter 2: ActiveWebflow Tutorial 35

36 deploying to an execution engine, deploying the process and using remote debugging capability of ActiveWebflow to graphically interact with your deployed process. You will create a loan approval process definition. The process describes the interactions among three participants, the control flow, and decisions based on exchanged data. It is based on a Web Services Description Language (WSDL) document that describes the messages and business operations used in the process. Note: The example process and WSDL file are taken directly from the code listed in the BPEL4WS 1.1 specification, but we made some modifications: The BPEL code has two invalid XML characters. We changed the < and > symbols used in a link transition expression to < and >. We have added the appropriate <binding> and <service> sections to the WSDL file so that you can deploy and run the process. Also, note that the loan approval WSDL file includes the required BPEL extension for partner link types, but not the optional property and property alias extensions required for correlation. When you have completed the tutorial you will have worked with most, but not all, of ActiveWebflow s capabilities. Be sure to see ActiveWebflow Feature Tour and Tips and Tricks for a discussion of product capabilities. The tutorial is divided into the following sections: Tutorial Part 1: Starting a New Process You will learn how to create the tutorial project, create and open a process document, and become familiar with the ActiveWebflow environment. Tutorial Part 2: Planning and Designing a Process You will learn how to use the Process Editor and graphical toolkit to develop the sample loan approval process BPEL definition. Tutorial Part 3: Adding Web References You will learn to add WSDL files to ActiveWebflow to make all pertinent partner link types, port types, roles, operations, and messages available for building processes. Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities 36 Introduction to ActiveWebflow Tutorial Version 1.5

37 You will learn the powerful shortcuts in ActiveWebflow to create Receives, Replies and Invokes in a process by starting with a WSDL operation. Tutorial Part 5: Adding Process Activities and Properties You will learn how to complete a process definition by adding an Assign, Copy Operation, links, link transitions, and namespaces. You will learn how to view your process in both a graphical and hierarchical view. You will learn how to create namespaces, variables, and activities manually, as an alternative to using the Operation Wizard. Tutorial Part 6: Adding Fault Handling You will learn how to catch errors sent to the process. Tutorial Part 8: Simulating the Process You will learn how to simulate execution of your process with sample data values. Tutorial Part 9: Deploying the Process You will learn how to create a process deployment descriptor file and package several files into a business process archive for deployment to the ActiveWebflow server. Tutorial Part 10: Running the Process on the Server You will learn how to deploy, run, manage, and test a process on the ActiveWebflow server. Tutorial Part 11: Debugging Your Process Remotely You will learn how to set up remote process launch configurations to debug a process running on the server. Tutorial Part 1: Starting a New Process You can use ActiveWebflow to design a process using top-down or bottom-up techniques. In the top-down technique, you sketch out your process by dropping down activities and creating links between them. You then add all the necessary information to bind the activities to an implementation and add decision-making to make your sketch a working process. In the bottom-up technique, you use the definitions of the implementation that are available when you begin process creation. This tutorial covers both design techniques. By completing Part 1 of the tutorial, you will be able to: Version 1.5 Chapter 2: ActiveWebflow Tutorial 37

38 Create the tutorial project Create a new process document Familiarize yourself with the ActiveWebflow tools that help you create a valid process When you are done, go to Tutorial Part 2: Planning and Designing a Process. Step 1: Create the tutorial project A project is a folder that contains folders and files. The default location for ActiveWebflow projects is in the Workspace folder of your install folder. When you create a new project in ActiveWebflow, it is also created in the same location in the file system. A project is a required container to store files. 1 Select File>New>Simple>Project and click Next. 2 Type in ActiveWebflow_Tutorial for a project name, as shown. 3 Click Finish. Your Navigator view should look like the following illustration. 38 Tutorial Part 1: Starting a New Process Version 1.5

39 Step 2: Create a new process file: 1 Select File>New>BPEL Process. 2 Select the ActiveWebflow_Tutorial folder, and in the file name field, type in tutorial for your BPEL file. The.bpel extension is automatically added. 3 Skip the Advanced settings. These settings override defaults that you can set in Preferences. 4 Click Finish. Your new file opens as a blank document in the Process Editor, as shown in the following illustration. Version 1.5 Chapter 2: ActiveWebflow Tutorial 39

40 You may notice an error message that says, No activity designated to create instance. This message is part of BPEL validation. You can ignore this message for now. Notice the following user interface features: 1 Process file are listed in the Navigator view. Double-click on a Navigator file to open it. You can drag BPEL files from the file system into a project. Select a file and drag it to the project filename. The cursor displays a + sign and you can drop the file into a project. 2 A newly created process file is opened automatically in the Process Editor. The Process Editor canvas is blank to begin with. When you open multiple files, they are displayed as different tabs. To switch between open files, click on a tab. 3 To create a process, you will use the palette. Each palette group contains a set of icons, such as the Activity group, displayed above. You can select a palette icon and drop it onto the canvas or draw links between objects. 4 The Properties view displays the attributes for the object in focus. In the illustration above, the tutorial.bpel process is in focus in the Process Editor. If a file is selected in the Navigator, a different set of attributes is displayed. 40 Tutorial Part 1: Starting a New Process Version 1.5

41 5 The tabs along the top of a view indicate that several views are stacked together. Select a tab to display a view. Tip: You can close (hide), minimize, maximize, move, and rearrange views as desired. Continue to Tutorial Part 2: Planning and Designing a Process. Tutorial Part 2: Planning and Designing a Process Tutorial Part 1: Starting a New Process covered creating a new project and a new BPEL file. By completing Part 2 of the tutorial, you will be able to: Understand the design of the loan approval process Understand top-down vs. bottom up design Use layout features of the Process Editor to optimize process display Review BPEL validation messages At the end of this tutorial part, you will understand the loan approval process we will build. Note: A completed file called loanapproval_tutorial_complete.bpel is located in the ActiveWebflow_Samples project in the ActiveWebflow Professional installation folder. The complete set of design and deployment files are available for you to simulate and remotely debug the process. What is the Loan Approval Process? The loan approval process starts by receiving a customer request for a loan amount. If the request is for less than $10,000, the assessor s Web service is invoked to assess whether the customer is a low or high risk. If the customer is low risk, the request is approved. Otherwise, the request is sent to the approver for review. If the amount is for $10,000 or more, the request is always sent to the approver for review. The customer can receive acceptance from the assessor or an accept/reject reply from the approver. A top-down design would begin by adding activities to the Process editor, without adding any valid attributes to them. A top-down design would look similar to this: Version 1.5 Chapter 2: ActiveWebflow Tutorial 41

42 This part of the tutorial familiarizes you with the Process Editor, demonstrating features you can use to create a top-down design. We will not create a complete top-down design. Step 1: Create a Receive activity A BPEL process begins by receiving an input message. This means a top-down design would start with either a Receive or a Pick activity, since they are structured to receive data from a business partner s Web service. 1 Ensure the tutorial.bpel file that you created in Part 1 is open in the Process Editor. 2 From the Activity palette, drag a Receive icon to the canvas. The activity is labeled with Receive. 3 Ensure that the Receive is selected. A selection box encloses it. When it is selected, the Properties view displays Receive attributes. 4 To make the activity name more meaningful, do one of the following: Click on the activity label Receive and type in ReceiveOrder. Do not use spaces in the name. or 42 Tutorial Part 2: Planning and Designing a Process Version 1.5

43 In Properties view, type in the Activity Name field, ReceiveOrder. The following example shows what your activity should look like. Step 2: Working with Layout Features in the Process Editor You can use several features in the Process Editor to optimize the display of your process. We will complete a short exercise to demonstrate the layout features. 1 From the Activity palette, drag an Empty activity to the canvas. 2 Try the following features by selecting them from the toolbar: Use Auto Layout to layout activities in a grid Select two or more activities and Align them Magnify the display area with Zoom For a complex process, display the Thumbnail view to select one area of your design to view. By default the Thumbnail view is closed. Open it from the Window>Show View command. 3 Delete the Empty activity. Step 3: Save the File and Review BPEL Validation Messages Take a moment to save your file. You will notice a change to your Receive activity icon. Also, some errors have been added to the Problems view, as shown. Version 1.5 Chapter 2: ActiveWebflow Tutorial 43

44 These errors are added to the Problems view by default when you save your file. They are messages pertaining to the validation of BPEL code generated for your process. You can see the BPEL XML code in the Source view of the Process Editor. The errors listed in Problems view will automatically disappear as we complete a valid BPEL process in the tutorial. Continue to Tutorial Part 3: Adding Web References. Tutorial Part 3: Adding Web References If you have not already done so, complete or review Tutorial Part 1: Starting a New Process and Tutorial Part 2: Planning and Designing a Process. In Part 2 of the tutorial, you learned how to create a top-down design by arranging BPEL activities on the Process Editor canvas. Now you will begin creating an executable process based on a WSDL file. In the Navigator view of ActiveWebflow, you should have the following: ActiveWebflow_Tutorial project tutorial.bpel that you created in Part 1 By completing Part 3 of the tutorial, you will be able to: Import a samples project containing a completed tutorial file and additional files needed in Tutorial Part 3. Add a WSDL file to your project Add the WSDL file as a Web Reference Use Web Reference view filters 44 Tutorial Part 3: Adding Web References Version 1.5

45 Step 1: Import the ActiveWebflow Professional Samples project The ActiveWebflow Professional Samples folder contains resources needed in the next part of the tutorial. Also, you can view a completed tutorial and other sample projects by importing the samples project. 1 Select File>Import. 2 Select Existing Project into Workspace, as shown, and click Next. 3 Browse to your ActiveWebflow Professional install folder and select Samples, as shown in the example. Click OK. 4 Click Finish. Your Navigator should look similar to the following example. Version 1.5 Chapter 2: ActiveWebflow Tutorial 45

46 Step 2: Add a WSDL folder to the ActiveWebflow_Tutorial project A Web Services Description Language (WSDL) file describes business operations that are invoked to carry out the activities of a BPEL process. WSDL files are required in order to create a valid executable BPEL file. A good practice is to include relevant WSDL files in your project so that you can easily deploy the files in the project to a deployment package. Normally you would create a project folder and import a WSDL file into it. We will take a shortcut for the tutorial. 1 Expand the Samples folder and select the Completed Tutorial folder. 2 Select the WSDL subfolder and select Copy from the right-mouse menu. 3 Paste the WSDL folder to the ActiveWebflow_Tutorial project. Your Navigator should look like the following example. 46 Tutorial Part 3: Adding Web References Version 1.5

47 Step 3: Add a Web Reference A Web Reference is a Web Services Description Language (WSDL) file or schema. By adding WSDL files and schemas to the Web References view, you have a convenient registry of namespaces, messages, type definitions, sample data, and other elements to use in your process definitions. In Step 1 you added the loanapproval.wsdl file to the project. Now you will add the WSDL file to Web References, a powerful registry. 1 Display the Web References view. This view is stacked next to the Navigator view. 2 Select the Globe icon on the Web References toolbar, as shown. 3 In the Add Web Reference dialog, select Browse Projects, as shown. 4 Expand the ActiveWebflow_Tutorial project, expand the WSDL folder, select loanapproval.wsdl, and click OK. Ensure you select the WSDL from ActiveWebflow_Tutorial project, as shown. Click OK again. Version 1.5 Chapter 2: ActiveWebflow Tutorial 47

48 Your Web References view should look like the following illustration. The file listed above is the WSDL file you will reference in your loan approval process, tutorial.bpel. Tip: When you add many Web References, rest your mouse on a Web Reference and use hover help to view location and namespace details for each WSDL, as shown in the example. 48 Tutorial Part 3: Adding Web References Version 1.5

49 Step 4: Use Web Reference view filters The Web References view displays WSDL definitions and schemas. This view provides a filter for viewing the various components of WSDL files. For example, you can view files according to namespaces, partner link types, or messages. 1 In Web References view, select View Partner Link Types from the dropdown arrow in the toolbar. 2 Expand the partner link type loanpartnerlinktype to display the request operation, as shown. Continue to Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities. Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities If you have not already done so, complete or review Tutorial Part 1: Starting a New Process, Tutorial Part 2: Planning and Designing a Process, and Tutorial Part 3: Adding Web References. In Part 2 of the tutorial, you added a BPEL assign activity on the Process Editor canvas. Now you will begin creating an executable process based on a WSDL file that you have added to Web References. In the Navigator view of ActiveWebflow, you should have the following: ActiveWebflow_Tutorial project tutorial.bpel that you created in Part 1 In Web References view, you should have loanapproval.wsdl that you added in Part 3. The Web References view should be set to Partner Link Types. Version 1.5 Chapter 2: ActiveWebflow Tutorial 49

50 By completing Part 4 of the tutorial, you will be able to: Create a Receive/Reply pair of activities by starting with a Web Reference operation Create Invoke activities by starting with Web Reference operations Step 1: Use the Operation Wizard to create a pair of Receive and Reply activities ActiveWebflow contains an Operation wizard that uses Web References to build a good chunk of a BPEL process automatically. It discovers the namespace, partner link type and message information required to create Receive, Reply and Invoke activities, that is, the Web service activities. The loan approval process needs four Web service activities: Receive. This activity receives the loan request message from a customer. Reply. This activity sends an approval message back to the customer. Invoke Loan Assessor and Invoke Loan Approver. We will describe and create these activities in the next step. 1 Ensure your file, tutorial.bpel, is open in the Process Editor. 2 Delete any activities that remain on the canvas, such as a Receive or Empty activity that you created in Part 2 of the tutorial. The canvas should be blank. 3 From Web References view, drag the request operation to the Process Editor canvas. As described in the last part of the tutorial, you can find the request operation by setting Web References to Partner Link Types view and expanding loan- PartnerLinkType. 4 In the Operation wizard, select the Receive-Reply option and click Next. A BPEL process must begin by receiving an input message. This means you must start with either a Receive or a Pick activity, since they are structured to receive data from a business partner s Web service. Since the loan approval process contains a Receive and matching Reply, you can create both activities at the same time. 50 Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities Version 1.5

51 5 Notice that the Operation wizard suggests loanpartnerlinktype for a partner link name. To make the name more meaningful, type in customer for the partner link, and click Next. A partner link describes the roles that a process and service can play as well as what data they can manipulate in that role. They are based on partner link types defined in a WSDL file. A business process can have many roles as it interacts with services, and each role is defined within a partner link. The customer role is defined in the loanapproval.wsdl file. Version 1.5 Chapter 2: ActiveWebflow Tutorial 51

52 6 Notice that the Operation wizard selects creditinformationmessage for the input variable name. This is the WSDL message used in the operation. To make the process variable name more meaningful, type in request, and click Next. A BPEL process receives, manipulates, and sends data through XML variables. Variables hold the messages exchanged between business partners as well as data used only within the process. 7 Name the output variable approval. 8 Click Finish. The Receive and Reply activities appear in the Process Editor. The activities have valid properties. The following illustration shows the activities and properties for the Receive created by the Operation wizard. 52 Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities Version 1.5

53 Step 2: Rename the Receive and Reply activities To make the activity names more meaningful, we will rename them. 1 Select the Receive activity in the Process Editor. 2 Ensure that the Properties view is in focus. 3 Look at the properties of the Receive activity. The required properties, partner link, port type, operation, and variable contain valid values from loanapproval.wsdl. 4 Rename the Receive. Either type ReceiveCustomerRequestforLoanAmt in the activity label on the Process Editor canvas or, in Properties view, type into the Activity Name field. Do not use spaces. 5 Select the Reply activity, and rename it AcceptMessageToCustomer. 6 In Properties view, scroll down to Label, and select Activity Type: Name. This step shows you that you can name activities in several ways. Step 3: Create the Invoke Loan Assessor Activity using the Operation Wizard The process requires invocation of two different Web services. Each Web service receives an input from the process and returns an output. Version 1.5 Chapter 2: ActiveWebflow Tutorial 53

54 1 In Web References - Partner Link Types view, expand the riskassessmentlink- Type and then expand assessor. 2 Select the check operation, as shown in the example. 3 Drag the check operation to the Process Editor. 4 In the Operation wizard, select Invoke for the activity type, and click Next. 5 Name the partner link assessor, and click Next. 6 The input variable to the loan assessor is request, so we will use the existing variable that was named in the Receive activity, as shown in the example. Click Next. 7 Create a new output variable named risk. 8 Click Finish. 9 Rename the Invoke activity InvokeLoanAssessor, as the example shows. 54 Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities Version 1.5

55 Step 4: Create the Invoke Loan Approver activity using the Operation Wizard 1 In Web References, expand the loanapprovallinktype partner link type. 2 Drag the approve operation to the Process Editor canvas. 3 In the Operation wizard, do the following: a Select Invoke for the activity type. b Create a partner link named approver. c Use the existing request and approval variables. 4 Rename the activity InvokeLoanApprover, as shown in the example. You should now have four activities on the Process Editor canvas, as shown. Version 1.5 Chapter 2: ActiveWebflow Tutorial 55

56 The Web service activities are in place, and you can continue to Tutorial Part 5: Adding Process Activities and Properties. Tutorial Part 5: Adding Process Activities and Properties You have now completed: Tutorial Part 1: Starting a New Process Tutorial Part 2: Planning and Designing a Process Tutorial Part 3: Adding Web References Tutorial Part 4: Using the Operation Wizard to Create Web Interaction Activities In the Navigator view of ActiveWebflow, you should have the following: ActiveWebflow_Tutorial project tutorial.bpel that you created in Part 4 By completing Part 5 of the tutorial, you will be able to: Use the Outline view to see your process in a hierarchical view Rename a namespace prefix Create an Assign activity and a Copy Operation for it Create links and link transitions using the Expression Builder Add a Create Instance attribute to a Receive activity 56 Tutorial Part 5: Adding Process Activities and Properties Version 1.5

57 Step 1: Use the Outline view to add and select building blocks The Outline view displays all major components of a BPEL process. The Outline view shown on the left is the default for a new process, containing only the parent nodes. Your Outline should look like the one on the right. By starting your process using Web References, you have automatically added the appropriate namespace, partner links, variables, and several activities. 1 In Outline view, select Partners. 2 Drag the Partners node to the bottom of the outline. The loan approval process does not include any partners, so you can move this node out of the way. Tip: You can move items up and down to reorganize them. You can rightmouse click on a node to add new items of the same type. Version 1.5 Chapter 2: ActiveWebflow Tutorial 57

58 Step 2: Rename a Namespace Prefix Each WSDL file declares one or more namespaces that provide a context for messages, port types, and other definitions. The namespaces that are declared in the WSDL files that your process references must also be declared in the process itself. Because one namespace can have many WSDL files associated with it, ActiveWebflow identifies the correct WSDL file by using the Imports function. The Operation wizard automatically added the import, and added a default namespace prefix, which you can rename to make it more meaningful. 1 In Outline view, expand Imports to see the location of the WSDL and namespace. 2 Expand Namespaces and select the ns1 namespace, which is the namespace the Operation wizard added. 3 In the Properties view, type lns (lns is short for loan namespace) in the Prefix field to provide a shortcut for the loan approval URI reference. Press Enter. Tip: All processes contain two common namespaces. The xsd namespace defines the location of the XML schema. The bpws namespace defines the location of the BPEL schema. Step 3: Use a Shortcut to Automatically Create an Assign Activity There is one more activity the process needs, an Assign. In the loan approval process, the assessor must assign a congratulations-type value to the approval message sent to the customer in the Reply. An Assign accomplishes this through a Copy Operation. Within the Process Variables view, you can create a Copy Operation automatically. The Copy Operation copies an expression ( yes ) to a message part (accept). 1 Display the Process Variables view, which is stacked next to Web References. 2 Right-mouse click the approval variable, and select Open. 58 Tutorial Part 5: Adding Process Activities and Properties Version 1.5

59 3 Right-mouse click the accept message part, and select Copy> To, as the illustration shows. Note: The Copy >To option means create the TO side of the Copy Operation. 4 In the Copy Operations dialog, complete the FROM part as follows: a Select Expression from the Type list. b Type in yes in the Expression field. 5 Click OK, and you will see a new Assign activity in the Process Editor. The activity is in the upper left corner, and you can move it below the Invoke Loan Assessor. 6 Rename the Assign as AssignYestoAccept. Version 1.5 Chapter 2: ActiveWebflow Tutorial 59

60 Tip: There are more shortcuts you can take when working with variables. Be sure to read the Using Variables section of ActiveWebflow Online Help. Step 4: Add Links for Sequencing Activities Depending on the loan amount in the request, either the loan assessor s Web service or the loan approver s Web service is invoked. Our process implements this logic by linking the Receive to both Invokes. Since the sequence is conditional, a transition condition will be added to both links in Step 5. 1 Select the Receive activity. 2 Select InvokeLoanAssessor. 3 Select the Link toolbar icon or select Link Activities from the right-mouse menu. 4 In Properties view, type in the Link Name field, receive-to-assess. 5 Repeat Steps 1-4 to create a link from the Receive to the Invoke Loan Approver activity, naming the link receive-to-approve. Step 5: Add a Transition Condition to Links 1 Select the receive-to-assess link in the Process Editor. 2 Double-click the link. 3 In the Transition Builder dialog, double-click the amount part of the request variable to add the appropriate expression to the Transition box. 4 Complete the expression as shown in the following example, and click OK. 60 Tutorial Part 5: Adding Process Activities and Properties Version 1.5

61 5 For the receive-to-approve link, add the expression as follows: bpws:getvariabledata('request', 'amount') >= 10000, and click OK. Step 6: Add links and link transitions for the Invoke activities The Loan Assessor returns a result of high risk or low risk for the customer. The process can assign the low risk message to a congratulations-type of reply to the customer or send a high risk message to invoke the Loan Approver for a full review of the customer. 1 Add a link from Invoke Loan Assessor to Invoke Loan Approver. 2 Name the link assess-to-approve. 3 Add a link transition for a high risk condition by creating the expression bpws:getvariabledata('risk', 'level')!= 'low' 4 Change the Link Router style to create a straight, rather than stair-step, link: Scroll down to the Visual settings. From the Link Router drop-down list, select Manual. Note that the Manual style lets you position the link transition (the diamond shape) at a selected angle as the example shows. Version 1.5 Chapter 2: ActiveWebflow Tutorial 61

62 5 Add a link between Invoke Loan Assessor and the Assign. Label the link assess-to-setmessage with a transition expression: bpws:getvariabledata('risk', 'level') = 'low'. 6 Link the Assign activity to the Reply activity, and link the Invoke Loan Approver activity to the Reply. Do not add any link transitions to these links. Your process should look like the following illustration. Step 7: Add a Create Instance property to the Receive activity The Receive is the activity that kicks off the process, so you must set the Create Instance property to Yes. 1 In the Process Editor, select the Receive activity. 2 In the Properties view, select Yes from the Create Instance drop-down. 62 Tutorial Part 5: Adding Process Activities and Properties Version 1.5

63 Step 8: Disable the Abstract Process setting and validate your process 1 Click on a blank part of the Process Editor to display the Properties view for the process. 2 In the Abstract Process property, ensure that No is selected from the dropdown list, as shown. 3 Save your file. 4 View Problems view, stacked next to Properties view. There should be no errors listed. If any errors are listed, double-click the error to go to the source of the error. You can also compare your file to loanapproval_tutorial_complete.bpel to discover any differences. You have completed the main process definition. Continue to Tutorial Part 6: Adding Fault Handling. Tutorial Part 6: Adding Fault Handling To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. Fault handling in a BPEL process is reverse work, undoing the partial and unsuccessful work of a scope in which a fault has occurred. When a fault occurs, normal processing is terminated, and control is transferred to the corresponding fault handler. So far in the tutorial, you have completed a BPEL process definition that contains all the steps for normal processing. Now you will add a fault handler to handle a service invocation fault. If the loan approval process throws a fault, it terminates the process via a standard fault, and turns over control to the fault handler activity. Version 1.5 Chapter 2: ActiveWebflow Tutorial 63

64 In the Navigator view of ActiveWebflow, you should have the following files: tutorial.bpel that you created in Part 2 loanapproval_tutorial_complete.bpel, a completed version of the file created in Part 2 By completing Part 6 of the tutorial, you will be able to: Add a fault variable Add a Catch fault handler for the process Add a fault handling activity to the Catch handler Step 1: Add a fault variable 1 In the Outline view, right-mouse click on Variables, and select Add Variable. 2 Fill in the Definition dialog as shown in the example: 3 In the Properties view, type error in the Name field. 4 The properties for the error variable should look like the following example: 64 Tutorial Part 6: Adding Fault Handling Version 1.5

65 Step 2: Add a Catch fault handler 1 Click on the Fault Handlers tab of the Process Editor. 2 Right mouse click on the canvas, and select Add Catch. 3 Select the catch handler (Ensure the selection box encloses the activity). 4 In the Properties view, select Fault Name, and click the Dialog Button at the end of the row. 5 Select the Fault Name, which is from the loanapproval.wsdl file, as shown in the example. 6 From the Fault Variable drop-down, select error, which is the Process Variable you created earlier. Version 1.5 Chapter 2: ActiveWebflow Tutorial 65

66 Step 3: Add a fault handling activity 1 From the Activity palette, drag a Reply activity into the Catch handler, as shown. 2 Fill in the properties for the activity to handle the fault, as shown in the example. You must select them in the following order: partner link, port type, operation, fault name, variable.) The process can now catch a fault from either the loan assessor or the loan approver service. This is because both services define the same fault message. For the loan approval process, it makes sense to add one fault handler to the process as a whole. As an alternative, we could have designed the process to include individual fault handlers for each invoke activity. Proceed to Tutorial Part 7: Adding Compensation and Correlation. 66 Tutorial Part 6: Adding Fault Handling Version 1.5

67 Tutorial Part 7: Adding Compensation and Correlation To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. Compensation is the process of reversing or providing an alternative for a successfully completed activity, especially when a fault occurs. Compensation restores data to what it was before the activity work was done. Correlation is a construct for keeping track of a group of messages that belong together in one particular business partner interaction. Correlation matches messages and interactions with the business process instances they are intended for. The loan approval tutorial does not require correlation or compensation. For more information, see Compensation and Correlation. Continue to Tutorial Part 8: Simulating the Process. Tutorial Part 8: Simulating the Process To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. If you have followed all tutorial parts so far, you have completed a BPEL process definition that contains all the steps for normal and fault processing. Now you will turn from the design phase to the testing phase by simulating execution of your process. In the Navigator view of ActiveWebflow, you should have the following files: tutorial.bpel that you created in Part 2 loanapproval_tutorial_complete.bpel, a completed version of the file created in Part 2 By completing Part 8 of the tutorial, you will be able to: Complete the prerequisite checklist for simulation Add sample data values for WSDL message parts Display data values for process variables Simulate execution of a BPEL process Test all execution paths in a process by overriding default data values Version 1.5 Chapter 2: ActiveWebflow Tutorial 67

68 Step 1: Complete the prerequisite checklist for simulation ActiveWebflow Designer validates your BPEL process before you execute it, adding validation tasks to the Problems view for you to complete. The tasks are broken down into errors, warnings, and information. You must ensure your process is executable, and you must complete all error tasks before running your process. 1 Open tutorial.bpel. 2 Ensure that the Abstract Process and Suppress Join Failure properties are set as follows: a Select Properties view. b Click on an empty part of the Process Editor (or select Process from the Outline view). c Set Abstract Process to No to indicate that the process should be validated for execution. d Click the Show Advanced Properties button in the Properties view toolbar, and ensure that Suppress Join Failure is set to Yes. This allows you to test various simulation paths without testing that all links to an activity are true. 3 Ensure that ActiveWebflow is reporting BPEL validation tasks, as follows: a b Select Window>Preferences>ActiveWebflow>Tasks and Problems. Enable all BPEL Validation problems, as shown. 68 Tutorial Part 8: Simulating the Process Version 1.5

69 4 In the Process Editor canvas, move an activity slightly. This action requires that your file must be saved. Save your file to ensure that all validation tasks appear in the Problems view. 5 Select Problems view. 6 If an error task exists, such as the one shown in the following example, correct the error, and save your file. Version 1.5 Chapter 2: ActiveWebflow Tutorial 69

70 Step 2: Add sample data values for message parts To simulate process execution, you need to initialize process variables. ActiveWebflow has a convenient way to provide default data values and ways to override the defaults for different test scenarios. When you add WSDL files to Web References, you can view a list of the defined messages, and then add sample data values for message parts. The sample data is available for all processes that use the messages. 1 Select Web References view. 2 From the Web References toolbar drop-down list, select View Messages. 3 Expand creditinformationmessage. 4 Select the amount message part, and from the right-mouse menu, select Add Sample. 5 Fill in the Add Sample Data dialog as follows: 6 Repeat steps 4 and 5 to add another sample data value of Expand the amount part. Right-mouse click on the sample data value of 9000 and select Default Sample. 8 Add a sample data value for each of the remaining two parts of creditinformationmessage: name and firstname. Your Web References view should look similar to the following example. 70 Tutorial Part 8: Simulating the Process Version 1.5

71 9 Continue adding sample data for the other messages, as follows: Message Part Value approvalmessage accept yes errormessage errorcode 1 riskassessmentmessage level low Your Web References view should look like the following example: Version 1.5 Chapter 2: ActiveWebflow Tutorial 71

72 10 Select the Refresh icon (double arrows) from the Web References toolbar. This action refreshes the contents of Web References and makes sample data available to process variables. Step 3: Display Data Values for Process Variables In Step 2 you added sample data to message parts, making the data available to all processes that reference the WSDL file. The data is used as the default initial values for process variables. As you run simulation, you can inspect process variables to view initialized and changed values. 1 Display the Process Variables view. 2 Select a variable, such as request, and from the right-mouse menu, select Open All. 3 From the Process Variables toolbar, select Show Variable Data. Your Process Variables view should look like the following example. Notice the following visual information cues in the Process Variables view: In the Process Variables list, boldface indicates an open variable 72 Tutorial Part 8: Simulating the Process Version 1.5

73 In the approval variable, the accept part is blue, indicating it is used in a copy operation of an Assign activity. The icon shows a small yellow arrow pointing inward, indicating the data is being copied TO the variable. Tip: There are more icons and symbols for complex schema and message-type variables. The tutorial process uses only simple message types. Step 4: Simulate Process Execution If you have completed all previous steps in this part of the tutorial, you are ready to begin simulating execution of your process. 1 Click on a blank part of the Process Editor canvas to activate the main toolbar. 2 Select the Start Simulation icon, as shown. 3 Notice the changes to the ActiveWebflow environment, as shown in the following example. Version 1.5 Chapter 2: ActiveWebflow Tutorial 73

74 1 The perspective switches to a debug perspective. 2 The beginning activity is highlighted 3 The current variable is highlighted 4 The sample data is cleared 5 The Debug view is opened to run and step through a process 6 The Console is opened to report simulation events 4 The debug perspective displays the Navigator tab the first time you select it. Select the Process Variables tab before proceeding. 5 In the Debug view, click the Step Over button to continue, as shown. 74 Tutorial Part 8: Simulating the Process Version 1.5

75 6 Step through your process, inspecting process variables as each activity is executed. The simulator stepped through the loan assessor path because the loan amount requested was less than $10,000. The Process Editor canvas should look like the following example when you are done. Step 5: Clear the Process Execution State 1 Click anywhere on a blank part of the Process Editor canvas. 2 On the main toolbar, click the Clear Process Execution State icon, which is next to the Start Simulation icon. Step 6: Override Default Values for Different Test Scenarios The simulation path went through the loan assessor s service using the default sample data value of To test the loan approver s path, do the following. Version 1.5 Chapter 2: ActiveWebflow Tutorial 75

76 1 Select the Receive activity. 2 In the Properties view, select Input Message, under the Simulation heading. 3 Click the button at the end of the Input Message row. 4 In the Set Simulation Data dialog, enable the check box for Override sample data for simulation. 5 In the amount row, click next to 9000, and then select the Dialog button. 6 In the Sample dialog, change the value to The Set Simulation Data dialog should look like the following example. 7 Rerun the process. Your simulation path should look like the following example: 76 Tutorial Part 8: Simulating the Process Version 1.5

77 8 Clear the process execution state. 9 Inspect the request variable in Process Variables view to see the data value used. 10 Inspect the Console to view all simulation events. 11 From the Debug view toolbar, select Remove All Terminated Launches. Step 7: Simulate Fault Handling In the loan approval process, a fault is thrown if the loan approver s service cannot handle the customer request. In Tutorial Part 6: Adding Fault Handling, you added a fault handler to catch this fault and send a reply containing an error code. We will simulate this. 1 On the Process Editor canvas, select the Invoke Loan Approver activity. 2 In Properties View, under Simulation, do the following: a b Set Result to Fault. Set Fault Name to loanprocessfault. 3 Start simulation and step through the process. 4 The simulator executes the fault handler, as shown. Version 1.5 Chapter 2: ActiveWebflow Tutorial 77

78 5 On the Process tab, the simulator shows activity termination with a fault, as shown. 6 View the Console to see execution path events. 7 Clear the process execution state. Tip: You can also simulate fault handling for the loan assessor service. The same fault message is defined for both the loan approver and the loan assessor service. To simulate fault handling for the loan assessor service, select the Invoke Assessor activity and set the Result property to Fault. Change the sample data value to be less than and re-simulate. Continue to Tutorial Part 9: Deploying the Process. Tutorial Part 9: Deploying the Process To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. 78 Tutorial Part 9: Deploying the Process Version 1.5

79 If you have followed all tutorial parts so far, you have designed and debugged a BPEL process. It is time to deploy the process to the ActiveWebflow Server. Deployment is the act of publishing your BPEL process to the ActiveWebflow Server where it can run. In the deployment procedure, you use the WS-Addressing specification to define where you want your endpoint references to come from. In the Navigator view of ActiveWebflow, you should have the following files: tutorial.bpel that you created in Part 2 loanapproval_tutorial_complete.bpel, a completed version of the file created in Part 2 By completing Part 9 of the tutorial, you will be able to: Complete the prerequisite checklist for deployment Create a process deployment descriptor file Create a workspace project to hold deployment files Create a business process deployment archive Deploy the business process archive to the server Step 1: Complete the prerequisite checklist for deployment A BPEL file is ready for deployment to the ActiveWebflow Server when there are no errors in the Tasks view and when a simulated execution of the process terminates normally. 1 Open tutorial.bpel 2 Simulate the process, as described in Tutorial Part 8: Simulating the Process, and test all execution paths. Step 2: Create a process deployment descriptor file A Process Deployment Descriptor (.pdd) file describes the relationship between the partner links defined in the BPEL file and the implementation required to interact with actual partner endpoints. You create a.pdd file to indicate where your endpoint references are. The.pdd file is an integral part of the deployment package for the process. Version 1.5 Chapter 2: ActiveWebflow Tutorial 79

80 Recall that the loan approval process has the following definitions for partner links: Table 3: Partner Link Name Partner Role My Role approver approver none assessor assessor none customer none loanservice You will assign an endpoint type for each partner role and will provide access protocol information for the process role (My Role). An endpoint type is a binding property that indicates the actual service the process interacts with. Different types give you control over specifying services you work with now and in the future. In this tutorial, you will indicate a static, hard-coded reference to partner services. 1 Select File>New>Deployment Descriptor to open the New Deployment Descriptor dialog as shown. 2 Do not change the Deployment Platform. ActiveBPEL Engine is the appropriate choice for this deployment. Select tutorial.bpel and click Next. 80 Tutorial Part 9: Deploying the Process Version 1.5

81 3 On the Configure process deployment page, select approver from the Partner Links list. 4 Select Static from the Endpoint Type list, as shown in the example. WS-Addressing is automatically added based on the binding information in the WSDL file. 5 Select assessor and then select Static as the Endpoint Type. 6 Select customer, and in the My Role panel, select RPC for the Binding style. 7 In the Service field, change the customerservice name to LoanService. 8 Leave the Allowed Roles field blank, and click Finish. The.pdd file opens in an editor, as shown in the following example. Version 1.5 Chapter 2: ActiveWebflow Tutorial 81

82 9 Close tutorial.pdd. Step 3: Create a new project folder for deployed files As a good practice, you will create a folder within your project to hold deployment files. 1 In the Navigator, select ActiveWebflow_Tutorial, and from the right-mouse menu, select New>Other. 2 Select Simple>Folder, and click Next. 3 Name the folder bpr, as the example shows. Step 4: Create a business process deployment archive and target deployment folder To deploy your process to the ActiveWebflow server, you must add all relevant files to an archive file (.bpr file), which is similar to a Web archive file. 82 Tutorial Part 9: Deploying the Process Version 1.5

83 1 Select File>Export>Business Process Archive File and click Next. 2 Select the tutorial.pdd file to include in the archive, as shown in the following example. 3 For the export destination BPR file, browse to the bpr folder and name the.bpr file tutorial.bpr. Your path should be similar to the following: ActiveWebflow Professional\Designer\workspace\ActiveWebflow_ Tutorial\bpr\tutorial.bpr 4 Select File in the Type field and in the Deployment location field, browse to the following location: \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bpr Selecting this option automatically deploys your.bpr file to the ActiveWebflow server upon completion of the export. Version 1.5 Chapter 2: ActiveWebflow Tutorial 83

84 5 Select the check box next to Save the archive specification..., and browse to the bpr folder. 6 Name the file tutorial.bprd. This file is an Ant script which you can run to re-deploy the bpr file whenever you modify a.bpel or.pdd file. 7 Select Finish. 8 To view the bpr and bprd files in Navigator, select File>Refresh. Continue to Tutorial Part 10: Running the Process on the Server. Tutorial Part 10: Running the Process on the Server To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. If you have followed all tutorial parts so far, you have deployed a BPEL process to ActiveWebflow Server. After deploying the process to the ActiveWebflow Server, you can run the process by sending in a loan amount request and getting back a response from the assessor or approver. You should have the following files in the following location: \\ActiveWebflow Professional Installation folder\server\activebpel_ Tomcat\bpr\tutorial.bpr This file is your deployment archive, which you copied to this location. \\ActiveWebflow Professional Installation folder\server\activebpel_ Tomcat\bin\startup.bat This start-up file is part of the ActiveWebflow installation. \\ActiveWebflow Professional Installation folder\samples\activewebflow_ Tutorial_Complete_Files\ActiveWebflow_Tutorial_test_page.war This file serves as a test page to send and receive messages to the process. \\ActiveWebflow Professional Installation folder\samples\activewebflow_ Tutorial_Complete_Files\ActiveWebflow_tutorial_client_config.xml This is a data file used by the test page. \\ActiveWebflow Professional Installation folder\samples\activewebflow_ Tutorial_Complete_Files\ActiveWebflow_Tutorial_web_services.wsr 84 Tutorial Part 10: Running the Process on the Server Version 1.5

85 This is a file used by the test page. By completing Part 10 of the tutorial, you will be able to: Add test files to the appropriate server folders Start the ActiveBPEL engine View the ActiveBPEL Administration Console Send a request to the process and receive a reply Step 1: Copy the test page and related files to required folders You must copy the test page to the server webapps folder and copy the sample data file to the server temp folder. 1 Copy \\ActiveWebflow Professional Installation folder\samples\activewebflow_tutorial_complete_files\activewebflow_tutorial_test_ page.war to \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\webapps. 2 Copy \\ActiveWebflow Professional Installation folder\samples\activewebflow_tutorial_complete_files\activewebflow_tutorial_ client_config.xml to \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\temp. 3 Copy \\ActiveWebflow Professional Installation folder\samples\activewebflow_tutorial_complete_files\activewebflow_tutorial_web_ services.wsr to \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bpr. Step 2: Start the server The ActiveWebflow Server consists of the ActiveBPEL engine running under Apache Tomcat Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies. 1 Double-click startup.bat, located in: \ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bin 2 Tomcat starts up in a command window, and the ActiveBPEL engine also starts. Version 1.5 Chapter 2: ActiveWebflow Tutorial 85

86 3 When startup completes with the message, ActiveBPEL engine started, minimize the command window. Step 3: View the ActiveBPEL Administrative Console When the ActiveBPEL engine starts, it scans the bpr folder for deployed processes. You can view a list of deployed processed. 1 Open your Web browser, and type the following URL into the Address field: 2 Your browser should look similar to the following example: 3 If there are no deployed processes, ensure that you have copied tutorial.bpr to the correct location, described at the beginning of this part of the tutorial. Step 4: Send a request to the process You can create an instance of the process by using the test client to initiate the Receive activity in tutorial.bpel. The test client returns a Reply. 86 Tutorial Part 10: Running the Process on the Server Version 1.5

87 1 Open a new instance of your Web browser. 2 Type the following URL into the Address field: 3 Your browser displays the test client from which you can enter values and receive a response, as shown in the following example: 4 Enter a value for the loan amount, such as If you deployed the loanapproval_tutorial_complete.bpr, in the URL field, change LoanService to LoanServiceComplete. 6 Select low for the Assessor reply. This means that the variable risk used in the Assessor invoke activity contains this value. 7 Select yes for the Approver reply. This means the variable approval used in both the Approver invoke and the assign activities contain this value. 8 Click Apply for a Loan to see the results. You can also debug your running or completed process from within ActiveWebflow Designer. To do so, go to Tutorial Part 11: Debugging Your Process Remotely. Version 1.5 Chapter 2: ActiveWebflow Tutorial 87

88 Tutorial Part 11: Debugging Your Process Remotely To start at the beginning of the tutorial, see Introduction to ActiveWebflow Tutorial. If you have followed all tutorial parts so far, you have deployed and run a BPEL process on the ActiveWebflow Server. Before starting this part of the tutorial, we recommend that you complete Tutorial Part 10: Running the Process on the Server. In part 10, you copied several files to the appropriate server folders. You should have the following files in the following server locations: \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\webapps\activewebflow_tutorial_test_page.war \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\temp\activewebflow_tutorial_client_config.xml \\ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bpr\activewebflow_tutorial_web_services.wsr In the Navigator view of ActiveWebflow, you should have the following files: tutorial.bpel that you created in Part 4 tutorial.bpr that you created in Part 9 By completing Part 11 of the tutorial, you will be able to: Add a breakpoint to tutorial.bpel Create a configuration file for launching a remote debugging session Start the server and instantiate your process Start a remote debugging session Step through your process and inspect variables Step 1: Add a breakpoint to tutorial.bpel You can connect to a running or completed process from within ActiveWebflow Designer for remote debugging. There are several options for remote debugging, and we will set a breakpoint in the process and then attach to the running process when the breakpoint is hit. 88 Tutorial Part 11: Debugging Your Process Remotely Version 1.5

89 1 Open tutorial.bpel in the Process Editor. 2 Right-mouse click on the Receive activity and select Add Breakpoint. The Receive activity should look like the following example. Step 2: Start the server The server must be running in order to start remote debugging, so start the server now (if it is not already running) before setting up a debug configuration. 1 If the server is already running, as described in Part 10 of the tutorial, you can skip to the next Step. 2 Double-click startup.bat, located in: \ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bin 3 Tomcat starts up in a command window, and the ActiveBPEL engine also starts. Minimize the command window when you see the message ActiveB- PEL engine started. Step 3: Create a configuration for launching a remote debug session A remote debug configuration indicates where processes are running and how you want to attach to them. 1 From the Run menu, select Debug. 2 In the Debug dialog, select New. 3 In the Name field, type tutorial_run_to_breakpoint. 4 In the Main tab, note that the default Server URL is displayed for deployed ActiveWebflow processes. Do not change it. 5 In the Process Selection panel, select Manual process selection or breakpoints. This selection indicates that you do not want to immediately debug a process, but rather will select a process manually. 6 Enable the option Attach to any process on breakpoint to indicate that a process containing a breakpoint will be attached to, if not already attached, when a breakpoint is hit. Your Debug configuration dialog should look like the following example. Version 1.5 Chapter 2: ActiveWebflow Tutorial 89

90 7 Select Debug to begin remote debugging for the current configuration. Your Debug view should look like the following example. Step 4: Instantiate the process You can create an instance of the process by using the test client to initiate the Receive activity in tutorial.bpel, just as you did in Part 10 of the tutorial. 1 Open a new instance of your Web browser. 2 Type the following URL into the Address field: 3 Your browser displays the test client from which you can enter values and receive a response, as shown in the following example: 90 Tutorial Part 11: Debugging Your Process Remotely Version 1.5

91 4 Enter a value for the loan amount, such as Ensure that the Operation is set to request. 6 Select low for the Assessor reply. This means that the variable risk used in the Assessor invoke activity contains this value. 7 Select yes for the Approver reply. This means the variable approval used in both the Approver invoke and the assign activities contain this value. 8 Click Apply for a Loan. Step 5: Begin remote debugging 1 In ActiveWebflow Designer, open all variables in the Process Variables view and position the view next to the Process Editor canvas. Your Process Editor should look like the following example. Note: If you receive a remote debugging error message from ActiveWebflow, it means that your workspace copy of the process file is missing. ActiveWebflow displays your local copy of the process while remote debugging. To correct the error, import tutorial.bpel into the ActiveWebflow_Tutorial project in the Navigator and re-instantiate the process. Version 1.5 Chapter 2: ActiveWebflow Tutorial 91

92 2 Notice that the running process is stopped on the Receive activity with the breakpoint, as we configured. 3 In Debug view, click the Step Over icon on the toolbar. The debug highlighter moves to the InvokeLoanAssessor activity. The request variable displays the data from the test client request. 4 Click Step Over to highlight the Assign. The risk variable contains the low value. Your Designer should look like the following example. 92 Tutorial Part 11: Debugging Your Process Remotely Version 1.5

93 5 Click Step Over to highlight the Reply. The debug highlighter moves through the Assign activity, and the accept part of the approve variable displays yes. 6 Click Step Over to terminate and disconnect the process automatically. 7 View the test client in your browser. It should look like the following example. 8 When you are done remote debugging, close the Tomcat command window. Version 1.5 Chapter 2: ActiveWebflow Tutorial 93

94 9 Switch out of the ActiveWebflow Debug perspective by selecting the ActiveWebflow Designer perspective icon from the Fast View bar on the left margin of the application window. 94 Tutorial Part 11: Debugging Your Process Remotely Version 1.5

95 3 Using ActiveWebflow for the First Time What s in this chapter Launching ActiveWebflow Designer Using the Workspace to Store Projects Creating Projects and Folders Starting a New Process Importing an Existing BPEL Process into ActiveWebflow Using the ActiveWebflow Samples Launching ActiveWebflow Designer To launch ActiveWebflow, double-click the program icon on the desktop, as shown. When you launch ActiveWebflow for the first time, all of the application s views are empty. The application looks similar to the following illustration. Version 1.5 Chapter 3: Using ActiveWebflow for the First Time 95

96 To get started, you must create a new project, and then either add a file to the project or import an existing project. For details, see Creating Projects and Folders. It is recommended that you create a new project in the workspace folder, which is the default location. For more information, see Using the Workspace to Store Projects. Using the Workspace to Store Projects The workspace is the folder on disk that contains all of your projects files, as well as meta-data such as preferences you may have customized. ActiveWebflow ships with no pre-defined projects and resources in the workspace. However, the Samples folder contains projects that you can import into ActiveWebflow Designer. All of the projects and files you create are added to the workspace folder and are displayed in the ActiveWebflow Navigator view. If you make a change to a file outside of ActiveWebflow, the change is reflected in Navigator. The path to the workspace is \\ActiveWebflow Professional\Designer\workspace. For more information, see: Creating Projects and Folders Using the ActiveWebflow Samples Importing an Existing BPEL Process into ActiveWebflow 96 Using the Workspace to Store Projects Version 1.5

97 Creating Projects and Folders You must create a project folder to store BPEL process files. A project maps to a folder in the file system. To create a new project: 1 Select File>New>Project>Simple, and click Next. 2 Type in a project name. 3 Do one of the following: Click Finish to create a project in \\ActiveWebflow Professional\Designer\workspace. This is the default location for projects. Deselect the check box next to Use default, and browse to a file system location to create a project. Click Finish when you are done. Note: If the file system folder you select contains subfolders, all subfolders become part of the project. Be sure to select Make New Folder and type in a folder name if you want an empty project, as the illustration shows. Note: You cannot create nested projects. Be sure that your projects do not overlap. 4 Your new project appears in the Navigator, and the folder in the file system contains a.project file. Version 1.5 Chapter 3: Using ActiveWebflow for the First Time 97

98 You can now create new BPEL process files. For information on creating a new BPEL process, see Starting a New Process. If desired, you can create project folders to organize your files. To create a project folder: 1 Select File>New>Other>Folder, and click Next. 2 Select a project. 3 Type in a folder name and click Finish. The following illustration shows an example of two folders that have been added to a project. Starting a New Process Ensure that at least one project is displayed in the Navigator before creating a new BPEL process. For details, see Creating Projects and Folders. To begin a new process: 1 Select File>New>BPEL Process. 2 Select your project folder, and in the File name field, type in a name for your BPEL file. The.bpel extension is automatically added. 3 Select Advanced to view properties that you can set for this process. The default values (for the check box properties) are shown and can be set for all processes in ActiveWebflow Preferences. In addition, you can set the process name, target namespace and other properties for this process later. See Process Element and Properties for more information. 4 Click Finish. Your BPEL file opens on the Process tab of the Process Editor. 98 Starting a New Process Version 1.5

99 Importing an Existing BPEL Process into ActiveWebflow If you have created a BPEL process outside of ActiveWebflow, we recommend that you follow the steps below before opening your BPEL file in ActiveWebflow. It is highly recommended that you add your WSDL files to Web References before opening your BPEL file so that ActiveWebflow can associate the WSDL files to your BPEL process and validate your BPEL process. 1 Select the Web References tab. For more information, see Web References. 2 Select Add Web Reference from the toolbar drop-down list, and add the WSDL files and schema referenced in your BPEL process. 3 Select the Navigator tab. 4 Select File>New>Project>Project, and click Next. 5 Type in a project name, and click Finish. 6 Select File>Import and import your BPEL file into the new project. 7 Use the Tasks view to correct any validation errors that occurred. Note: If you import your BPEL process before you add the referenced WSDL file to Web References, ActiveWebflow reports validation errors because it cannot locate an appropriate namespace for your process. You must manually add a namespace, as described in Manually Importing WSDL Locations. Using the ActiveWebflow Samples The samples included with ActiveWebflow are in a separate project folder outside of the workspace. You can import the Samples project into the file Navigator. The imported project is not copied to the file system workspace folder. It remains in the Samples folder in the file system. The samples include: Completed Tutorial. Contains complete versions of the BPEL, WSDL, and related files that you can compare to (or use instead of) your work when stepping through the ActiveWebflow Tutorial. ActiveWebflow_Tutorial_Complete_Files. Contains the deployment archive and test client, and services you can use to remote debug the tutorial BPEL process running on the ActiveBPEL server. Other Samples. Contains BPEL and WSDL files you can use as examples. Also contains the set of files needed to add custom XPath functions to your Version 1.5 Chapter 3: Using ActiveWebflow for the First Time 99

100 process for simulation and execution. For more information, see Creating and Using Custom Functions. To import the Samples project: Tip: This procedure is part of the ActiveWebflow tutorial. It is recommended that you step through the tutorial for a comprehensive introduction to ActiveWebflow Designer. For more information, see ActiveWebflow Tutorial. 1 In ActiveWebflow Designer, select File>Import. 2 Select Existing Project into Workspace, as shown, and click Next. 3 Browse to your ActiveWebflow Professional install folder and select Samples, as shown in the example. The Samples folder contains the.project file, which is needed in order to import a project. Click OK. 4 Click Finish. 100 Using the ActiveWebflow Samples Version 1.5

101 4 Getting Started in ActiveWebflow Designer What s in this chapter About ActiveWebflow Designer and the Eclipse Workbench Navigating Through ActiveWebflow Designer ActiveWebflow Perspectives ActiveWebflow Designer Perspective ActiveWebflow Debug Perspective Using the ActiveWebflow Process Editor Customizing the ActiveWebflow Perspective ActiveWebflow Preferences Accessing ActiveWebflow Online Help About ActiveWebflow Designer and the Eclipse Workbench ActiveWebflow Designer runs as a plugin in the Eclipse Workbench integrated development environment. Eclipse is an open platform for tool integration built by an open community of tool providers. ActiveWebflow Designer takes advantage of the Eclipse Workbench features to provide design, execution, and debug tools for its suite of products. If you have worked in the Eclipse Workbench before, you will notice that ActiveWebflow Designer is a standard plugin. If you are new to Eclipse, you will appreciate the flexibility and richness of the work environment. The following topics present a brief description of the ActiveWebflow Designer user interface elements. If you are new to Eclipse, you may also want to browse the Workbench User s Guide Help, which describes generic interface details. For more information, see Navigating Through ActiveWebflow Designer. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 101

102 Navigating Through ActiveWebflow Designer ActiveWebflow s user interface consists of various perspectives, with associated views, editors, and menus. Select an interface concept for more information: Windows, Perspectives, Views, and Editors ActiveWebflow Perspectives ActiveWebflow Designer Perspective ActiveWebflow Debug Perspective Using the ActiveWebflow Process Editor Windows, Perspectives, Views, and Editors The ActiveWebflow Designer uses the basic Eclipse Workbench user interface components: windows, perspectives, views, and editors. Each time you launch ActiveWebflow, the Workbench window opens and displays a default perspective. A perspective consists of views, editors, menus and toolbars that support a set of tasks. Each perspective has several views. A view is a unique window, designed for one task, such as displaying an XML tree, listing tasks, or showing object properties. Each view has its own toolbar. Each perspective also has an editing area where files are opened. An editor is associated with a file type and provides the appropriate file actions. The most common file type is a document which can be edited, but some file types require special actions, such as automatically generating BPEL XML code. Editors share the same real estate, and are stacked on top of each other when several files are open. Many editors have a marker bar where you can add bookmarks, tasks, and breakpoints, as appropriate. 102 Navigating Through ActiveWebflow Designer Version 1.5

103 Here are some tips for customizing your work environment: Table 4: Editor Tips View Tips Perspective Tips Double-click the titlebar to make the editor full screen Hide a view by right-mouse clicking on the view titlebar and selecting Fast View. The view is moved to the shortcut bar as an icon. Click the icon to open the view. Select Window>Customize Perspective to show and hide views Tile two or more editors by dragging one titlebar to the left edge of the editing area Rearrange views by moving and docking them and by rearranging their tabs. Open the same perspective in two windows by selecting Window>New Window ActiveWebflow Perspectives When you launch ActiveWebflow Designer, you see a default window appearance, called a perspective. A perspective consists of views, editors, menus and toolbars that support a set of tasks. A view is a unique window within a perspective, designed for one task, such as displaying an XML tree view of a file, listing errors or tasks, or showing object properties. ActiveWebflow Designer contains two default perspectives: ActiveWebflow Designer Perspective ActiveWebflow Debug Perspective Perspectives are versatile layouts that you can customize. See Customizing the ActiveWebflow Perspective for details. You can open and close perspectives using their icons on the Perspective Fast / View bar. The default position for the Perspective bar is top right. As the following illustration shows, you can dock the bar in another location, shown here on the top left. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 103

104 ActiveWebflow Designer Perspective The ActiveWebflow Designer perspective is the default product perspective and contains the views, editor, menus, and toolbars that support the tasks for designing and generating a BPEL process definition. Select a topic for more information on each view and editor in the perspective: BPEL File Navigator Web References Outline View Properties View Process Variables Error Log Problems View Tasks View Thumbnail View Bookmarks View Status Bar Using the ActiveWebflow Process Editor BPEL File Navigator The Navigator displays projects, folders, and files located in the ActiveWebflow workspace folder. You must create a project before creating a BPEL process. For details, see Creating Projects and Folders. 104 ActiveWebflow Designer Perspective Version 1.5

105 After you create or import projects and files, you can display the Navigator for a convenient view of files to work with in the Process Editor. The Navigator is a mirror of the file system Workspace folder. ActiveWebflow is installed with a project called Samples that is not in your workspace. You can import it into the Navigator. We recommend you store all files within workspace projects for easy access from within ActiveWebflow. Tips for using the Navigator: Add projects and files to the Navigator by dragging them in from the file system Import projects and files. For more information, see Importing existing projects and Importing resources from the file system in the Workbench User Guide Help. Copy and paste files from the file system Add files to the project workspace in the file system and then use the Refresh command to update the Navigator. For more information, see Workbench and Editing files outside the Workbench in the Workbench User Guide Help. Use the many tools in the Navigator to filter, show, hide, and navigate through files. For more information, see Navigator view in the Workbench User Guide Help. Web References For more information, see Web References. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 105

106 Outline View The Outline view displays all major components of a BPEL process, as shown. The nodes in the outline synchronize with the Process Editor and the Properties view. For example, select an activity in the Process node to display the highlighted activity on the Procerss Editor canvas. Tips for using the Outline view: Right-mouse click on an item to add new items of the same type Re-order items by moving them up and down Re-order variables to re-order them in the Process Variables view Delete items you are not using Double-click variables and other components to open the main property, such as the Definition dialog. 106 ActiveWebflow Designer Perspective Version 1.5

107 Properties View The Properties view displays names and values of properties of a selected resource. The following table describes the different uses of the Properties view. Table 5: Selected Resource Navigator file Process (open in the Process Editor or selected from Outline view) Process object: activity, link, fault handler, event handler, variable, correlation set Partner Link Partner Imports Namespace Web References Error Log, Problems view Properties File properties are displayed, such as size and date Process properties. These properties are attributes of the <process> element in a BPEL XML file. Required and optional BPEL properties, including visual and simulation properties. The properties are editable. Required and optional properties. The properties are editable. Also includes visual properties for Swimlanes. Optional properties. Also includes visual properties for partners. Required and optional properties Required and optional properties None None. Details are not listed in the Properties view. Double-click an error or problem to view details. Process Variables The Process Variables view displays a list of variables that you create or that are created when you drag and drop WSDL operations onto the Process Editor canvas. A BPEL process receives, manipulates, and sends data through XML variables. Variables hold the messages exchanged between business partners as well as data used only within the process. Use the Process Variables view to open individual variables to view their properties and to add sample data for use during simulation. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 107

108 Use the Outline view to create global or local variables. Global variables are available to the whole process and local variables are only available to process scope they are defined in. Error Log The Error Log displays details of any system errors. Active Endpoints can use this information for troubleshooting. In the default perspective, the Error Log is not shown. To open the Error Log, select Window>Show View>Error Log. The following illustration shows an example of the Error Log. 1 Export this log to a text file. Import an older Error log. 2 Clear the error log view, without deleting the contents of the log file 3 Delete the contents of the log file 4 Open this log in a text editor 5 Restore the log file display 6 Select filters for viewing event types, number of events to display and other criteria Tips for using the Error Log: Double-click an error to view the log and session information Right-mouse click an error to copy the log and session information The following illustration shows the event details view of an error. You may be asked to copy the information from this dialog to help Active Endpoints troubleshoot a problem. 108 ActiveWebflow Designer Perspective Version 1.5

109 Problems View The Problems view displays errors, warnings, and information related to the validation of your BPEL process. When you save your file, ActiveWebflow performs static analysis on the BPEL file. This analysis validates the BPEL definition, XPath syntax, and WSDL references of the process, and adds items for invalid activities to the Problems view. Before testing your process, you can correct invalid activities. As you correct errors and warnings, the related items in the Problems view disappear. You can also set a preference for level(s) of information you want to see in the Problems view. The following illustration shows several errors and one warning for BPEL processes in ActiveWebflow. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 109

110 Tips for using the Problems view: Double-click an item to go to the associated resource Right-mouse click an item to view property details or to select Go To resource Tasks View The Tasks view displays to-do items you add. Add an item from this view, or rightmouse click on an activity on the Process Editor canvas. The following illustration shows an example of the Tasks view. 1 Check box for to-do item, indicating complete or incomplete. Check the box when the item is complete. Click the column header to sort by completion. 2 Priority for to-do task, including high, normal, and low. Click the column header to sort by priority. 3 Add new to-do task and selected priority 4 Delete selected task 110 ActiveWebflow Designer Perspective Version 1.5

111 5 Filter task list display 6 Select Sort and Filter criteria Tips for using the Tasks view: Double-click a task to go to the associated resource Right-mouse click a task to view property details or to select Go To resource Thumbnail View If you design a complex process, it can outgrow the canvas display quickly. You can display the Thumbnail view to make navigation in a large process easier. The Thumbnail view shows a miniature representation of your process. The section of the process currently showing in the Process Editor is shaded by a blue box. To view another section of the process, click on the Thumbnail view shaded box, and move the box. The corresponding section of the process on the canvas is moved into view. The following illustration points out how to recognize the shaded box. To display the Thumbnail view, select Window> Show View>Thumbnail. Bookmarks View The Bookmarks view displays a list of bookmarks that you have added to a BPEL process or a service file. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 111

112 Add a bookmark to a BPEL activity or a service file to create an easy way to link back to the information. You can select a bookmark from the list and go to the place where you added the bookmark. In the default perspective, the Bookmarks view is not shown. To open the Bookmarks view, select Window>Show View>Bookmarks. The following illustration shows an example of the Bookmarks view. 1 Delete selected bookmark 2 Open the Filters dialog to select criteria to narrow the display of bookmarks 3 Select Sort or Filters criteria Double-click a bookmark to highlight its location on the Process Editor canvas. For more details on bookmarks, see the Workbench User Guide Help. Status Bar The Status Bar shows the information about current actions and error messages. The following illustration shows an example of an error message in the Status Bar. 112 ActiveWebflow Designer Perspective Version 1.5

113 ActiveWebflow Debug Perspective The ActiveWebflow Debug Perspective contains the views, editors, menus, and toolbars that support simulated execution and remote debugging of BPEL processes. For more information, see Simulating and Debugging. Using the ActiveWebflow Process Editor The Process Editor consists of a canvas and palette for creating a visual representation of a BPEL process. When you create a BPEL file, as described in Starting a New Process, the file opens in the Process tab of the editor, and you have a blank canvas on which to create a process. The following illustration shows the parts of the Process Editor. 1 Palette. Select activities, containers, and links to create a process definition. Annotate your process with drawing labels and shapes. Create custom activities to re-use in other processes. 2 Tabs. Select a tab to design a specific component of a process on its own page or to view the generated XML code in the Source tab. You can print the contents of each page. 3 Canvas. Drag palette items to the canvas. Set visual properties for the items and the canvas. Select a topic for more information: Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 113

114 Process Editor Process Tab Process Editor Fault Handlers Tab Process Editor Event Handlers Tab Process Editor Compensator Tab Process Editor Source Tab Using Process Editor Tool Palettes Displaying Swimlanes Setting Visual Properties and Using Your Own Library of Images Adding Tasks and Bookmarks to the Process Adding Comments to the Process Tips for Designing on the Process Editor Canvas Process Editor Process Tab From the Navigator you open a process file (a.bpel file), and the graphical representation of the process is displayed in the Process tab of the Process Editor. Use the Process tab to design your process, including all activities, links, and structures. Select objects from the Link, Activity, Container and Drawing palettes to design and annotate your process. Use the Fault Handlers and Event Handlers tabs to design handling of exceptional events at a process level. You can open as many.bpel files as you wish. Click on a file name in the Process Editor titlebar to display a specific process. You can print the graphical elements on this page. Process Editor Fault Handlers Tab Use the Fault Handlers tab of the Process Editor to design process-level fault handling. You can add catch and catchall containers and activities on this tab. These fault handlers are added to the <faulthandlers> section of the BPEL file. For more information, see Fault Handling. To add scope-level fault handlers, see Adding a Fault Handler for a Scope. You can add drawing labels to Fault Handlers. 114 Using the ActiveWebflow Process Editor Version 1.5

115 You can print the graphical elements on this page. Process Editor Event Handlers Tab Use the Event Handlers tab of the Process Editor to design process-level message and timeout events. For more information, see Event Handling. You can add drawing labels to Event Handlers. You can print the graphical elements on this page. Process Editor Compensator Tab Use this tab when you enable instance compensation for the process. For more information, see Process Element and Properties. Process Editor Source Tab Use the Source tab of the Process Editor to view the generated XML code for your process. The code you see is validated against the BPEL4WS 1.1 specification. Note: The Source view is for display purposes only. Using Process Editor Tool Palettes Use the Process Editor tool palettes to select and drag items to the canvas. The palettes are organized into groups of objects, including: Links and selections Activities Containers Other Drawing Custom Use a link to connect two activities to make them run in sequence. Use the other selection tools to select a set of items on the canvas. Select from the basic process activities to create a process. For example, select a Receive or Pick to begin the process. Select a container to structure a group of activities. For example, a Sequence is a container in which to add one or more activities. Select a special container. For example, select a catch all for a fault handler, or a case or otherwise for a switch activity. Add labels and shapes to the canvas. They are ignored in the XML code, but they print. Save any activity or set of activities from a BPEL drawing as a custom activity. You can reuse the custom activity in other BPEL drawings. By default, the custom palette is hidden when empty. You can customize the palettes in many ways. For example, you can view icons only, as shown in the following example. To view icons only, right-mouse click on any palette entry and select Layout>Icons Only. See the list of other tips below the illustration. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 115

116 Tips for using the palette: Right-mouse click on a palette group title to view a list of customization options Click on a palette group title to open or close the group Displaying Swimlanes A Swimlane is a view that shows a partner process correlated with your process. In essence a Swimlane displays a diagram that depicts the part of the partner s process which faces your process. For example, if your process has a Receive activity, then the partner process must have an Invoke activity that is initiating that Receive. The flip side is an Invoke activity to invoke a partner s Web service. In this case, the partner needs a Receive activity on the other side waiting for that message. For more details, see Showing and Hiding Swimlanes. The following illustration shows a Swimlane on the right and the relationship between partners. 116 Using the ActiveWebflow Process Editor Version 1.5

117 Tips for working with Swimlanes: By default, all Swimlanes are hidden You can show one or more partners You can change the default color of Swimlanes in Preferences To set Swimlane display preferences, see Swimlane Appearance Preferences. Setting Visual Properties and Using Your Own Library of Images For all of ActiveWebflow s activity icons, you can change the font size, colors, borders, and other visual properties. In addition, you can change the activity icons to impart more meaningful visual representation for the type of process you are building. Here are some examples. Example 1: Add a border, change font size for an activity. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 117

118 Example 2: Select your own images for activities by setting the Image Location property for each activity. Example 3: Change the link style from process default (Manhattan) to Manual. The manual style draws a straight link, rather than a stair-step style link, and allows you to set the angle for a link transition. 118 Using the ActiveWebflow Process Editor Version 1.5

119 The following table lists the visual properties you can set for an activity. Table 6: Property Description Basic Properties Border Border Color Custom Label Image Location Size to Fit Label Label Alignment Label Placement Yes/No selection to display a border on a drawing item Opens a dialog for you to choose a basic or custom color for the border of a drawing item Text you type in to display instead of activity type or name File system location and name of the image file. See the Tips section below for multiselecting activities to change their images. Set to Yes to restrict resizing of the selected drawing object. Select No to permit resizing of the drawing object. Select the display format for an activity label. See Selecting Activity Labels. Align text (left, right, center, top, bottom) Placement of text label relative to image Advanced Properties Primary Alignment Secondary Alignment Background Color Font Font Color Image Display Image Text Gap For a Sequence activity, sets the alignment for the group of activities For a Sequence activity, set the alignment position of the activities within the sequence. Fill color, if the Transparent property is No Font to use for label Color for labels The image to draw if any Select the size for the gap between an activity icon and the label Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 119

120 Table 6: Property Location Size Transparent Transparency Level Description The XY location on the canvas of the object The current size on canvas Yes/No setting. If you select No, you can set the Background color For drawing objects, set the value of transparency. A larger value decreases the tranparency. Tips for setting visual properties: To change the image for a group of activities, multi-select the activities and then select the Image Location. For example, select all Receives to change the icon for that activity type. To resize a container activity, such as a Sequence, set the Size to Fit option to No To set visual preferences, see Auto Layout Preferences. Adding Tasks and Bookmarks to the Process You can add a bookmark to a graphical element on the Process Editor canvas and create a link to easily jump back to that spot in the process. You can also add a task, which is similar to a bookmark. To add a task, highlight a graphical element and create a link to easily jump back to it. The difference between a task and bookmark is in the intent of the link. A task usually indicates something that needs to be done at that spot as opposed to just an easy link back to it. A task also has a priority to let you easily sort tasks by importance. To add a task or bookmark to a graphical element, select the element and rightclick. Select Add Bookmark or Add Task. Name the task or bookmark. The following illustration shows an example of a graphical element with a task or bookmark added. 120 Using the ActiveWebflow Process Editor Version 1.5

121 1 Receive activity with a task added 2 Receive activity with a bookmark added For more information, see Tasks View and Bookmarks View. Adding Comments to the Process You can add a comment to any element of the process, such as an activity, link, variable, or the process itself. 1 Select an item from the Outline view or the Process Editor canvas. For example: Select Process or a partner link, variable, or copy operation from the Outline view Select an activity or link on the Process Editor canvas 2 In the Properties view, at the end of the Comment row, click the Dialog Button. 3 Type in a comment in the Comment dialog and click OK. Tip: You can add a Task tag to the beginning of the comment and the comment appears in Tasks view. For details, see Tasks and Problems Preferences. The comments for activities and links appear when your mouse hovers over them on the Process Editor canvas, as shown. Comments appear as formatted tags in the Source view of your process. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 121

122 Note: If you want to add a comment about a namespace, add the comment to the process itself. Tips for Designing on the Process Editor Canvas Here are some tips for designing your process: Double-click the Process Editor titlebar to enlarge the canvas to full view Change the font size and color, borders, images and other properties for activities and links. See Setting Visual Properties and Using Your Own Library of Images. Use the Auto Layout toolbar button to arrange process activities according to the settings in Auto Layout Preferences Use Zoom In and Zoom Out on the Process menu to change magnification of the canvas Select a Zoom percentage or Fit Page from the toolbar Zoom drop-down Select two or more activities and link them using the Link toolbar button Use the Thumbnail View to view different parts of your process if it is large and complex Show Swimlanes to view partner interactions. See Displaying Swimlanes for more information. Select two or more graphical elements and align them using the toolbar Align drop-down Customizing the ActiveWebflow Perspective As you work on various parts of your BPEL process, you may need to hide some views, enlarge others, and change the tab order of others. The workbench environment that ActiveWebflow is built upon is very flexible and lets you do all of these things. For details, see Windows, Perspectives, Views, and Editors. 122 Customizing the ActiveWebflow Perspective Version 1.5

123 ActiveWebflow Preferences You can set default preferences for all processes, and then override a preference for individual processes. To set ActiveWebflow preferences, select Window>Preferences>ActiveWebflow. Preferences on the main page include: Target Namespace preamble Default settings for new process files: Suppress join failure Enable instance compensation Create as abstract process Launch primary property dialog after add Every BPEL process needs a target namespace. Type in a default namespace preamble, if desired. You can change the namespace and add additional ones for each new process you create. Enabled by default. For a description of this setting, see Process Element and Properties. Disabled by default. For a description of this setting, see Process Element and Properties. Disabled by default. For a description of this setting, see Process Element and Properties. In Outline view, you can right mouse click on a node, such as Imports, Partners, or Variables and add a new item. If you enable this option, you can right mouse click on the item to edit the primary property. For example, you can right mouse click on a partner to edit the partner link set. You can disable this option if you prefer to edit all the properties (not just the primary property) in the Properties view. Note: These settings take effect the next time you start ActiveWebflow Designer. You can set additional preferences for the following: Auto Layout Preferences Creating and Using Custom Functions Remote Debugging Preferences Simulation Preferences Swimlane Appearance Preferences Tasks and Problems Preferences Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 123

124 Auto Layout Preferences Select Window>Preferences>ActiveWebflow>Auto Layout to view these preferences. The main ActiveWebflow toolbar contains an Auto Layout button that organizes graphical elements on the process canvas into a grid that best fits the display area. On the Auto Layout page of ActiveWebflow Preferences, set the default values for laying out the graphical elements (e.g., activities and containers). Horizontal or vertical layout Size of margins for containers Spacing between levels and nodes Select the primary axis for your process diagrams Set the size, in pixels, for interior margins for scopes, sequences, and other containers Set the size, in pixels, for vertical (level) and horizontal (node) spacing between activities. Swimlane Appearance Preferences Select Window>Preferences>ActiveWebflow>Swimlane Appearance to view these preferences. On the Swimlane Appearance page of ActiveWebflow Preferences, you can define defaults for Swimlane appearance. Swimlane gap size and colors Link color default Link color follows border Link line style Set the gap size, in pixels, for the gap between each Swimlane. Select the background and border color. Set the color for the arrows (links) that connect process activities to partner activities. Check the check box to enable color coordination for Swimlane borders and links Select a line style for the arrows (links) that connect process activities to partner activities Tasks and Problems Preferences Select Window>Preferences>ActiveWebflow>Tasks and Problems to view these preferences. 124 ActiveWebflow Preferences Version 1.5

125 On the Tasks and Problems page of ActiveWebflow Preferences, you can enable settings for tasks that appear in the Tasks view and problems in the Problems view. Enable user-defined task tags Add a task tag Enable error problems Enable warning problems Select the check box to use your own tags for creating tasks Add a tag, and then use the tag in an activity s Comment dialog. The text is added as a Task in Tasks view. It is also part of hover help for the activity. For details, see Add Task Tag. ActiveWebflow provides two default with a Normal priority and TODO with a High priority. Select this check box to display all validation errors when you save your file. A validation error refers to an invalid BPEL element definition. For example, if you drag a Receive activity to the canvas without specifying the partner link, port type, operation, and variable, error problems are generated for each missing attribute. If you do not want to be reminded of problems you need to address, you can deselect this check box. Before simulating execution, be sure to enable error problems and make corrections. Select this check box to display all validation warnings when you save your file. A validation warning can refer to unused resources, such as variables and partner links, unsupported expression languages, or other potential errors. If you do not want to be reminded of warnings, you can deselect this check box. Note: If your processes use Correlation Sets, it is highly recommended that you enable warning problems. A warning problem appears if correlation is missing from activities that handle correlated messages. Enable info problemsselect this check box to display all information messages when you save your file. If you do not want to be reminded of information messages, you can deselect this check box. Add Task Tag Enter a name and set a priority for a tag. Use the tag as follows: 1 On the Process Editor canvas, select an activity. For example, select a Receive. 2 In Properties view, select Comment, and at the end of the row, select the Dialog Button. 3 In the Comment dialog, type in a tag and text. For Create sample data file for Input Message 4 Click OK, and notice that a new Task is added to the Tasks view. Also, the task appears as part of hover help for the activity as well as within <comment> tags in the source view. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 125

126 Tip: You can also add tasks by selecting Add Task from the right-mouse menu of an activity. The task is added to Tasks view, but does not appear in hover help or in process <comment> tags. Additional Preferences In addition to the general workspace preferences described in ActiveWebflow Preferences, refer to the following preference pages, described in other sections: Adding Custom Functions to Expression and Query Builders Remote Debugging Preferences Simulation Preferences Accessing ActiveWebflow Online Help ActiveWebflow has several online help features: Table 7: Help Feature Help menu Welcome page Tips and Tricks Help Contents F1 Help Hover Help Help Search Description Select the Help menu to view the Welcome page, Tips and Tricks, and Help Contents Provides getting started help for new users Provides productivity shortcuts Displays all help topics in an expandable/collapsible list Press F1 on any view or dialog box to view a context-sensitive help topic Rest your mouse on an item in a list, toolbar button, or graphical display to view property details Search for help topics by selecting the Search menu or toolbar icon The ActiveWebflow Designer User Guide is available as a PDF file. To open and print the guide, select the Windows Start menu. Then select All Programs>Active Endpoints>ActiveWebflow Professional>ActiveWebflow User Guide. 126 Accessing ActiveWebflow Online Help Version 1.5

127 Dialog Button In the Properties view, one of the Value choices for a property opens a dialog. For example, in a Copy Operation, you can create a complex expression with the Expression Builder dialog. You will notice in many procedures there is a reference to the Dialog Button which is shown in the following illustration. Image Location Dialog The Image Location dialog allows you to select an activity s display image from the file system or to select the activity s default image. Version 1.5 Chapter 4: Getting Started in ActiveWebflow Designer 127

128 128 Image Location Dialog Version 1.5

129 5 Web References What s in this chapter What is a Web Reference? Viewing, Adding, and Removing Web References Viewing WSDL Namespaces, Messages, Partner Link Types, and Schema Using Sample Data for WSDL Messages Finding Where a WSDL Component is Used Using Web References Search You can add files to the Web References view that make your design work faster and easier. What is a Web Reference? A Web Reference is a Web Services Description Language (WSDL) file or schema that you have added to ActiveWebflow. WSDL files are displayed by name in the Web References view. When you add a WSDL file to the view, it is available for all ActiveWebflow processes. By adding WSDL files and schemas to the Web References view, you have a convenient registry of namespaces, messages, type definitions, sample data, and other elements to use across BPEL processes. To make your work quick and easy, product wizards help you jump-start process design by automatically including the WSDL elements needed. Also, Web References has an extensive search capability. In addition, in the Web References view, you can add sample data files for message variables and make the data available for testing and debugging your process. To display WSDL files, click the Web References tab. The following illustration shows the default view of Web References in ActiveWebflow. Version 1.5 Chapter 5: Web References 129

130 WSDL files are XML-based files that contain the namespace declarations, type declarations, messages, and other element definitions that you can use to create business processes. WSDL files conform to the Web Services Description Language standard authored by a World Wide Web Consortium committee. ActiveWebflow supports Web Services Description Language (WSDL) 1.1, a W3C Note dated 15 March For more information about this standard, see Viewing, Adding, and Removing Web References You can manage Web Reference files as follows: Viewing Key Elements of a WSDL Tree Web References Toolbar Options Adding a Web Reference Removing a Web Reference Viewing, Editing, and Resolving Web References Refreshing Web References Filtering the Web References View by Reference Set Viewing Key Elements of a WSDL Tree The Web References view displays the names of WSDL files that you have added to the view. Because a WSDL file is an XML file, you can expand or collapse the file view in a tree structure to see elements. Web References displays the most relevant elements for process design. To display the WSDL file as an XML tree structure, click the plus sign next to the file name to show the elements in the file: 130 Viewing, Adding, and Removing Web References Version 1.5

131 Messages Port Types and Operations Partner Links, Roles, and Operations Message Properties and Property Aliases Bindings and Operations Service Names and Ports Web References Toolbar Options Use the toolbar options to add, remove, refresh and filter Web References, as the illustration shows. 1 Adding a Web Reference 2 Removing a Web Reference 3 Refreshing Web References 4 Viewing WSDL Namespaces, Messages, Partner Link Types, and Schema and Filtering the Web References View by Reference Set 5 Viewing, Editing, and Resolving Web References Adding a Web Reference Tip: Before adding a WSDL file to ActiveWebflow, copy the file to your \\ActiveWebflow installation folder\designer\workspace\bpel project folder, where you might also later add other related files for deployment to an ActiveWebflow server. To add a Web Reference: 1 In the Web References view toolbar, click the Globe icon with a plus sign. 2 In the Add Web References dialog, do one or more of the following: Version 1.5 Chapter 5: Web References 131

132 Select Browse File System to locate WSDL files or schemas on your computer or network Select Browse Projects to locate WSDL files or schemas you have added to a workspace project Type in an URL, such as the following example: 3 Select as many files as you wish. The target namespace referenced in each WSDL is displayed. See the example illustration below. 4 Click OK. Each WSDL file is validated before it is added to Web References. Note: The Target Namespace is a convention of XML Schema that enables the WSDL document to refer to itself. It is a value that is unique, different from all other namespaces that are defined. Removing a Web Reference You can remove a Web Reference you no longer need. Select the WSDL file, from any view (messages, partner link types, etc.), and select the Globe with the minus sign in the Web References toolbar. Note: The Remove function removes the WSDL file from the registry. It does not delete it from the file system. You cannot remove just one part of the file, such as a namespace, message or operation. 132 Viewing, Adding, and Removing Web References Version 1.5

133 The WSDL reference in your process is not affected since the WSDL is referenced by its file system or project location. Viewing, Editing, and Resolving Web References You can right-mouse click on a WSDL file in Web References view and select View Web Reference to view XML text. If the WSDL file is in a workspace project, it appears in the Navigator view, and you can open and edit it in a text editor. To edit a WSDL that is part of a project: 1 In the Navigator view, select a WSDL file. 2 Double-click the file to open it in a text editor. 3 Edit the file and save it. 4 In Web References view, select Refresh. If the WSDL file is not in a workspace project, you can edit it outside of ActiveWebflow. After you edit the file, update Web References by selecting Refresh from the Web References toolbar. For more information, see Refreshing Web References. Your WSDL changes may affect the references in BPEL files, and you may need to resolve them. For example, if your BPEL process refers to a partner link role name that you change, the Role name will be marked as Unresolved Reference, and you must select a new name from the Properties view to ensure your process is valid. Refreshing Web References Select the circular arrows (Refresh icon) on the Web References view toolbar to refresh the content of the view as well as the references within your BPEL processes. The Refresh feature is useful if you have edited a Web Reference file in your computer s file system. Filtering the Web References View by Reference Set A reference set limits the list of Web References in view. You can create various reference sets to display only the Web References relevant to the BPEL projects you are currently working on. A reference set is a handy way to display only the relevant namespaces, partner link types, and messages you want to work with. To create a reference set: Version 1.5 Chapter 5: Web References 133

134 1 In Web References view, select Select Reference Set from the drop-down arrow on the toolbar. 2 In the Select Reference Set dialog, select New. 3 Type in a reference set name. 4 Select the WSDL and schema files to include, and click OK. 5 Click OK. Tips for working with reference sets: Redisplay all Web References by selecting Deselect Reference Set from the Web References drop-down list on the toolbar Edit the current reference set by selecting Edit [name] Reference Set from the Web References drop-down list on the toolbar Remove a reference set by selecting Select Reference Set from the Web References drop-down list on the toolbar and then selecting Remove Note: In the Navigator you can create working sets of your project files, and they are similar to reference sets. Working sets and reference sets are mutually exclusive display functions. For example, you can use working sets, but not reference sets, to filter searches. Viewing WSDL Namespaces, Messages, Partner Link Types, and Schema Web References view provides a filter for viewing the various components of WSDL files on a component by component basis. Click the down arrow in the Web References view toolbar to select one of the following view options: Table 8: View This Item: WSDL Partner Link Types Namespaces Expand This Item to: View port types, partner links, messages, message properties, property aliases, bindings, and services View associated partner roles and operations View WDSL files where namespace is declared 134 Viewing WSDL Namespaces, Messages, Partner Link Types, and Schema Version 1.5

135 Table 8: View This Item: Messages Schemas Expand This Item to: View message parts. Right-mouse click a message part to use sample data options. can not expand Using WSDL Operations in BPEL Activities One of the key productivity features of Web References is accessing WSDL operations for use in your process designs. For example, you can display a list of WSDL port types and from them select an operation to drag directly to the Process Editor canvas. This action starts a wizard to help you create an appropriate activity as part of your process definition. There is no need to hand-code BPEL XML files. ActiveWebflow generates valid code as you make selections from the wizards. For more information, see Creating an Activity by Starting with a Web Reference. Creating a WSDL File with Extensions for BPEL Typically you add WSDL files into Web References view, as described in Adding a Web Reference. However, not all WSDL files include the extensions required to create executable BPEL processes. The extensions are partner link types, properties, and property aliases. ActiveWebflow includes a wizard to allow you to create partner link type definitions, that are required for creating executable BPEL processes. When you create new partner link types, ActiveWebflow asks you if you want to add them to an existing WSDL or create a new WSDL. If you create a new WSDL, it is automatically added to Web References. The WSDL contains only the partner link type definitions. Version 1.5 Chapter 5: Web References 135

136 In addition, a wizard helps you create property and property aliases that are needed for Correlation Sets. These extensions can be added to an existing WSDL or to a new WSDL. For details, see Partner Link Type and Creating Message Properties and Property Aliases. Using Sample Data for WSDL Messages WSDL files define operations that receive an input message and, optionally, return an output message. In the Web References view, you can add sample data files for message parts. When you are ready to test your process, you can load the sample message part values into your variables. As you execute and debug your process, you can inspect the input and output data values as they are processed. By adding sample data files to Web Reference messages, you have a default set of data across all projects that refer to WSDL messages. Web References view keeps track of all sample files and their locations on your file system and presents the list to you when you are loading values into message variables. For more information, see: Creating a Sample Data File Adding a Sample Data File in Web References Selecting a Default Sample Data File Viewing the XML Structure of a Sample Data File Removing a Sample Data File Creating a Sample Data File When you want to use sample data for complex messages, you must create a sample data file before adding it to ActiveWebflow. A sample data file is an XML file structured with message part elements that have been defined in the schema declared in the WSDL namespace. The following code is an example of a partial sample data file for a purchase order output message. <purchaseorders xmlns=" xmlns:tns=" <purchaseorder tns:orderdate=" "> <shipto tns:country="us"> <name>jay Lor Jr.</name> <street>100 My Street</street> <city>my City</city> 136 Using Sample Data for WSDL Messages Version 1.5

137 <state>ct</state> <zip>06484</zip> </shipto>... </purchaseorder> </purchaseorders> Note: You can create multiple sample data files for the same message part. You can name the files uniquely, or you can use the same filename and store the files in different folders. ActiveWebflow keeps track of file locations when you add the files to Web References. Adding a Sample Data File in Web References You can add several sample data files to Web Reference messages that are complex types and then select a default sample for all processes you create in ActiveWebflow. On a process by process basis, you can add sample data to process variables in addition to or instead of using the samples added to Web References. To add sample data: 1 In the Web References view toolbar, click the down arrow, and select View Messages. 2 In the Messages list, expand a message with a complex part, and select a message part for which you have created a valid sample XML data file. 3 Double-click the complex part to open the Add Sample dialog. 4 Select the source location for the file: Project. Select a project you created or imported into the Navigator view. File System. Select a folder on your computer or network. 5 Browse to the file, select it, and click OK. ActiveWebflow validates the file against the WSDL schema and reports errors, if any. The first file you add is set as the default sample, but you can add additional files and select one as a default. Selecting a Default Sample Data File You can add several sample data files per message part in Web References view. You can select one sample file as the default file that is loaded into process variables. In Web References view, expand a WSDL message. To select a default sample data file, right-mouse click on a sample file and select Default Sample, as shown. Version 1.5 Chapter 5: Web References 137

138 Viewing the XML Structure of a Sample Data File To view the XML text of a sample data file, right-mouse click on the data file name and select View Sample. Removing a Sample Data File To remove a sample data file, right-mouse click on the data file and select Remove Sample. If you remove the file designated as the default file, the first file in the list becomes the default. Selecting Sample Data From Web References The Load Sample from Web References dialog displays a list of XML files containing sample data values for the Process Variables message part displayed. 138 Selecting Sample Data From Web References Version 1.5

139 The list consists of all sample data files that you or another user has added to Web References for the selected message part. For more information, see Adding a Sample Data File in Web References. The pathname of each file is displayed to help you identify the file you want to use. Select a sample file from the list. You will see the data values in the data column of the variable. Finding Where a WSDL Component is Used In ActiveWebflow, you can perform two kinds of searches for Web References: Quick search for a WSDL component with the Find Where Used option Search for a string or pattern using the Web References tab in the Search dialog. For more information, see Using Web References Search. The Find Where Used search helps you quickly locate a WSDL component reference in an ActiveWebflow project file. When you build BPEL processes in ActiveWebflow, you reference the components of the WSDL files displayed in the Web References view. You can search for a particular WSDL component to find the BPEL files that are referencing the component. This search is useful if a WSDL file changes, because you may need to search for and update the references. To use Find Where Used 1 From the Web References toolbar, click the down arrow and select the view you need, such as WSDL file view or message view. For more information, see Web References Toolbar Options. 2 Select one item from the display list, that is, select one of the following: WSDL file Message Namespace Partner link type 3 Right-mouse click and select Find Where Used. 4 Select the scope of the search: Version 1.5 Chapter 5: Web References 139

140 Entire workspace, namely all project files exist in the workspace folder Working set, which is a named, customized group of files and folders 5 A list of project files matching the search criteria appears in the Search results view. If the Search view is not visible, select it from the Window>Show View menu. In the following example, a WSDL message was selected for the search criteria, as indicated in the Search titlebar. 6 Double-click a file to open it. In the Search view, you can perform more search functions, such as search again, use a previous search, and search within search results. For more information, press F1 in the Search view. Using Web References Search In ActiveWebflow, you can search for the use of Web Reference components within your BPEL files. You can perform two kinds of searches for Web References: Search for a string or pattern using the Web References tab in the Search dialog. Quick search for a WSDL component with the Find Where Used option. For more information, see Finding Where a WSDL Component is Used. Web References search helps you locate a WSDL component referenced in a BPEL file. If you do not remember the full name of the component, you can search using wildcards. To perform a Web Reference Search in the entire Workspace or in a Working set 140 Using Web References Search Version 1.5

141 1 Select Web Reference from the Search menu. 2 In the Search for panel, select the type of WSDL component: Message Partner Link Type Namespace 3 For a message or partner link type search do the following: If desired, type in a search string, optionally with wildcards. Select the Case sensitive box, if desired. If desired, further refine the search by providing namespace information. Select the Case sensitive box, if desired. 4 For a namespace search, if desired, type in a search string, optionally with wildcards. Select the Case sensitive box, if desired. 5 Select the scope of the search: Entire workspace, namely all BPEL files in the Navigator that have not been imported from outside the workspace A working set, which is a named, customized group of project files and folders. Note that working set refers to a set of Navigator files and not a reference set of Web References. For details on using Selected Resources, refer to the next procedure. 6 Select Search. 7 A list of project files appears in the Search results view. If the Search view is not visible, select it from the Window>Show View menu. In the following example, the search criteria included messages starting with the string a in all namespaces in the entire workspace, as indicated in the Search title bar. 8 Double-click a file to open it. To perform a Web Reference Search with Selected Resources Version 1.5 Chapter 5: Web References 141

142 1 Display the Navigator view. 2 Select one or more files. When you open the Search dialog, the Select Resources option will be selected. 3 Follow the procedure above, starting with Step 1, Select Web Reference from the Search menu. In the following example, two files were selected in the Navigator before the Search dialog was opened. The search criteria was for all messages in all namespaces. Validation Error Message Dialog The file you are adding has been checked against the schema declared in the selected WSDL file, and one or more errors have been found. The errors are caused by one or more invalid or missing declarations or definitions in the file. If the error is non-critical, you can add the sample file and correct the error later. For an explanation of the error(s), click View Errors. If ActiveWebflow cannot parse the XML file, you will not be able to add it. You can view errors in the Error Log. If the Error Log is not visible, select Window>Show View>Error Log. During the test and debug phase of your project, you must correct an invalid data file. Viewing Sample Data File Errors The View Errors dialog shows you the XML text in your sample data file and the validation errors found in the file. The errors were generated after the file was checked against the schema declared in the selected WSDL file. 142 Validation Error Message Dialog Version 1.5

143 Click on an error message in the bottom half of the dialog to highlight the line in the file that contains a validation error. You can add the sample file and correct the errors later. Version 1.5 Chapter 5: Web References 143

144 144 Viewing Sample Data File Errors Version 1.5

145 6 Planning Your BPEL Process What s in this chapter Using Top-Down or Bottom-Up Process Design Using WSDL References for Efficient Design Importing WSDL Locations and Namespaces Understanding BPEL Process Structure and Properties Understanding BPEL Process Lifecycle Creating an Abstract vs. an Executable Process To create a BPEL process, you need: An idea for an automated data exchange A business partner who has some data to exchange with you A flowchart type of plan that describes how you want to receive data, invoke operations, and reply to your business partner WSDL files describing messages, operations, and port types that will be referenced by the process WSDL definitions for each partner in the process that are in existence or that you ll create for your process Using Top-Down or Bottom-Up Process Design You can use ActiveWebflow to design a process using top-down or bottom-up techniques. In the top-down technique, you sketch out your process by dropping down activities onto a canvas and creating links between them. You then add all the necessary information to bind the activities to an implementation and add decision-making to make your sketch a working process. In the bottom-up technique, you use the definitions of the implementation that are available when you begin process creation.the bottom-up technique requires com- Version 1.5 Chapter 6: Planning Your BPEL Process 145

146 plete and valid Web Services Description Language (WSDL) files. See Using WSDL References for Efficient Design for details. Using WSDL References for Efficient Design A BPEL process uses the definitions from Web Services Description Language (WSDL) files. WSDL files contain the namespace, partner link types, port types, operations, and messages needed to define the process, and WSDL files are required in order to create a valid, executable BPEL definition. It is highly recommended that you add WSDL files to the Web References view of ActiveWebflow before you begin to create a process definition. Web References provide several key productivity features: You can drop a WSDL operation onto the Process Editor to automatically create an appropriate Web Service interaction activity (Receive, Receive/Reply, Invoke) You can automatically create the appropriate WSDL extensions required for a BPEL process, if they do not already exist (partner link types, properties, property aliases) You can use the WSDL definitions across processes See the following topics: Web References Creating WSDL Extensions for BPEL Starting a Process by Dropping an Operation onto the Process Editor Creating WSDL Extensions for BPEL A BPEL process depends upon WSDL extensions that are unique for BPEL. ActiveWebflow can create these extensions automatically, if they do not exist in your WSDL files. The extensions are partner link types, properties, and property aliases. A partner link type defines the role(s) played by a service and the port type provided by the service. For details, see Partner Link Type. Properties and property aliases are significant for correlating a group of messages in a process. For more information, see Creating Message Properties and Property Aliases. 146 Using WSDL References for Efficient Design Version 1.5

147 Starting a Process by Dropping an Operation onto the Process Editor You can begin designing a BPEL process by opening a Web Reference, locating a port type or partner link type, and dragging an operation to the Process Editor canvas. This technique of starting a process design is highly effective. When you start a process this way, ActiveWebflow does the following: Creates the appropriate activity with all required properties Adds a target namespace to the process Creates a namespace prefix Creates process variable(s) For information on how to use Web References for the greatest design efficiency, see Creating an Activity by Starting with a Web Reference. Importing WSDL Locations and Namespaces A BPEL process must contain namespaces that point to WSDL locations. Because one namespace can have many WSDL files associated with it, ActiveWebflow identifies the correct WSDL file by using the Imports function. Imports is a helper function in ActiveWebflow that identifies and adds appropriate WSDL namespaces to a process. Imports is not a BPEL construct. You can add Imports manually or automatically. See the following topics: Automatically Importing WSDL Location Manually Importing WSDL Locations Refreshing Imports Deleting an Import Automatically Importing WSDL Location Your WSDL files may be located in many places and may share the same namespace. When you specify a WSDL location, ActiveWebflow adds the appropriate namespace declaration to the BPEL process and ensures that the namespace points to the correct WSDL reference. ActiveWebflow takes care of WSDL location/namespace declarations for you when you add a WSDL file to Web References and then create a Receive or Invoke activity by starting with a Web Reference operation. For basic information on Version 1.5 Chapter 6: Planning Your BPEL Process 147

148 using the convenience of Web References, see Web References. See also Creating an Activity by Starting with a Web Reference. Manually Importing WSDL Locations If you import and open a BPEL process into ActiveWebflow before adding a WSDL file to Web References, ActiveWebflow reports unresolved references to port types because the WSDL is unknown. You can add WSDL location and namespace manually as follows. 1 From Outline view, select Imports. 2 Right-mouse click and select Add Import. 3 In the Location dialog, do one of the following: Select File System and browse to the location of the WSDL file to select it. Note that the File System selection is useful for testing, but probably not the best choice for a deployed process since it references a static pathname. Select Project and browse to the ActiveWebflow workspace project folder containing the WSDL file. Select URL and type in a Web location of a WSDL file, such as or? Note that when the process is deployed and running, this URL must be available. 4 Note that the target namespace is displayed for the WSDL file. If you paste a pathname or URL into the WSDL file location field, you must press the Tab key to see the target namespace. Click OK when you are through. To modify an import, double-click it, or in Properties view, click the Dialog Button next to Declaration Location. ActiveWebflow adds the target namespace to the BPEL process and associates the namespace with a default prefix. Also, the port types, operations, and partner link types defined in the WSDL are available for use in the process. The following illustration shows how the WSDL location and namespace are displayed. Note that ActiveWebflow adds a new namespace prefix with a default name ns1. See Namespace Prefix and Declaration for more information. 148 Importing WSDL Locations and Namespaces Version 1.5

149 Refreshing Imports The Imports node in Outline view displays the location of all WSDLs referenced in your process. If you modify a WSDL or create a new WSDL for partner link types or correlation properties, you can refresh Imports to update the WSDL reference. Note: Refreshing Web References does not refresh the Imports information. Tip: If you import and open a BPEL process in ActiveWebflow before adding a WSDL file to Web References, ActiveWebflow reports unresolved references to port types, operations, and variables because the WSDL is unknown. You can fix the errors reported as follows: 1 Add the appropriate WSDL files to Web References, as described in Adding a Web Reference. 2 In the Outline view, right-mouse click on Imports, and select Refresh Imports. Deleting an Import You can delete an imported WSDL location by right-mouse clicking an Import in Outline view and selecting Delete. From the menu bar, you can also select Process>Delete>Import. Note that the associated namespace prefix and URI are not deleted. You can manually delete the namespace, if desired. Namespace Prefix and Declaration A BPEL process must contain namespaces that point to WSDL locations. To add WSDL locations, you use the Imports function, as described in Importing WSDL Locations and Namespaces. Version 1.5 Chapter 6: Planning Your BPEL Process 149

150 After adding an import, you can rename the default prefix for the namespace, as follows. 1 In Outline View, select a Namespace. 2 In the Properties view, type in a Prefix to use as a shortcut definition for the namespace. The prefix is mapped to the URI reference displayed. Note: If you delete an import, you must manually delete the namespace associated with it. Deleting a Namespace You can delete a namespace by right-mouse clicking a namespace in Outline view and selecting Delete. From the menu bar, you can also select Process>Delete>Namespace. Variables and other references within the namespace, if any exist, become unresolved references, as noted in the Tasks view. Note that when you delete an Import, the associated namespace prefix and URI are not deleted. You can manually delete the namespace, if desired. Understanding BPEL Process Structure and Properties A BPEL process has several structural parts: Process Element and Properties Variables Partner Links Activities Fault Handlers Compensation Handlers Process Element and Properties After you create a new BPEL file in ActiveWebflow, add an activity to the drawing canvas, and save your file, ActiveWebflow creates the underlying XML file. If you look at the XML text, you ll see that the file begins with the <process> element. The XML Syntax for the process element looks like this: <process name= ncname targetnamespace= uri querylanguage= anyuri? expressionlanguage= anyuri? suppressjoinfailure= yes no? 150 Understanding BPEL Process Structure and Properties Version 1.5

151 enableinstancecompensation= yes no? abstractprocess= yes no? xmlns= > To specify <process> properties: 1 Click on a blank part of the Process Editor canvas to put the process as a whole in focus. 2 In the Properties view, set the Process properties as desired. Table 9: Process Properties Property Description Default Value Abstract Process Enable Instance Compensation Expression Language Specifies whether the process is abstract or executable. For more information, see Creating an Abstract vs. an Executable Process. This setting can be specified as a preference for all new processes. See ActiveWebflow Preferences. Specifies whether the process as a whole can be compensated by platformspecific means. The process instance can be compensated after normal completion. This setting can be specified as a preference for all new processes. See ActiveWebflow Preferences. Specifies the language used in building variable and other expressions. The default is XPath 1.0. Also available for future standards as they evolve. no no /REC-xpath Process Name You can specify a process name that differs from the BPEL file name. This is useful if you create different or updated versions of the same process. You can name the BPEL file with meaningful version information, but can use the same internal process name. The process name property, not the BPEL filename, is known to the server engine. name of the BPEL file Version 1.5 Chapter 6: Planning Your BPEL Process 151

152 Table 9: Process Properties Property Description Default Value Query Language Suppress Join Failure Target Namespace Specifies the XML query language. The default is XPath 1.0. Also available for future standards as they evolve. A join condition is a property of all activity types and provides status about an incoming link. A join failure indicates that link execution failed. At the process level, this attribute specifies whether a join failure is suppressed for the whole process. Can be overridden at the activity level and can be specified as a preference for all new processes. See ActiveWebflow Preferences. The XML namespace that refers to the required WSDL information. This is a required property /REC-xpath yes none Partner Links A BPEL process describes a flow of interactions between the process and services. Each interaction describes what role the process and services play at that step in the flow and what data can be manipulated by the parties in those roles. The constructs used to define roles are: Partner link type Partner link Partner (optional) You can define and add these roles in ActiveWebflow. For more information, see Partner Link Types, Partner Links, and Partners. Variables The BPEL process receives, manipulates, and sends data through XML variables. For example, the process receives a purchase order message from a buyer and puts 152 Understanding BPEL Process Structure and Properties Version 1.5

153 the message in an input XML variable, and from there it can be copied to another operation. Variables are defined in one of the following ways: WSDL message types XML schema simple types XML schema elements Variables allow processes to maintain state data, such as time outs, and process history based on messages exchanged. Activities Activities are the processing steps, performed in the order described by the flow diagram you design in ActiveWebflow. In ActiveWebflow, there are several types of activities: Basic activities to exchange and assign data and define execution steps Containers to structure activities and handle faults and compensation Event Handlers For more information, see Creating an Activity. Fault Handlers A fault handler defines the activity that the process must perform in response to an error condition. For more information, see Fault Handling. Compensation Handlers Compensation is the process of reversing or providing an alternative for a successfully completed activity, especially when a fault occurs. For more information, see Compensation. Understanding BPEL Process Lifecycle A BPEL process instance has a beginning, middle, and end, which are all defined by activities. The process must begin with one of the following: Receive activity Version 1.5 Chapter 6: Planning Your BPEL Process 153

154 Pick activity Flow activity containing one or more Receive or Pick activities In a Receive or Pick, the Create Instance property must be set to Yes. The middle of the process consists of linked activities, running in sequence or concurrently. The process instance ends in one of the following ways: An activity defines that the process is complete A fault reaches a process scope, and the process terminates abnormally Creating an Abstract vs. an Executable Process In ActiveWebflow, you can build two kinds of business processes: Abstract Executable An abstract process is a business protocol description document that tells your business partners what a process will look like when it runs. It outlines the steps of a process without actually filling in all the actions and data required for a running process. The purpose of an abstract process is to share information with your partners, without exposing how you intend to use data from your service. It gives your partners a way to understand how to create their WSDL files to work in your process and to tell them what information you plan to send them when the process runs. An abstract process outlines the type of data to be exchanged, as well as activities, time limits, error handling, and other meaningful pieces of information for the process. An executable process contains all the actual message data, operations, and partner information required for a running process. It uses the full power of data assignment and selection. The following illustration shows that you can start your process either by using WSDL files in existence or by building an abstract BPEL process first and then create the WSDL files for it. 154 Creating an Abstract vs. an Executable Process Version 1.5

155 The following table describes the features that are available, required, and optional in abstract and executable process building Table 10: Property settings for abstract vs. executable process Feature Abstract Process Executable Process Process property Set abstract=yes Set abstract=no Expressions Variables Does not include the fault described for the executable process Can refer to some variables before they are initialized. However, all message properties must be initialized, such as the Input variable of an Invoke activity. Manipulation of variables is limited to message properties and reference to opaque (private) data A function is included that extracts arbitrary values from variables. For more information, see Using the Expression Builder. If you reference a variable before you initialize it, you must throw a fault. Version 1.5 Chapter 6: Planning Your BPEL Process 155

156 Table 10: Property settings for abstract vs. executable process Feature Abstract Process Executable Process Assignment Cannot use a query property Can use an opaque property for a data variable. This means you can define a placeholder for actual data from your service that you do not want to expose to your business partners. You can use an XPath query property to identify a value within a source or target variable part. For more information, see Assign. Correlation Operations If variable references are omitted in activities, then they can not be referred to in a correlation set. Variables for Receive, Pick and Reply and Input variable for Invoke are optional Correlation set properties must be identical for all messages within the set and certain faults must be thrown if correlation rules are violated Variables for Receive, Reply, Pick and Input variable for Invoke are required. In a request/response operation the Output variable is required for Invoke. If operation rules are violated, certain faults must be thrown. Terminate Activity Does not apply Used to immediately terminate the process Event Handlers Does not apply The Input variable is required for an OnMessage event handler Faults There are no standard faults defined Standard faults are defined for: Expressions and variables that extract values during execution Correlation violation Simultaneously enabled Receive activities Conflicting requests Invalid Reply Repeated compensation For more information, see BPEL Standard Faults. 156 Creating an Abstract vs. an Executable Process Version 1.5

157 7 Partner Link Types, Partner Links, and Partners What s in this chapter What are Partner Link Types, Partner Links, and Partners? Partner Link Type Partner Link Partner Showing and Hiding Swimlanes Exporting a Partner Link or Partner to an Abstract Process What are Partner Link Types, Partner Links, and Partners? A BPEL process describes a flow of interactions between the process and services. Each interaction describes what role the process and services play at that step in the flow and what data can be manipulated by the parties in those roles. BPEL defines several constructs to identify roles and relationships used in interactions. The constructs are partner, partner link, and partner link type. A partner is a collection of partner links. A partner link describes the roles that a process and service play as well as what data they can manipulate in that role. A partner link is defined by its partner link type, as shown in the following diagram. Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 157

158 The partner definitions and usage in a BPEL process do not refer to the specifics of Web services. Since a BPEL process is a reusable definition that can be deployed in different ways, the definitions are abstract. The addressing, security, and other specifics of Web services are taken care of at deployment time. When a process is deployed, every partner role in a partner link for a BPEL process instance is assigned a unique endpoint reference. For more details on each concept, see: Partner Link Type Partner Link Partner Partner Link Type A partner link type describes the kind of message exchange that two WSDL services intend to carry out. A partner link type characterizes this exchange by defining the roles played by each service and by specifying the port type provided by the service to receive messages appropriate to the exchange. A partner link type can include one role or two roles. In the case where a partner link type contains two roles, each of the services must implement its role by providing the port type specified. The use of two roles indicates that there is a requirement for the calling service to receive some type of callback from the target service in the course of the conversation. In the case where a partner link type contains only one role, there is no restriction placed on the calling web service regarding roles. The service described by the sin- 158 Partner Link Type Version 1.5

159 gle role is capable of completing the conversation simply by having its operation invoked without the need for issuing a callback. The following illustration shows an example of a partner link type defining two roles. Partner Link Type Definition Partner Link Type Example For example, a partner link type named AuctionHouse_Seller describes two roles: AuctionHouse and Seller. The AuctionHouse role supports a port type of Seller, which expects an input message of an item for sale. The Seller role supports a port type Seller_Answer, which expects an input message from the auction house, regarding whether or not the item has sold. The output message is the name of the item for sale. In this example, the port types are from the same service; however, port types can be from two different services. The partner link type is a WSDL extension. It can specify one or two roles. The port types can be from the same or from different WSDL files. A partner link type definition to be used by your process can come from the following sources: From a WSDL file, where it is already defined, or where you can add a new definition From a separate WSDL file with its own namespace, for the case where there are two port types, and they are from different services Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 159

160 From an ActiveWebflow BPEL process, where you create can a new definition and add it to a WSDL file Add a new Partner Link Type: 1 Display the Web References view. 2 Ensure that the WSDL file you want to refer to is displayed in the list. 3 Expand a Port Type to display an operation you want to use, but does not have an associated Partner Link Type yet. 4 Drag the operation to the Process Editor canvas to open the Partner Link Type wizard, as shown. 5 Do one of the following: Use an existing Partner Link Type definition by selecting from the list, and then click Finish. Select a Partner Link Type definition from Add to Partner Link Type, type in a new Role name, and then click Finish. 160 Partner Link Type Version 1.5

161 Create a new Partner Link Type name and Role name, and then click Next. 6 In Step 5 if you created a new Partner Link Type, you can add it to an existing WSDL file or create a new file for the definition. Do one of the following: Type in an URL in the Create new WSDL file field to qualify all names and message types for this Partner Link Type definition. Then enter the WSDL filename and pathname in the Location field, as the example shows in the following illustration, or click Browse to create a new filename and location. Type the file name in the File name field of the Open dialog. Select a WSDL file from Add to WSDL file to add your new Partner Link Type definition. Partner Link 7 Click Finish. Note: If you add the Partner Link Type definitions to a new WSDL, ActiveWebflow automatically adds the WSDL to Web References and to the Imports node in Outline view. Whereas the partner link type is an abstract definition of a conversation between two services, a partner link is the embodiment. It defines the role that the process plays (if any) and the role that the partner service plays (if any). Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 161

162 A partner link definition consists of: A unique name A partner link type At least one role and can include two roles Role names of My Role, which is the process role, and Partner Role In a BPEL process, you use the partner link when defining Web service interaction activities. For example, a Receive activity specifies a partner link, its port type and operation. The port type comes from the associated partner link type. This means that the process can accept incoming message data from the service playing the partner role defined in the partner link. At a minimum, a process must have one partner link for each type of conversation it is engaged in. BPEL allows for multiple partner links of the same partner link type to exist within a process. Add a partner link automatically: Partner links are automatically added to the process when you drop a Web Reference operation onto the Process Editor canvas and complete a wizard to create a Receive, Invoke, or Reply. This is the recommended technique for creating partner links. For more information, see Creating an Activity by Starting with a Web Reference. Add a new partner link manually: 1 From the Outline view, right-mouse click on Partner Link and select Add Partner Link. A partner link named P1 is added to the partner link list. 2 In the Properties View, define the partner link by selecting the partner link type and at least one role. For more information, see Partner Link Type and Partner Links and Endpoint References. Delete a partner link: 1 Click on a blank spot on the drawing canvas for the current process. 2 From the Process menu, select Delete, then Partner Link. 3 Select a partner link from the list to delete and click OK. 162 Partner Link Version 1.5

163 XML Syntax <partnerlinks> <partnerlink name= ncname partnerlinktype= qname myrole= ncname? partnerrole= ncname?>+ </partnerlink> </partnerlinks> Example <partnerlink name= seller partnerlinktype= AuctionHouse_SellerLT myrole= AuctionHouse partnerrole= Seller </partnerlink> Partner Links and Endpoint References Partner In a BPEL process, interactions between business partners are defined by partner links. The definitions are abstract and do not contain any access information about actual running services. This purpose of omitting real access information is to allow the process definition to be re-used for many services. How do the actual services get accessed? A service is identified in different ways: outside of the process at deployment time or within the process in an Assign activity. During deployment of a process, each role defined in a partner link is assigned an endpoint reference. An endpoint indicates a specific location for accessing a Web service using a specific protocol and data format. An endpoint reference conveys the information needed to access a Web service endpoint. Using endpoint references in deployment makes possible the dynamic selection of a service partner. Within a process, you can invoke a service by setting a target endpoint reference in an Assign activity. For more information, see Assign. A partner is a collection of partner links. When a partner link is included in a partner definition, it cannot be used outside of the partner definition. A partner definition is optional, and it cannot overlap with other partner definitions. You can create partner definitions to show what capabilities are required from one partner. During deployment, the partner definition requires that the roles grouped as a partner must be performed by the same provider. For example, a business partner called SellerShipper is required to provide the services associated with the roles of seller and shipper. Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 163

164 XML Syntax <partners> <partner name= ncname >+ <partnerlink name= ncname />+ </partner> </partners> Example <partner name= SellerShipper <partnerlink name= Seller /> <partnerlink name= Shipper /> </partner> For more information, see: Adding a New Partner Deleting a Partner Showing and Hiding Swimlanes Adding a New Partner Before adding a partner, be sure to create at least one partner link. 1 Right-mouse click on a blank spot in the Process Editor canvas, making sure no icons are selected. 2 Select Add Partner. 3 In the Properties view, click the Dialog Button next to Partner Link. 4 In the Partner Link Set dialog, select one or more available partner links and add them to the Partner Link Set box. Note: You can not add the same partner link to more than one partner. Partner link roles grouped in a partner indicate that the same provider must perform all services. Deleting a Partner When you delete a partner, the partner links are available for other partner definitions. 1 Click on a blank spot on the Process Editor canvas for the current process. 2 From the Process menu, select Delete, then Partner. 3 Select a partner from the list to delete, and click OK. 164 Partner Version 1.5

165 Showing and Hiding Swimlanes The Process Editor canvas can display Swimlanes in addition to the flow diagram of a BPEL process. A Swimlane is a view that shows a partner process correlated with your process. In essence, a partner lane is a diagram that depicts the part of the partner s process which faces your process. There are two kinds of Swimlanes: partner and partner link. You can display either or both of these lanes on the Process, Fault Handlers, Event Handlers, and Compensator tabs of the Process Editor. For more information, see Showing and Hiding Lanes for Partner Definitions and Showing and Hiding Lanes for Partner Link Definitions. Showing and Hiding Lanes for Partner Definitions Before you can display a Swimlane for partners, create at least one partner definition as described in Adding a New Partner, and create at least one Web service interaction activity such as a receive or invoke. 1 From the Process menu, select View Swimlanes. 2 Select Partners and select a partner to view. Tips: Select Show All from the View Swimlanes option to view all partner and partner link lanes. The illustration below shows an example. Print a process diagram with partner lanes to share at business partner meetings Set a preference for Swimlane colors and link style. See Swimlane Appearance Preferences. Move Swimlane activities up and down to align them with process activities. Select an activity (invoke, receive, or reply), and drag it up or down. Display Swimlanes on the Fault Handlers, Event Handlers, and Compensator tabs The following illustration shows an example of partner and partner link display. The partner (AssessorCustomer) is on the left, and the partner link (approver) is on the right. Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 165

166 Showing and Hiding Lanes for Partner Link Definitions Before you can display a Swimlane for partner links, create at least one Web service interaction activity such as a receive or invoke. 1 From the Process menu, select View Swimlanes. 2 Select Partner Links and select a partner link to view. Tips: Select Show All from the View Swimlane option to view all partner and partner link lanes. The illustration below shows an example. Print a process diagram with Swimlanes to share at business partner meetings Set a preference for Swimlane colors and link style. See Swimlane Appearance Preferences. Move Swimlane activities up and down to align them with process activities. Select an activity (invoke, receive, or reply), and drag it up or down. Display Swimlanes on the Fault Handlers, Event Handlers, and Compensator tabs The following illustration shows an example of partner and partner link display. The partner (AssessorCustomer) is on the left, and the partner link (approver) is on the right. 166 Showing and Hiding Swimlanes Version 1.5

167 Exporting a Partner Link or Partner to an Abstract Process To help your partners implement the operations that interact with your service, you can provide your partners with a process definition that describes the operations. This process definition can be exported from a Swimlane in a process diagram. For Swimlane information, see Showing and Hiding Swimlanes. To create a BPEL file containing partner or partner link information: 1 Create a BPEL process with at least one completed activity that is based on a WSDL operation such as a receive, invoke, or OnMessage branch of a pick activity. 2 If desired, display a partner link or partner Swimlane to see the facing activities. 3 From the Process menu, select Export Abstract Process. 4 Select Partners or Partner Links. 5 Select a partner or partner link from the list. 6 In the Export Abstract Process dialog, select a location for the BPEL file that will be created. 7 Accept the default name or type in a new name for the BPEL file and, if desired, enable the check box for Open file on export. Version 1.5 Chapter 7: Partner Link Types, Partner Links, and Partners 167

168 8 Click OK. ActiveWebflow creates a BPEL process with the Abstract Process attribute set to yes. The file is listed in the Navigator. For more information on abstract processes, see Creating an Abstract vs. an Executable Process. 168 Exporting a Partner Link or Partner to an Abstract Process Version 1.5

169 8 Creating an Activity What s in this chapter Overview of Activities Defining an Activity and Its Properties Creating a Custom Activity Creating an Activity by Starting with a Web Reference Using the Expression Builder Using the Query Builder Creating a Join Condition for an Incoming Link An activity is a step in a BPEL process. It can describe an interaction with a Web service, or it can perform internal process functions. The process must contain at least one activity. Overview of Activities Basic activities break down into two kinds: those that interact with Web service partners and those that are used internally by the BPEL process. The following table provides brief definitions and links to more details. Table 11: Activity Name Description Web service interaction activities Receive Invoke Reply Accepts message data from a service partner. Optionally begins a process by creating an instance of the process. Directs a Web service to perform an operation Sends a response to a partner identified in a matching Receive activity Version 1.5 Chapter 8: Creating an Activity 169

170 Table 11: Activity Name Description Internal Process Activities Assign Throw Terminate Wait Empty Compensate Manipulates process variables and partner link endpoint references by creating Copy From/To operations for them Signals a fault. Specifies a standard or custom fault Stops an executable process immediately Stops process execution for a specified amount of time or until a deadline is reached An activity that does nothing when it executes. Useful for situations where you need an activity but do not want anything to really happen, for example, suppressing a fault by having the empty be the child of the catch. Executes the compensation handler on a named scope or executes the default compensation if no scope is named For information on structured activities, see Different Ways of Structuring Activities. Defining an Activity and Its Properties You can select and drag an activity to the Process Editor canvas from the Activity palette. 170 Defining an Activity and Its Properties Version 1.5

171 Note: You can also drag an operation from a Web Reference to the Process Editor canvas to create a Receive, a Receive/Reply combination, or an Invoke activity as described in Creating an Activity by Starting with a Web Reference. With the activity in focus on the Process Editor canvas, you can set property values in the Properties view. The illustration shows an example of the basic Receive activity properties. Select the Advanced button on the Properties toolbar to display all the properties for an activity. The Advanced properties are the standard properties for all activities. In the illustration below basic and advanced properties are displayed. Version 1.5 Chapter 8: Creating an Activity 171

172 When your mouse hovers over an activity icon, you see property details for the activity. The following illustration shows an example. For more information, see: Selecting Values for Activity Properties Selecting Activity Labels Standard Properties for Activities Selecting Values for Activity Properties When you add an activity to the Process Editor canvas, the Properties view displays all of the valid properties for it. Some properties are activity-specific, and some are standard for all activities. 172 Defining an Activity and Its Properties Version 1.5

173 For example, the Create Instance property is valid only for a Receive or Pick activity. The Copy Operation is valid only for the Assign activity. You assign values to properties as follows: For Activity Name, there are several choices. See Selecting Activity Labels. For list-valued properties, such as Variable, click in the Value field and select from the list. For building a complex property, such as for Correlation Sets, click the Dialog Button. Selecting Activity Labels When you add an activity to the Process Editor canvas, it is labeled with the activity type. For example, a Receive activity is labeled Receive. You can make the label more meaningful by adding a name or custom text. You can also add a name but display only the type to preserve screen real estate. The following examples show some labeling choices. Notice that you can keep the label short, if desired, and then use hover help to display details. Activity Type: Name Activity Type Custom Label Create a label in one of the following ways: Edit the activity label directly on the Process Editor canvas or fill in Activity Name in the Properties view Select a label type from the Label property Fill in the Custom Label field and then select Custom from the Label list To edit the activity label: Version 1.5 Chapter 8: Creating an Activity 173

174 1 In the Process Editor canvas, click on the activity label. The label field changes to an edit field, as shown. 2 Type in a label, which is the same as an activity name. Do not include spaces or special characters. Select the label type from the Label field in Properties view as follows: Table 12: Activity Name or Type Activity Name Activity Type Activity Type: Name Custom By default, the type is displayed. If you add a name, the name is displayed and is editable on the canvas. The name is editable on the canvas. It cannot contain spaces or special characters. The name is an attribute of the activity element in the BPEL XML and is exported with the process. The best choice to preserve screen real estate. The Type is not editable on the canvas. Meaningful label, but is not editable on the canvas. This is for display purposes only. It can include spaces and special characters, and is editable on the canvas. It does not export with the BPEL XML. Standard Properties for Activities The following table shows standard properties for all activities. The table does not include activity-specific properties, which are discussed under each activity. Table 13: Standard Properties Attribute Suppress Join Failure Join Condition Comment Description See Process Properties See Creating a Join Condition for an Incoming Link See Adding Comments to the Process 174 Defining an Activity and Its Properties Version 1.5

175 Table 13: Standard Properties Attribute Execution State Description See Viewing the Execution State of an Activity or Link Receive Note: The Suppress Join Failure and Join Condition properties appear in the Properties view when you select the Advanced button on the toolbar. When a BPEL processing engine gets a message, it searches for a Receive activity with a matching partner link, port type, and operation. The Receive activity specifies the partner link it expects to receive a message from and the port type and operation it expects the partner s service to invoke. For an executable process, the Receive must specify an input variable for the message data received. See Partner Link Types, Partner Links, and Partners for descriptions of concepts important to this activity. The Receive activity can begin a business process instance by including a Create Instance property set to Yes. You can create a set of concurrent initial Receives. This case allows for any one message of a set to initialize the process. To create a multiple-activity starting point, add the Receives to a Flow structure. For more information, see Flow. Also you must provide a Correlation Set for all concurrent Receives that initiate a process, as described in Adding Correlations to an Activity. Two other activities are similar to a Receive: an OnMessage clause in a Pick or an OnMessage event handler. For more information, refer to Pick. Table 14: Required and optional properties for Receive Required Properties Partner Link Port Type Operation Variable (required only for executable process, not abstract process) Optional Properties Name. See Selecting Activity Labels Correlations. See Correlation Create Instance Join Condition. See Creating a Join Condition for an Incoming Link Version 1.5 Chapter 8: Creating an Activity 175

176 Table 14: Required and optional properties for Receive Required Properties Optional Properties Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To add a Receive activity to the process manually: Note: For a shortcut and recommended technique, see Creating an Activity by Starting with a Web Reference. 1 From the Activity palette, drag a Receive activity to the Process Editor canvas. 2 In the Properties view, select the following values in order: a Partner Link b Port Type (Valid Port Types appear in the drop-down list after you select a Partner Link.) c Operation (Valid Operations appear in the drop-down list after you select a Port Type.) 3 Optionally type in a Name. 4 Optionally, select a Variable from the operation. 5 Select other optional properties as desired. 176 Receive Version 1.5

177 Usage Examples One Receive can start a process Any one starts a process; all are required to complete the Flow In a Pick with OnMessage activities, one of many can start a process; the rest are ignored XML Syntax <receive partnerlink= ncname porttype= qname operation= ncname variable= ncname? createinstance= yes no? standard-attributes> standard-elements <correlations>? <correlation set= ncname initiate= yes no?>+ </correlations> </receive> XML Example <receive name="receivecustomerrequest" partnerlink="customer" porttype="lns:loanservicept" operation="request" variable="request" createinstance="yes"> Invoke The Invoke activity directs a Web service to perform an operation. It specifies the partner link, port type and operation to invoke. The Invoke must specify an input variable for the message data to transmit and may specify an output variable in the case of a synchronous request-response Web service invocation. See Partner Link Types, Partner Links, and Partners for descriptions of concepts important to this activity. An Invoke activity can be compensated, or reversed, by including it in a Scope. For more information, see Compensation. Version 1.5 Chapter 8: Creating an Activity 177

178 An Invoke can also include fault handling when the Invoke is added to a Scope. Alternately, any faults associated with the invoked service can be handled at the process level, if desired. For more information, see Fault Handling. Table 15: Required and optional properties for Invoke Required Properties Partner Link Port Type Operation Input Variable Optional Properties Name. See Selecting Activity Labels Correlations. See Correlation. Output Variable Suppress Join Failure. See Process Properties Join Condition. See Creating a Join Condition for an Incoming Link Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To add an Invoke activity to the process manually: Note: For a shortcut and the recommended technique, see Creating an Activity by Starting with a Web Reference. 1 From the Activity palette, drag an Invoke activity to the Process Editor canvas. 2 In the Properties view, select the following values in order: a Partner Link b Port Type (Valid Port Types appear in the drop-down list after you select a Partner Link.) c Operation (Valid Operations appear in the drop-down list after you select a Port Type.) 3 Optionally type in a Name. 4 Optionally, select an input variable and an output variable from the operation. 178 Invoke Version 1.5

179 5 Select other optional properties as desired. A simple example of using an Invoke in a process is shown in the following illustration. XML Syntax <invoke partnerlink= ncname porttype= qname operation= ncname inputvariable= ncname? outputvariable= ncname? standard-attributes> standard-elements <correlations>? <correlation set= ncname initiate= yes no?> pattern= in out out-in />+ </correlations> <catch faultname= qname faultvariable= ncname?>* activity </catch> <catchall> activity </catchall> <compensationhandler>? activity </compensationhandler> </invoke> Example: <invoke name="invokeapprover" partnerlink="approver" porttype="lns:loanapprovalpt" operation="approve" inputvariable="request" outputvariable="approval"> Reply The Reply activity matches a Receive activity. It has the same partner link, port type, and operation as its matching Receive. Use a Reply to send a synchronous response to a Receive. A Receive may have multiple reply activities referencing it but only one of them is allowed to execute. Attempting to reply multiple times to a receive results in a Version 1.5 Chapter 8: Creating an Activity 179

180 bpws:invalidreply fault. For example, a process might receive a message and through its normal execution send a reply while through some fault handling it could reply with an error message. In this case, both of the Reply activites are referencing the initial Receive and its partner link, port type, and operation, but only one of them is allowed to execute. For an executable process, the Reply must specify a variable for the message data being sent. The Reply activity can return a fault response. You can select a Reply to handle a fault by adding it to a Catch container and specifying the fault name and variable properties. See Adding a Fault Handler for more information. Table 16: Required and optional properties for Reply Required Properties Partner Link Port Type Operation Variable Optional Properties Name. See Selecting Activity Labels Correlations. See Correlation Fault Name Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To add a Reply activity to the process manually: Note: For a shortcut and recommended technique, see Creating an Activity by Starting with a Web Reference. 1 From the Activity palette, drag a Reply activity to the Process Editor canvas. 2 In the Properties view, select the following values in order: 180 Reply Version 1.5

181 a Partner Link b Port Type (Valid Port Types appear in the drop-down list after you select a Partner Link. c Operation (Valid Operations appear in the drop-down list after you select a Port Type.) 3 Optionally type in a Name. 4 Optionally, select a Variable from the operation. 5 Select other optional properties as desired. A simple example of using a Reply in a process is shown in the following illustration. To add a Reply with a fault response: 1 Create a Catch container for the appropriate scope or the process as a whole. For more information, see Defining Catch and CatchAll Fault Handlers. 2 Add a Reply to the Catch container. 3 Select the properties and name, as described in the procedure above. 4 Select a Fault Name from the list. 5 Select the fault variable from the Variable list. The following illustration shows an example of adding a Reply to a Catch container and selecting the fault name and variable. Version 1.5 Chapter 8: Creating an Activity 181

182 The following illustration shows a simple example of using a Reply with a fault. XML Syntax <reply partnerlink= ncname porttype= qname operation= ncname variable= ncname? faultname= qname? standard-attributes> standard-elements <correlations>? <correlation set= ncname initiate= yes no?>+ </correlations> </reply> 182 Reply Version 1.5

183 Example 1 Normal Response: <reply name="reply" partnerlink="customer" porttype="lns:loanservicept" operation="request" variable="approval"> Example 2 Fault Handling: <reply name="reply" partnerlink="customer" porttype="lns:loanservicept" operation="request" variable="error" faultname= unabletohandlerequest > Assign The Assign activity updates the content of variables. It updates variables in several ways: Copies data from one variable to another Constructs new data using XPath expressions and functions Constructs new data using BPEL4WS extension functions You can also use Assign to copy endpoint references to and from partner links for dynamic selection of service partners. Table 17: Required and optional properties for Assign Required Properties Copy Optional Properties Name. See Selecting Activity Labels Suppress Join Failure. See Process Properties Join Condition. See Creating a Join Condition for an Incoming Link Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link Version 1.5 Chapter 8: Creating an Activity 183

184 To add an Assign activity to the process: 1 From the Activity palette, drag an Assign activity to the Process Editor canvas. 2 Double-click the assign to open the Copy Operations dialog. Alternately, in the Properties view, click in the Value field of the Copy Operations and select the Dialog Button. 3 Select New. 4 In the From section, select a Type. Table 18: From Type Description Upon Selection of this Type... Expression An XPath expression to perform computations on variables and properties. Must return a string, number or Boolean. You can create the expression with an Expression Builder. For more information, see Using the Expression Builder Literal Opaque Partner Variable A constant that conforms to an XML schema definition. The type may be indicated inline using xsi:type Name representing private application data. Use this option only for an abstract process. For more information, see Creating an Abstract vs. an Executable Process. This selection generates a list of partner links and roles A WSDL message variable and optional part name A WSDL message property XML schema simple type or element You can type in an XML document fragment, such as: <myelement> x </myelement> No other choices are allowed You can select a partner link and role defining an endpoint reference You can select a variable name, and optionally, a part name and query. For more information, see Using the Query Builder. Queries are allowed only in executable processes. Variable Property A WSDL message property You can select a variable name and property 184 Assign Version 1.5

185 5 In the To section, select a Type. The To type must be compatible with the From type, as shown. Table 19: This From type Message-type variable XML schema type variable XML element type variable Literal Expression Must match this To type Message-type variable with matching type A variable containing a schema type A variable containing the same element Must have a matching XML schema type Variable 6 Click OK. You can add multiple Copy operations to an Assign. They will be executed in the order shown in the Copy Operations dialog and also in the Outline view. Note: For a shortcut to creating new Assigns or adding Copy operations to an existing Assign, you can use drag-and-drop features in the Process Variables view. For more information, see Using Variables in a Copy Operation. XML Syntax <assign standard-attributes> standard-elements <copy>+ from-spec (see below) to-spec (see below) </copy> </assign> From-Spec The From element can be in one of these forms: <from variable= ncname part= ncname?/> <from partnerlink= ncname endpointreference= MyRole partnerrole /> <from variable= ncname property= qname /> <from expression= general-expr /> <from> literal value </from> In an executable process, you can also use: <from variable= ncname part= ncname? query= querystring?/> In an abstract process, you can also use: Version 1.5 Chapter 8: Creating an Activity 185

186 <from opaque= yes > Opaque data is private application data that you do not want to expose to your business partners. It is effectively an abstract process placeholder for some real data that you intend to use in an executable process. To-Spec The To element can be in one of these forms: <to variable= ncname part= ncname?/> <to partnerlink= ncname /> <to variable= ncname property= qname /> In an executable process, you can also use: <to variable= ncname part= ncname? query= querystring?/> Example: <assign> <copy> <from expression="'yes'"/> <to part="accept" variable="approval"/> </copy> </assign> See also: Copy Operation Examples Tips for Copy Operations Copy Operation Dynamic Endpoint Reference Example Tips for Copy Operations Copy operations in Assign activities are executed in the order listed in the Copy Operations dialog. The order is also shown in the Outline view. You can re-order the operations in either the Copy Operations dialog or in the Outline view. You can also add a comment for each copy operation. Select a Copy operation from the Outline view. The properties for it are displayed, and you can add a comment for it. For more information, see Adding Comments to the Process. Copy Operation Examples Example 1: Expression value with single quotes 186 Assign Version 1.5

187 Example 2: Query selection Note: To handle query selections with optional elements, see Simulation Preferences. Version 1.5 Chapter 8: Creating an Activity 187

188 Example 3: Expression using built-in BPEL function See Using the Expression Builder for more information. Example 4: Literal XML document fragment See also Copy Operation Dynamic Endpoint Reference Example Copy Operation Dynamic Endpoint Reference Example Here is an example of how to specify a copy operation for dynamic assignment of a service. The service name would be supplied as an input to the Assign activity. Note: Be sure to declare the WS Addressing namespace when you refer to endpoint references. The namespace is xmlns:wsa=" 2003/03/addressing" 188 Assign Version 1.5

189 To implement this assignment, copy from a Literal to a partner link, as shown: Example: <assign> <copy> <from> <wsa:endpointreference> <wsa:address>anyuri</wsa:address> <wsa:servicename>tns:service</wsa:servicename> </wsa:endpointreference> </from> <to partnerlink= mypartnerlink /> </copy> </assign> Throw The Throw activity provides one way to handle errors in a BPEL process. You can set link conditions from an activity and then connect one link to a Throw. For a discussion of error handling, see Fault Handling. Version 1.5 Chapter 8: Creating an Activity 189

190

191 Terminate XML Syntax <throw faultname= qname faultvariable=ncname? standardattributes standard-elements </throw> Example: <throw xmlns:flt= faultname=flt:outofstock /> The Terminate activity stops a business process. It is designed for an executable process, not an abstract process. All currently running activities must be terminated as soon as possible without any fault handling or compensation. Table 21: Required and optional properties for Terminate Required Properties none Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Version 1.5 Chapter 8: Creating an Activity 191

192 Table 21: Required and optional properties for Terminate Required Properties Optional Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Terminate activity: 1 From the Activity palette, drag a Terminate activity to the Process Editor canvas. 2 Add the activity to an appropriate container or link another activity to it. The following illustration shows an example of using a Terminate activity. XML Syntax <terminate standard-attributes standard-elements </terminate> Wait The Wait activity tells the business process to wait for a given time period or until a certain time has passed. 192 Wait Version 1.5

193 The Wait expression conforms to an XPath expression, where the value is an XML schema type of datetime, date, or duration. Table 22: Required and optional properties for Wait Required Properties Wait Expression Wait Type Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Wait activity: 1 From the Activity palette, drag a Wait activity to the Process Editor canvas. 2 In the Properties view, select a Wait Type: Duration or Deadline. 3 Click the Dialog Button next to Wait Expression. 4 In the Expression box, specify one of the following: For a deadline, specify a date and time, such as ' T12:00'. Be sure to include the single quotes. For a duration, specify a time, such as 'P1DT10S'. Be sure to include the single quotes. Note: In addition to the few examples below for deadline and duration expressions, you can see the examples given in the XML schema specification. See the following: Version 1.5 Chapter 8: Creating an Activity 193

194 XML Syntax <wait (for= duration-expr until= deadline-expr )standardattributes> standard-elements </wait> Examples A duration of one second: <wait for="'pt1s'"/> A duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes: <wait for= P1Y2M3DT10H30M /> A deadline with a date and time: <wait until= T12:00 /> Empty The Empty activity is a no op instruction in the business process. This activity is useful for synchronization of concurrent activities. For example, you can use an Empty activity to show how links are affected, whether or not a fault is caught, and at what scope level it is caught. Table 23: Required and optional properties for Empty Required Properties none Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build an Empty activity: 194 Empty Version 1.5

195 1 From the Activity palette, drag a Empty activity to the Process Editor canvas. 2 Add the activity to an appropriate container or link another activity to it. The following illustration shows an example of using the Empty activity. Compensate XML Syntax <empty standard-attributes> standard-elements </empty> The Compensate activity triggers the start of an enclosed scope s compensation handler. See Compensation for a discussion of compensation handlers. The Compensate activity behaves in one of the following ways: It names a scope for which compensation is to be performed It specifies no scope name, thus providing explicit default-order compensation. which executes the compensation handler on all eligible scopes in the reverse order of their completion. The Compensate activity invokes compensation handlers for an enclosed scope, that is, a scope nested within the scope containing compensation handler or fault handler where the compensate activity is defined. Version 1.5 Chapter 8: Creating an Activity 195

196 The Compensate activity must be nested within a fault handler or a compensation handler. Table 24: Required and optional properties for Compensate Required Properties none Optional Properties Name. See Selecting Activity Labels Scope Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Compensate activity: 1 On the Process Editor canvas, select a scope that has a compensator or fault handler container. For a fault handler, ensure that the fault handler contains a catch container. 2 Drag a Compensate activity to the compensator or catch, as shown in the following example. 196 Compensate Version 1.5

197 3 In the Properties view, do one of the following: Leave the scope name as default to perform compensation actions on nested scopes in default order. Select a scope name from the list. The scope must be an inner scope in relation to the compensate activity. XML Syntax <compensate scope= ncname? standard-attributes> standard-elements </compensate> Example <compensate scope= assessorscope /> Creating a Custom Activity You can save any activity or set of activities from a BPEL file as a custom activity. You can shorten design time by reusing the custom activity in other BPEL files. Version 1.5 Chapter 8: Creating an Activity 197

198 To create a custom activity: 1 Select one or more icons on the Process Editor canvas. 2 Right-mouse click and select Add to Palette. The Custom palette appears, if it was previously empty. The selection is added to the Custom palette as Custom1. 3 Right-click the custom icon and select Customize. 4 Rename the custom icon by typing in the Name field. 5 Click OK. Creating an Activity by Starting with a Web Reference ActiveWebflow has a shortcut for you to create activities for an executable process. You can create a Receive, Reply, paired Receive/Reply, or Invoke by selecting an operation from a Web Reference and completing a wizard, as shown. Starting with a Partner Link Type Definition Note: If your WSDL file does not yet include partner link type definitions, you can select an operation from a port type. 1 Display the Partner Link Type element from a Web Reference document. The illustration shows an example of the loanpartnerlinktype. 2 Select an operation to receive from or invoke. 3 Drag the operation to the Process Editor canvas, and the Operation wizard appears. 198 Creating an Activity by Starting with a Web Reference Version 1.5

199 4 Select the activity type. As a shortcut, you can select Receive-Reply to set up matching activities at the same time. Click Next. 5 Accept the existing partner link you have already defined in your process, if available, or type in a new one. A partner link identifies the roles played by the process and service. Click Next. Note: You can edit the partner link and other wizard information after you have finished the wizard. Version 1.5 Chapter 8: Creating an Activity 199

200 6 Use the variable name associated with the operation input message, if desired, or type in a new name for the input variable in your process. Click Next. 7 For an invoke activity, repeat step 6 for the output variable name. Click Finish. Starting without a Partner Link Type Definition If the selected operation is not yet associated with a partner link type, you can select an operation from a port type. A wizard appears so you can create a partner link type definition and add it to an existing WSDL file or create a new WSDL file. For more information, see Partner Link Type. Using the Expression Builder You can select among the following function types to create an expression for Copy Operations, link transitions, and other BPEL constructs. See the procedure below for details on building an expression. BPEL Functions String Functions Number Functions Boolean Functions Node Set Functions 200 Using the Expression Builder Version 1.5

201 Example Expressions Custom Functions Technical Requirements and Sample Files Adding Custom Functions to Expression and Query Builders For Copy Operations in the Assign activity as well as for links and other constructs, you can create XPath expressions that result in a string, number, or Boolean. For details, see the XPath specification at To build an expression: 1 Select an activity that uses expressions, such as the assign, wait, or on alarm branch of a pick activity. 2 In the Properties view for the activity, select the appropriate property. For example, in a Assign activity, select Copy Operations, and select Expression as a Copy/From type to display the following dialog. 3 Select the variables, functions and operators from the three boxes to build an expression, following these tips: Expand a variable to see and use the parts and properties. For detailed descriptions of variables, see Using Variables. Double-click on a variable or variable part to paste the bpws:getvariable- Data function into the Expression box. Double-click on a branch under a part to paste the bpws:getvariabledata function into the Expression box with path information. Version 1.5 Chapter 8: Creating an Activity 201

202 Double-click a variable property to paste the bpws:getvariableproperty function into the Expression box. Add your own custom functions, as described in Creating and Using Custom Functions BPEL Functions bpws:getvariabledata(variablename, partname, [path]) Returns message data from a selected Variable in the business process. Parameters: VariableName: The name of the Variable to retrieve data from partname: the name of the part in the Variable which contains the data path: Optional XPath formatted query to return specific data under the part bpws:getvariableproperty(variablename, propertyname) Returns property data from a selected Variable in the business process. Parameters: VariableName: The name of the Variable to retrieve data from propertyname: the name of the property in the Variable which contains the data bpws:getlinkstatus(linkname) Returns a Boolean indicating the status of the passed link Parameter: linkname: The lname of the link for which to return status abx:getprocessid() Returns the process Id of the currently executing or completed process on the ActiveBPEL server. String Functions string(object) Converts the passed object to a string. 202 Using the Expression Builder Version 1.5

203 concat(string1, string2, [string3...]) Concatenates the passed strings. Can be passed any number of strings to concatenate. starts-with(mainstring, lookforstring) Returns true if the first string starts with the second string. contains(string, string) Returns true if the first string contains the second string. substring-before(string, string) Returns the part of the first string which is before the first occurrence of the second string. substring-after(string, string) Returns the first part of the string which occurs after the first occurrence of the second string substring(string, number, [number]) Returns the part of the string starting at the first number (the first character being 1) and optionally for the length indicated by the second number. string-length(string) Returns the length of the passed string. normalize-space(string) Returns the passed string with the leading and trailing spaces trimmed off. translate(string, string, string) Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string. For example, translate("bar","abc","abc") returns the string BAr. If there is a character in the second argument string with no character at a corresponding position in the third argument string (because the second argument string is longer than the third argument string), then occurrences of that character in the first argument string are removed. For example, translate("--aaa--","abc-","abc") returns "AAA". If a character occurs more than once in the second argument string, then the first occurrence determines the replacement character. If the third argu- Version 1.5 Chapter 8: Creating an Activity 203

204 ment string is longer than the second argument string, then excess characters are ignored. Number Functions number(object) Converts object to a number. sum(node-set) Returns the sum, for each node in the argument node set, of the result of converting the string-values of the node to a number. floor(number) Returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer. ceiling(number) Returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer. round(number) Returns the number that is closest to the argument and that is an integer. If there are two such numbers, then the one that is closest to positive infinity is returned. If the argument is NaN, then NaN is returned. If the argument is positive infinity, then positive infinity is returned. If the argument is negative infinity, then negative infinity is returned. If the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero, but greater than or equal to -0.5, then negative zero is returned. Boolean Functions boolean(object) The Boolean function converts its argument to a boolean as follows: a number is true if and only if it is neither positive or negative zero nor NaN; a node-set is true if and only if it is non-empty; a string is true if and only if its length is non-zero an 204 Using the Expression Builder Version 1.5

205 object of a type other than the four basic types is converted to a Boolean in a way that is dependent on that type. not(boolean) Returns true if its argument is false, and false otherwise. true() Returns true. false() Returns false. lang(string) The lang function returns true or false depending on whether the language of the context node as specified by xml:lang attributes is the same as or is a sub-language of the language specified by the argument string. The language of the context node is determined by the value of the xml:lang attribute on the context node, or, if the context node has no xml:lang attribute, by the value of the xml:lang attribute on the nearest ancestor of the context node that has an xml:lang attribute. If there is no such attribute, then lang returns false. If there is such an attribute, then lang returns true if the attribute value is equal to the argument ignoring case, or if there is some suffix starting with - such that the attribute value is equal to the argument ignoring that suffix of the attribute value and ignoring case. Node Set Functions last() Returns a number equal to the context size from the expression evaluation context. position() Returns a number equal to the context position from the expression evaluation context. count(node-set) Returns the number of nodes in the argument node-set. Version 1.5 Chapter 8: Creating an Activity 205

206 id(object) The id function selects elements by their unique ID. When the argument to id is of type node-set, then the result is the union of the result of applying id to the stringvalue of each of the nodes in the argument node-set. When the argument to id is of any other type, the argument is converted to a string as if by a call to the string function; the string is split into a whitespace-separated list of tokens (whitespace is any sequence of characters matching the production S); the result is a node-set containing the elements in the same document as the context node that have a unique id equal to any of the tokens in the list. local-name([node-set]) The local-name function returns the local part of the expanded-name of the node in the argument node-set that is first in document order. If the argument node-set is empty or the first node has no expanded-name, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member. namespace-uri([node-set]) The namespace-uri function returns the namespace URI of the expanded-name of the node in the argument node-set that is first in document order. If the argument node-set is empty, the first node has no expanded-name, or the namespace URI of the expanded-name is null, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member. name([node-set]) The name function returns a string containing a QName representing the expanded-name of the node in the argument node-set that is first in document order. The QName must represent the expanded-name with respect to the namespace declarations in effect on the node whose expanded-name is being represented. Typically, this will be the QName that occurred in the XML source. This need not be the case if there are namespace declarations in effect on the node that associate multiple prefixes with the same namespace. However, an implementation may include information about the original prefix in its representation of nodes; in this case, an implementation can ensure that the returned string is always the same as the QName used in the XML source. If the argument node-set is empty or the first node has no expanded-name, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member. 206 Using the Expression Builder Version 1.5

207 Example Expressions To express the following statement in a From clause of a Copy Operation: itemsshipped = itemsshipped + itemscount the From expression would look like this: bpws:getvariabledata( itemsshipped ) + bpws:getvariableproperty( shipnotice, props:itemscount ) The following expression converts a variable and part to a string: string(bpws:getvariabledata('input','parameters')) The following three expressions use similar functions and parameters, but are very different: bpws:getvariabledata('input','parameters')= low Compares the entire value of the input with the string "low", looking for an exact match. contains(bpws:getvariabledata('input','parameters'), low ) Compares the input with "low" and returns true if "low" appears anywhere in the input string. starts-with(bpws:getvariabledata('input','parameters'), low ) Returns true only if the input starts with the characters "low", whether or not there are any other characters after those. Using the Query Builder BPEL Functions String Functions Number Functions Boolean Functions Node Set Functions Example Expressions Custom Functions Technical Requirements and Sample Files Adding Custom Functions to Expression and Query Builders A Copy operation in an Assign activity can contain an XPath query attribute that results in a string, number, or Boolean. The value of the query attribute is a query string that identifies a single value within a source or target variable part. Version 1.5 Chapter 8: Creating an Activity 207

208 The Query dialog is similar to the Expression dialog, with the addition of a Variable Part tree for easy selection of parts. For details on XPath syntax, see the XPath specification at xpath. To build a query: 1 In the Properties view for an assign activity, select Copy operations. 2 In the Copy Operations dialog, select Variable from the Type field. 3 Click the Dialog Button next to Query to display the Query builder. 4 Select the variable parts, functions and operators from the boxes to build a query, following these tips: Double-click a variable part to generate the path information for the query. Double-click a variable to paste the bpws:getvariabledata function into the Query box. Double-click on a branch under a part to paste the bpws:getvariabledata function into the Query box with path information. Double-click a variable property to paste the bpws:getvariableproperty function into the Query box. 208 Using the Query Builder Version 1.5

209 Add your own custom functions, as described in Creating and Using Custom Functions Creating a Join Condition for an Incoming Link A join condition is a Boolean expression indicating the status of a link targeting an activity. When one or more links are connected to an activity, you can set a join condition to evaluate the success or failure of the incoming links. A join condition is a property of all activity types and allows you to construct complex execution conditions based on link status. For more information, see Using Links. When the join condition evaluates to true, the process continues normally. When a join condition evaluates to false, the process can throw a joinfailure fault. If you set the suppressjoinfailure property to yes for an activity that has a join condition, it means that a false join condition will not throw a joinfailure fault. To create a join condition: 1 Display the Properties view of an activity with an incoming link. 2 Click the Dialog Button next to Join Condition to display the following dialog. 3 Double-click a link to paste the BPEL link status function into the Join Condition box. This function returns a Boolean indicating the status of the passed link. 4 Click OK. Version 1.5 Chapter 8: Creating an Activity 209

210 Deadline and Duration Expressions Several activities contain properties to set a deadline or duration. For deadline and duration expressions, you can see the examples given in the XML schema specification. Note: Be sure to enclose deadline and duration values in single quotes, as shown in the examples below. Refer to the following: Examples: A duration of one second: <wait for="'pt1s'"/> A duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes: <wait for= P1Y2M3DT10H30M /> A deadline with a date and time: <wait until= T12:00 /> 210 Deadline and Duration Expressions Version 1.5

211 9 Structuring Activities What s in this chapter Different Ways of Structuring Activities Defining a Container and its Branches and Properties Selecting Activities for Containment ActiveWebflow provides containers to structure activities. Each container has its own rules for how its child activities are executed. The following illustration shows an example of a process using the several nested structures to give you a glance at how to use them. Version 1.5 Chapter 9: Structuring Activities 211

212 Different Ways of Structuring Activities The BPEL language provides ways to structure and nest activities. ActiveWebflow groups the structured activities in the Container palette of the Process Editor. Basic activities execute based on rules and conditions set by a parent container. In addition to using structured containers, you can also structure activities by linking them with the link tool. For more information, see Using Links. The following table provides brief definitions of containers. Table 25: Container Brief Descriptions Container Name Sequence Flow While Pick Switch Scope Description Executes activities in an ordered list Executes all activities in parallel Executes an activity repeatedly until a certain success condition has been met Executes a selected activity based on an incoming message or a time-out event. Includes the Create Instance property to start a process. Executes a selected activity based on branch conditions Provides a context for set of activities, with correlation, compensation, fault handling, event handling and local variables Defining a Container and its Branches and Properties You can select and drag a container to the Process Editor canvas from the Container palette. 212 Different Ways of Structuring Activities Version 1.5

213 After you place a container on the Process Editor canvas, you can define its properties, branches and branch properties. For more information, see: Defining Container Branches Defining Container and Branch Properties Defining Container Branches Several containers execute an activity based on conditional branches. You can define the branches by right-mouse clicking on the container icon on either the Process Editor canvas or the Outline view. The following illustration shows an example for Switch branches. Defining Container and Branch Properties With the activity in focus on the Process Editor canvas, you can set values in the Properties view. The illustration shows an example of the While activity properties. Version 1.5 Chapter 9: Structuring Activities 213

214 To set branch properties: 1 From the Container palette, drag a container to the Process Editor canvas, and ensure it is selected. 2 From the Other palette, drag an appropriate branch activity inside the container. For example, select Case for a Switch activity. Alternately, from the Outline view, right-mouse click and select a branch name. For example, select Case for a Switch activity. 3 Double-click the branch activity to open the appropriate expression builder. The following illustration shows the Case branch highlighted in the Outline view and the Case Expression property in the Properties view. 214 Defining a Container and its Branches and Properties Version 1.5

215 Sequence A Sequence container arranges and executes activities in an ordered list. This means that the first activity in a sequence executes, and when it is finished, the second activity begins. Table 26: Required and optional properties for Sequence Required Properties none Optional Properties Name. See Selecting Activity Labels Suppress Join Failure. See Process Properties Join Condition. See Creating a Join Condition for an Incoming Link Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Sequence: 1 From the Container palette, drag a Sequence activity to the Process Editor canvas. 2 Drag other activities into the Sequence, organizing them from top to bottom or left to right. Tip: You can select activities on the Process Editor canvas and then rightmouse click to select Create Container>Sequence. 3 Set the properties for each activity in the Sequence. XML Syntax <sequence standard-attributes> standard-elements activity+ </sequence> Example <sequence name="sequenceexample"> Version 1.5 Chapter 9: Structuring Activities 215

216 <receive name="receive1" partnerlink="customer" porttype="lns:loanservicept" operation="request" variable="request" createinstance="yes"/> <reply name="reply" partnerlink="customer" porttype="lns:loanservicept" operation="request" variable="approval"/> </sequence> Flow A Flow container executes all activities in parallel. This means you can define two or more activities, such as two Receive activities, to start at the same time. The activities start when the Flow starts. The Flow completes when all the activities in the container have completed. For example, you can receive approval from both a seller and a buyer by adding the seller and buyer Receive activities to a Flow. Both Receives must complete before the process invokes another activity, such as requesting an order shipment. Flows can also contain links which allow you to introduce dependencies between activities to control the order in which they are executed. Refer to Using Links for more information. The Flow is most useful for concurrent execution of activities. Table 27: Required and optional properties for Flow Required Properties none Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Flow: 216 Flow Version 1.5

217 1 From the Container palette, drag a Flow to the Process Editor canvas. 2 Drag an activity, such as Receive, inside the Flow. 3 Continue dragging the other activities into the Flow to execute concurrently. 4 Specify all the properties for each activity in the Flow. The following illustration shows an example of a Flow activity. XML Syntax <flow atandard-attributes> standard-elements <links>? <link name= ncname >+ </links> activity+ </flow> Example <flow name="marketplaceflow"> <receive name="sellerreceive" partnerlink="seller" porttype="tns:sellerpt" operation="submit" variable="sellerinfo" createinstance="yes"> </receive> <receive name="buyerreceive" partnerlink="buyer" porttype="tns:buyerpt" operation="submit" variable="buyerinfo" createinstance="yes"> </receive> </flow> Version 1.5 Chapter 9: Structuring Activities 217

218 While The While activity executes an activity repeatedly until its condition evaluates to false. Table 28: Required and optional properties for While Required Properties Condition Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a While: 1 From the Container palette, drag a While activity to the Process Editor canvas. 2 Double-click the While to open the Condition Builder. For details, see Using the Expression Builder. 3 Drag an activity, such as a Scope or Invoke, inside the While. 4 Specify all the properties for each activity in the While. XML Syntax <while condition= bool-expr standard-attributes> standard-elements activity </while> Example <while condition= bpws:getvariabledata(orderdetails) > 100 <scope>... </scope> </while> 218 While Version 1.5

219 Pick The Pick activity has at least one message and can optionally contain one or more alarms. When the Pick executes, it blocks until one of its messages is received or until one of its alarms go off. Only a single message or alarm ever executes in a Pick since the receipt of the message or the firing of the alarm immediately causes all of the other branches to go Dead Path. For example, a service may implement the process of waiting for a response to a quote by using a Pick with an accept message, reject message, and a timeout. If the accept or reject message is not received within the timeout period, then the alarm activity executes. A Pick activity is a good choice for asynchronous activities. You can also use a Pick activity to start a process with a set of messages and no alarm. This special form of Pick sets the CreateInstance property to yes and executes when the first message arrives. Table 29: Required and optional properties for Pick Required Properties For OnMessage: Partner Link Port Type Operation Variable Optional Properties Name. See Selecting Activity Labels Create Instance Correlations. See Correlation Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process For OnAlarm: Alarm Expression Alarm Type Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link Version 1.5 Chapter 9: Structuring Activities 219

220 To build a Pick: 1 From the Container palette, drag a Pick activity to the Process Editor canvas. 2 Right-click on the activity and select a branch: On Alarm or On Message 3 Select the branch icon. 4 For an On Alarm, do the following: a b c In the Properties view, select an Alarm Type: Duration or Deadline. Click the Dialog Button next to Alarm Expression. In the Expression box, specify one of the following: For a deadline, specify a date and time, such as ' T12:00' For a duration, specify an amount of time, such as '00:00:01' For details and examples, see Deadline and Duration Expressions d Drag an activity, such an Empty, to the On Alarm icon, and select activity properties to reflect the actions to take when the alarm goes off. 5 For an On Message, do the following: a In the Properties view, select the partner link, port type, operation, and variable as input for the Pick activity. b From the Activity palette, drag an activity, such a Receive, to the On Message icon, and select activity properties to reflect the actions to take when the message arrives. The following illustration shows an example of a Pick activity. XML Syntax <pick createinstance= yes no? standard-attributes> 220 Pick Version 1.5

221 standard-elements <onmessage partnerlink= ncname porttype= qname operation= ncname variable= ncname?>+ <correlations>? <correlation set= ncname initiate= yes no?>+ </correlations> activity </onmessage> <onalarm (for=duration-expr until= deadline-expr )>* activity </onalarm> </pick> Example: <pick name="pick1" createinstance="yes" onalarm for= PT30S > </empty> </onalarm> <onmessage partnerlink= customer porttype="lns:loanservicept" operation="request" variable="request" > <reply activity> </onmessage> </pick> Switch A Switch container executes an activity based on branch conditions defined by case elements. Switch contains case conditionals, each followed by an activity. The case conditionals are evaluated in order, and the first one to evaluate to true has its activity executed. The Switch container is a good choice if all cases can be evaluated to a true or false condition. The Switch also has an optional Otherwise branch. If you do not define the Otherwise branch, an implied Otherwise executes an Empty activity. Table 30: Required and optional properties for Switch Required Properties Case Expression Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Version 1.5 Chapter 9: Structuring Activities 221

222 Table 30: Required and optional properties for Switch Required Properties Optional Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Switch: 1 From the Container palette, drag a Switch activity to the Process Editor canvas. 2 Right-click on the activity and select Add Case. 3 Double-click the Case container to open the Case Expression Builder. Alternately, in the Properties view, click the Dialog Button next to Case Expression. 4 Select the variables, functions and operators to build a case statement. For details, see Using the Expression Builder. 5 From the Activity palette, drag an activity to the Case container, and select activity properties. 6 Repeat Steps 2 through 5 for the Add Otherwise branch, if desired. The following illustration shows an example of a Switch activity in Outline view. XML Syntax <switch standard-attributes> standard-elements 222 Switch Version 1.5

223 <case condition= bool-expr >+ activity </case> <otherwise>? activity </otherwise> </switch> Example <switch name="marketplaceswitch"> <case condition="bpws:getvariabledata('sellerinfo', 'askingprice') <=bpws:getvariabledata('buyerinfo', 'offer')"> <assign name="successassign"> <copy> <from expression="'deal Successful'"/> <to variable="negotiationoutcome" part="outcome"/> </copy> </assign> </case> <otherwise> <assign name="failedassign"> <copy> <from expression="'deal Failed'"/> <to variable="negotiationoutcome" part="outcome"/> </copy> </assign> </otherwise> </switch> Scope The Scope activity provides a context for a subset of activities. It can contain fault, event, and compensation handling for activities nested within it and can also have a set of defined variables and a correlation set. A Scope can encompass a logical unit of work, making it manageable to execute, and then, if need be, reverse an activity. For example, if a customer cancels a paid travel reservation, the money must be returned and the reservation must be canceled without affecting other reservations. By enclosing activities in a Scope, you can create the structure and conditions in which to manage activities as a unit. Version 1.5 Chapter 9: Structuring Activities 223

224 Each Scope has a primary activity, which can be a complex structured activity. Table 31: Required and optional properties for Scope Required Properties Variable Access Serializable. Refer to Using Variable Access Serializable in a Scope Optional Properties Name. See Selecting Activity Labels Join Condition. See Creating a Join Condition for an Incoming Link Suppress Join Failure. See Process Properties Comment. See Adding Comments to the Process Setting Visual Properties and Using Your Own Library of Images Execution State. See Viewing the Execution State of an Activity or Link To build a Scope: 1 From the Container palette, drag a Scope activity to the Process Editor canvas. 2 In the Properties view, set Variable Access Serializable to Yes or No. 3 On the Process Editor canvas, right-mouse click the Scope activity to add rules and conditions, including: Correlation Set. For more information, see Correlation Variable. For more information, see Using Variables. Compensation Handler. For more information, see Compensate and Compensation Event Handlers. For more information, see Event Handling. Fault Handlers. For more information, see Fault Handling. 4 From the Activity palette, drag activities to the Scope container, and select activity properties. 5 To view all the activities in the Scope, right-mouse click on the Scope container and select the Show options, as desired. The asterisk indicates an activity is contained. 224 Scope Version 1.5

225 The following illustration shows a sample Scope activity. Note: You can save an activity, or group of activities to the Custom palette for reuse. Because a Scope can be complex, it is a good candidate for re-use. For more information, see Creating a Custom Activity. XML Syntax <scope variableaccessserializable= yes no? standard-attributes> standard-elements <variables>?... </variables> <correlationsets>?... </correlationsets> <faulthandlers>?... </faulthandlers> <compensationhandler>?... </compensationhandler> <eventhandlers>?... </eventhandlers> activity </scope> Example <scope variableaccessserializable= no > <faulthandlers>?... </faulthandlers> <flow> <invoke partnerlink= Seller porttype= Sell:Purchasing operation= SyncPurchase Version 1.5 Chapter 9: Structuring Activities 225

226 inputvariable= sendpo outputvariable= getresponse /> <invoke partnerlink= Shipper porttype= Ship:Orders operation= OrderShipment inputvariable= sendshiporder outputvariable= shipack /> </flow> </scope> See also: Using Variable Access Serializable in a Scope Lifecycle of a Scope Using Variable Access Serializable in a Scope Two Scopes can run at the same time. For example, at the end of the year, a bank executes two activities for each account: add interest and charge credit card costs. These activities can be executed in any order. However, since they both update the account, they cannot be executed at the same time. To ensure that variables referred to within each scope do not conflict, you can enable the Variable Access Serializable property. This property enables serialized access to variables, so that one Scope has access to the shared variables and must finish using them before the concurrently running Scope can use them. Note: The Variable Access Serializable property is not enabled during compensation. For more information, see Compensation. Lifecycle of a Scope When a scope activity executes, it immediately registers any event messages or alarms with the engine prior to the execution of its child activity. Once registered, these messages and alarms are eligible to execute until the scope's child activity completes. If a fault occurs during execution of the child activity or one of the scope's events, then the scope's fault handler attempts to catch the fault. If the fault cannot be caught by the scope, then it is rethrown. The scope is said to have faulted and is not eligible for compensation. 226 Scope Version 1.5

227 If the child activity completes successfully, then the scope completes after uninstalling its event messages and timers, allowing them to complete if they are in the middle of executing. A scope is said to complete normally when it completes without a fault having been caught or rethrown. If a scope completes normally then it is eligible for compensation. Selecting Activities for Containment Here is a tip for easily structuring activities within a Sequence, Scope, or While activity. 1 Drag a selection area around a group of activities and release the mouse. All activities appear selected. 2 Right-mouse click on one of the activities and select Create Container. 3 Select Sequence, Scope, or While. Note: To remove the new container, select it and then select Undo New Container from the right-mouse menu. If you have already saved the process file, you can remove the container by dragging activities out of the container and then deleting it. You can also remove activities from a container by re-ordering them within the Outline view. Version 1.5 Chapter 9: Structuring Activities 227

228 228 Selecting Activities for Containment Version 1.5

229 10 Using Variables What s in this chapter Overview of Variables Adding a Variable Viewing Variables Deleting a Variable Using Sample Data Finding Variables Where Used Using Variables in a Copy Operation ActiveWebflow Designer provides many tools and shortcuts to define and use variables within a BPEL process. Overview of Variables A BPEL process receives, manipulates, and sends data through variables. Variables hold the messages exchanged between business partners and data used within the process. For example, a process that receives a purchase order message from a buyer puts the message in an input variable. From there the variable content can be accessed by other operations. The following illustration shows an example. Version 1.5 Chapter 10: Using Variables 229

230 Variables are defined in one of the following ways: WSDL Message Types XML Schema Simple Type XML Schema Element XML Syntax <variable name= ncname messagetype= qname? type=qname? element=qname?/>+ Adding a Variable Process Variables consist of three types: message, schema simple, and schema element. A message type is declared in a WSDL namespace that is referenced in your process. You can add message type variables to your process automatically when you create a Receive, Invoke, or Reply activity from a Web Reference. For details, see Creating an Activity by Starting with a Web Reference. You can also add variables to your process manually. Before manually adding a variable, ensure that an appropriate WSDL namespace is defined. For more information, see Importing WSDL Locations and Namespaces. You can declare global variables, accessible by the process as a whole, and you can declare local variables for use within a Scope. Local variables can have the same 230 Adding a Variable Version 1.5

231 name as global variables. If a local variable has the same name as a global variable, only the local variable is used in assignments within the Scope. To define a global variable: 1 In Outline view, right mouse click on Variables and select Add Variable. 2 Double-click the new variable, or in the Properties view, click the Dialog Button next to Definition to open the Definition dialog. 3 In the dialog, select the variable type: WSDL message (See WSDL Message Types) Schema type (See XML Schema Simple Type) Schema element (See XML Schema Element) 4 Select the name you need from the list that appears, and click OK. To define a local variable: 1 Select a Scope from Outline view. 2 Complete Steps 2-4 above. Variables are listed in the order they are created. To re-order the list, move a variable up or down in the Outline view. WSDL Message Types A WSDL message type variable uses a message type declared in a WSDL namespace that is referenced in your process. Only variables that are defined using message types can be used as input or output targets in activities. The following illustration shows an example of a variable defined as a WSDL message type. The message type namespace is declared in the BPEL process. Version 1.5 Chapter 10: Using Variables 231

232 XML Schema Simple Type An XML schema simple type variable uses a simple type of element built into the schema of the currently defined namespace(s). For example: <variable xmlns:props= name= itemsshipped type= props:itemcounttype /> XML Schema Element An XML schema element variable uses an element defined in the schema of the currently defined namespace(s), as shown in the following example. 232 Adding a Variable Version 1.5

233 Viewing Variables The Process Variables view has several features to help you easily define and use variables, such as: Quickly view variable(s) in use by selecting an activity in Outline or Process Editor canvas. See Quick View of Variables Used in Activities. Search for all uses of a variable using Find Where Used. See Finding Variables Where Used. View a complete variable definition (message and parts, path, properties, elements and their attributes, and simple types). See Using the Process Variables View Options and Understanding Icons, Symbols, and Descriptions of Variable Parts. Drag and drop variables to create Copy operations for new or current Assigns. See Using Variables in a Copy Operation. Select and edit sample data for message and element variables. See Using Sample Data. The following illustration shows an example of Process Variables list. Quick View of Variables Used in Activities When you select an activity on the Process Editor canvas or Outline view, the variables used in the activity appear selected in the Process Variables view. Version 1.5 Chapter 10: Using Variables 233

234 Using the Process Variables View Options Use the drop-down list of options on the Process Variables toolbar for convenience. The following table lists the options. Table 32: Option View Variable Hide Variable List Show Variable Data Show Variable Definition Layout Horizontal Layout Vertical Reload Variable Data Description Shows the variable list and lets you open a variable. Useful if the list is hidden. See Opening a Variable to View its Definition. Makes more room for open variables in the view by hiding the list of variables Displays variables in sample data view Displays variables in definition view Opens variables from left to right Opens variables from top to bottom Displays last saved version of sample data Tip: To rearrange the list of variables in Process Variables view, go to the Outline view and move variables up or down. Opening a Variable to View its Definition In the Process Variables view, you can open one or a selection of variables. To open one variable, double-click it To open a selection of variables, select them, and then select Open All from the right-mouse menu Select Open All to open all variables in the list The following illustration shows an example of the BuyerPO variable opened. 234 Viewing Variables Version 1.5

235 Understanding Icons, Symbols, and Descriptions of Variable Parts To understand each part of a variable, rest your mouse over it to view a description, as shown. A variable definition can include: Message parts and properties WSDL schema simple types WSDL schema elements and attributes An icon appears to the left of a variable part, property, element, or attribute. The icon, such as a pair of brackets (< >), is associated with a structural entity, such as an element. Version 1.5 Chapter 10: Using Variables 235

236 Variables used in copy operations have additional visual information, as described in Creating a Copy Operation Using Drag and Drop. In addition, to the right of a part, a symbol may appear, including: Asterisk, indicating a required field Ellipsis, indicating a repeating element Deleting a Variable You can delete a variable from your process. 1 Select Process from the ActiveWebflow main menu. 2 Select Delete>Variable. 3 Select a variable from the Delete Variable dialog, and click OK. Using Sample Data You can add sample data values for variables in the Process Variables view. During process simulation, sample values are used as the default variable values. If you have added samples to Web Reference messages, the default sample value from Web Reference messages is automatically loaded into message type variables. For more information, see Adding a Sample Data File in Web References. You can type in data values for simple type variables or load an XML data file for any variable defined as a schema type or any variable part that is complex. To add a single sample data value: 1 Open a variable in the Process Variables list. 2 Right-mouse click on the variable name or part name, and select Variable> View Data. 3 Double-click the variable to open the Edit Sample Data dialog, as shown. 236 Deleting a Variable Version 1.5

237 4 Type in a value and click OK. Notice that the value is displayed in the Data column of the open variable. For convenience, you can prepare an XML data file for complex variables and then add the sample, as described in Using Sample Data for WSDL Messages. To load sample data: 1 Create an XML file of sample data to represent a message or element structure from a WSDL namespace. The XML file must conform to the schema for the message type or element. 2 For convenience, add the sample data to Web References. Web Reference samples can be used across BPEL processes. See Creating a Sample Data File and Adding a Sample Data File in Web References for more information. 3 Open a complex variable in the Process Variables list. 4 Right-mouse click on the variable name or part name, and select View Data. 5 Right-mouse click on a variable part and select Load Data. 6 Select one of the following: Web References Default. Select this to re-load the default file, if you have changed the default. From File System. Select this to load an XML file that has not been added to a Web References message. From Web References. Select this if you have sample XML files for Web References messages. 7 After you select a file, you can expand the complex part to view data values. You can edit data from the sample file and then save it or save it as a new file. Version 1.5 Chapter 10: Using Variables 237

238 Each time you open View Data, ActiveWebflow displays the previously loaded data values. You can add several sample files for one Web Reference message. One file is the default, as shown in the following illustration. You can load any of the Web Reference message samples into the process variable. Finding Variables Where Used You can search for all occurrences of a variable in activities and links by using the Find Where Used right-mouse menu from a variable in the Process Variables list. 238 Finding Variables Where Used Version 1.5

239 You can also search for all variable used in Copy operations. To search for occurrences of the variable in Copy operations, select Find Where Used from the Copy right-mouse menu on a variable, as shown. Search from the Process Variable List Search Copy Operations ActiveWebflow displays the search results and highlights the first result in the Process Editor canvas and Outline view. From the Outline view, you can select an activity, link, or Copy operation for editing. Using Variables in a Copy Operation Within the Process Variables view, you can create and edit Copy operations for a current Assign or create a new Assign automatically. You can create a Copy operation by using a variable s context menu or by dragging and dropping a variable part to another variable part. For more information, see: Creating a Copy Operation Using a Context Menu Creating a Copy Operation Using Drag and Drop Selecting a Copy Operation to Edit Creating a Copy Operation Using a Context Menu Tip: Use this procedure to create any type of Copy operation. For a quicker way to create a variable-to-variable Copy operation, see Creating a Copy Operation Using Drag and Drop. Version 1.5 Chapter 10: Using Variables 239

240 1 Do one of the following: Select an Assign activity from the Process Editor canvas, if you want to add a Copy operation to it. The Copy will be added after any current Copy operations. Go to Step 2 if you want to create a new Assign activity automatically. 2 In the Process Variables list, open a variable for either the From or To clause of the Copy operation. 3 Right-mouse click and select Copy>From to create the From clause or Copy> To to create the To clause. 4 In the Copy Operations dialog, complete the remaining clause, and click OK. In the Process Editor canvas and Outline view, the current or new Assign activity is selected. Creating a Copy Operation Using Drag and Drop You can create the following types of Copy operations by dragging and dropping: From Variable [Part] To Variable [Part] From Variable Property To Variable Property For details, see Assign. To create a Copy operation by drag and drop: 1 Do one of the following: Select an Assign activity from the Process Editor canvas, if you want to add a Copy operation to it. The Copy will be added after any current Copy operations. Go to Step 2 if you want to create a new Assign activity automatically in the currently selected Scope. 2 In the Process Variables list, open the two variables for the From and To clauses of the Copy operation. 3 Drag the variable, part, or property of the From variable to the appropriate variable, part, or property of the To variable. Tip: Before you release the mouse button, you can view the Copy specification in the ActiveWebflow status bar. 240 Using Variables in a Copy Operation Version 1.5

241 After you release the mouse button, ActiveWebflow shows the results by highlighting the parts in use. Also, the From part icon has an outward arrow and the To part icon has an inward arrow, as shown. In the Process Editor canvas and Outline view, the current or new Assign activity is selected. Selecting a Copy Operation to Edit You can edit a Copy operation by selecting Copy>Edit from a variable s right mouse menu. If a variable has multiple Copy operations, the Copy Operations dialog opens so that you can select an operation to edit. Using Variables Based on WSDL Fault Messages Fault names and variables are based on WSDL fault messages are used within BPEL fault handling constructs. For details on defining and using fault names and variables within a scope or within the process as a whole, see Fault Handling. Version 1.5 Chapter 10: Using Variables 241

242 242 Using Variables Based on WSDL Fault Messages Version 1.5

243 11 Using Links What s in this chapter What is a Link? Adding a Link Between Activities Execution Rules for Links Designing With Links vs. Structured Activities Links and the Join Condition What is a Link? Use links to control process execution. A link is a structure that connects two activities and controls the order of execution of the two activities. A link can include a condition, further controlling when, or if, an activity executes. The condition is an XPath expression. You can add multiple links between basic activities and between structured activities. You can also add links to a basic activity contained by a structured activity. A link works inside of a flow. When you add a link between two activities, ActiveWebflow Designer creates a Flow activity including a link definition, as shown. Link XML Syntax <flow> <link name= L1 /> activity1 <source linkname= L1 />... activity2 <target linkname= L1 />... </flow> For more information about when to use links vs. using sequence, scope and other structured activities, see Designing With Links vs. Structured Activities. Version 1.5 Chapter 11: Using Links 243

244 Adding a Link Between Activities Add a link between two activities to control the order of execution of the activities. You can add a link with a transition condition or without one. For more information, see: Adding a Link with no Transition Adding a Link with a Transition Condition Link Examples Adding a Link with no Transition Add a simple link from a source activity to a target activity to require the source to finish successfully before the target executes. 1 Ensure that two activities are on the Process Editor canvas that you want to link. 2 Select the source activity and then use Shift plus select to select the target activity. 3 Select the Link toolbar button or select Link Activities from the right mouse menu of one of the activities. 4 ActiveWebflow names the link L1. You can double-click the link to open the Transition Builder dialog. 5 In the Properties view, you can rename the link, if desired. Tip: You can use the Link tool in the Palette, if desired. To do so, select the Link tool and then select the source activity. Connect the link to the target, as shown on the left in the illustration. Select the Select tool to turn off the Link tool. 244 Adding a Link Between Activities Version 1.5

245 Adding a Link with a Transition Condition Add a link with a transition condition based on the completion of the source activity. The condition must evaluate to a Boolean true before the target activity can begin. 1 Complete the steps for drawing a link, described in Adding a Link with no Transition. 2 Select a link and double-click it. Alternately, in the Properties view, click the Dialog Button next to Transition Condition. 3 Build an XPath expression, as described in Using the Expression Builder. The following illustration shows an example of condition that prevents an activity from executing if an amount is too large. In the example above, the getvariabledata parameters refer to a BPEL process variable holding data from a WSDL message. For more information, see Using Variables. Using the Add Link Dialog To add a link between two activites you can do one of the following: Select a source activity and then select a target activity. Select the Link toolbar button to create the link. You can also select multiple activities and the links are created in the selection order. See Adding a Link Between Activities for details. Use the Link tool in the Palette. See the tip in Adding a Link Between Activities for details. Use the Add Link dialog Version 1.5 Chapter 11: Using Links 245

246 To use the Add Link dialog: 1 Select an activity on the Process Editor canvas. For example, select a receive or a sequence. 2 From the right-mouse menu, select Link (or Add>Link). 3 Fill in the Add Link dialog as follows: a b c d e In the Name field, accept the default or type in a more meaningful link name. In the Target field, select the Dialog Button. In the Select Link Target Node dialog, select the target activity for the link, and click OK. If desired, add a Transition Condition for the link by double-clicking the link or by selecting the Dialog button in Properties view to open the Transition Builder. See Adding a Link with a Transition Condition for details. Select OK on the Add Link dialog. Link Examples The following illustrations show some ways you can use links. You can also consider Designing With Links vs. Structured Activities. In the first example, the second sequence executes if the link evaluates to true, otherwise the reply executes. 246 Adding a Link Between Activities Version 1.5

247 In the following example, two sequences are running in parallel. An activity in one sequence has a link to an activity in the other sequence. Version 1.5 Chapter 11: Using Links 247

248 Execution Rules for Links Once an activity completes, it evaluates any condition on the outgoing link(s). If no condition is defined, and the activity has completed normally, then all conditions evaluate to true so that the next activity can start. However, an activity can have a join condition set which further constrains execution. For more information, see Links and the Join Condition. If an activity has faulted, or could not be run, then all conditions evaluate to false. An activity can have multiple incoming links. The activity must wait to run until at least one of its incoming links evaluates to true. If all incoming links are false, the activity cannot run unless a supressjoinfailure property is true. A link can cross the boundary of a structured activity, except the following: While activity Serializable Scope Event handler Compensation handler A link that crosses the boundary of a fault handler must have its source within the fault handler and its target within a scope that encloses the fault handler scope. A link cannot create a control cycle by linking to a completed activity. Designing With Links vs. Structured Activities You can often set up the same execution order for activities using either links or a sequence. The following example shows two execution designs that are identical. 248 Execution Rules for Links Version 1.5

249 The following illustration shows another example of two identical execution designs, one using a switch activity and the other using links. There are many cases when you can design an execution path only with links. For example, you can link an activity from within a container to another activity in a different container. Links and the Join Condition You can control the start of an link-targeted activity by writing an expression for a join condition property. For more information, see Creating a Join Condition for an Incoming Link. Version 1.5 Chapter 11: Using Links 249

250 250 Links and the Join Condition Version 1.5

251 12 Compensation What s in this chapter What is Compensation? Compensation Handlers and Compensate Activities Adding a Compensation Handler to a Scope Compensating an Invoke Activity What is Compensation? Compensation enables a business process to define an activity at the scope or process level whose execution serves to reverse some previously executed application logic. There is no automatic restoration of data during compensation. It is up to the application to define its own compensation behavior. Some examples of compensation are cancelling a reservation, putting an order on hold, or removing a charge on a credit card. A business process can continue running even if part of it must be reversed. The following illustration shows an example of an OnMessage part of an Event Handler causing the business process to cancel an inventory order and send out an order cancellation notice. The activities of an already completed scope are the ones that are compensated. Version 1.5 Chapter 12: Compensation 251

252 1 When the event handler receives an order cancellation message, it throws a fault to the fault handler 2 The fault handler executes a compensate activity for the previously completed scope that it is linked to 3 The compensation handler for the completed scope rolls back the work of the Invoke- OrderInventory service Compensation handling is associated with a scope. A scope can be thought of as a logical unit of work, with a set of activities that may need reversal, and perhaps retrying, while other parts of the process can continue normally. The compensation actions might need to run in the same order as the original actions. Compensation and the State of Variables The compensation handler, if invoked, sees a frozen state of locally defined scope variables as they were when the scope being compensated was completed. If the 252 What is Compensation? Version 1.5

253 scope executed multiple times in a loop, then each compensation instance records the values of the local variables at the time of the scope s completion. Compensation Handlers and Compensate Activities You can add compensation handling as follows: Define a compensation handler for a scope. The compensation handler can only have a single child activity, but this activity can be a structured activity like a sequence which itself has child activities. The contents of the compensation handler depend on your application logic. Use a Compensate activity within a fault handler or compensation handler to specify compensation for a named, inner scope. This method provides control over the order and selection of compensation activities in a scope. You can also specify a Compensate activity in the form <compensate/>, which causes the default behavior to be invoked explicitly. This is useful when you have one or more enclosed scopes that you want to compensate, and you want them all to be compensated. If you want finer control over the order of compensation or if you only want to control compensation based on some process state then you will need to use the form of <compensate> that takes the scope name as a parameter. Keep in mind that you cannot mix the use of the default compensation form and the named compensation form. If both were to execute, or if you attempted to compensate a named scope twice, then you would get a bpws:repeatedcompensation fault. The following illustration compares default and specified compensation. Default-order compensation Specified compensation Implicit Compensation Version 1.5 Chapter 12: Compensation 253

254 In the case where a scope does not define a compensation handler, the execution engine provides an implicit compensation handler. This handler contains a single <compensate> activity which compensates all of the enclosed scopes that have completed and are eligible for compensation. In general, you should only provide a compensation handler when you have some application-specific logic to execute in order to undo some previously executed logic. See also: Default-Order Compensation Example Specified Compensation Example Default-Order Compensation Example Default compensation processing is available from the compensate activity with the form <compensate/>. The activity invokes the compensation handlers on all of the enclosed scopes that are eligible for compensation. The scope s compensation handlers are invoked in the reverse order of completion. If a scope executed multiple times in a <while> loop, then it is eligible for each execution instance where it completed without having a fault generated. The following example shows how a confirmed purchase order is cancelled. The CancelPurchase operation compensates the SyncPurchase operation in an already completed Invoke activity. <scope> <compensationhandler> <invoke partnerlink= Seller porttype= Sell:Purchasing operation= CancelPurchase inputvariable= getresponse outputvariable= getconfirmation > <correlations> <correlation set= PurchaseOrder pattern= out /> </correlations> </invoke> </compensationhandler> <invoke partnerlink= Seller porttype= Sell:Purchasing operation= SyncPurchase inputvariable= sendpo outputvariable= getresponse > <correlations> <correlation set= PurchaseOrder initiate= yes pattern= out /> </correlations> </invoke> </scope> See also Specified Compensation Example. 254 Compensation Handlers and Compensate Activities Version 1.5

255 Specified Compensation Example The following example shows how a Compensate activity is incorporated into a fault handler. For more information, see Fault Handling. <faulthandlers> <catch faultname="lns:loanprocessfault" faultcontainer="error"> <sequence name="fault-sequence"> <compensate scope="assessor-scope"/>... </sequence> </catch> </faulthandlers> See also Default-Order Compensation Example. Adding a Compensation Handler to a Scope A scope s activities can be compensated, or reversed, when the scope is completed and when another activity causes compensation to begin. To add a compensation handler to a scope: 1 From the Process Editor canvas, select a scope. 2 Right-mouse click and select Show Compensation Handler. 3 From the Activity palette, drag appropriate activities into the compensation handler, that will reverse the work of the scope s main activity. 4 From another scope, create an activity that triggers the compensation handler for the completed scope. The following illustration shows a scope and its compensation handler. Version 1.5 Chapter 12: Compensation 255

256 Compensating an Invoke Activity The BPEL4WS 1.1 specification provides a shorthand construct for adding an optional compensation handler and fault handler to an invoke. This is referred to as an implicit scope. If you import a BPEL file with compensation handlers written for an invoke activity, the invoke appears inside of a scope on the Process Editor canvas. For information on creating a compensation handler for a scope, see Adding a Compensation Handler to a Scope. Enabling Instance Compensation You can specify whether the process as a whole can be compensated by platformspecific means. The process instance can be compensated after normal completion. The Enable Instance Compensation setting can be specified for the current process or as a preference for all new processes. See Process Element and Properties and ActiveWebflow Preferences. 256 Compensating an Invoke Activity Version 1.5

257 13 Correlation What s in this chapter What is Correlation? What is a Correlation Set? Creating Message Properties and Property Aliases Adding a Correlation Set Deleting a Correlation Set Adding Correlations to an Activity Rules for Declaring and Using Correlation Sets What is Correlation? Correlation is a construct for keeping track of a group of messages that belong together in one particular business partner interaction. Correlation matches messages and interactions with the business process instances they are intended for. When a BPEL engine receives a message, it looks for a process that can handle the message. Some messages cause a new process instance to be created. Other messages need to be sent to an already-running process. How is that process found? It is found by matching the contents of a correlation set. The data within the correlation set is the signature that lets the engine match the message to the process expecting that message. You can add correlation to Receive, Pick, Reply, Invoke, and Event handler activities for this purpose. The steps for adding correlation to a process are shown in the following illustration. Version 1.5 Chapter 13: Correlation 257

258 Select a link for details about each step 1 Creating Message Properties and Property Aliases 2 What is a Correlation Set? and Adding a Correlation Set 3 Initiating and Setting Patterns for Correlation 4 Adding Correlations to an Activity What is a Correlation Set? A correlation set is a set of properties shared by messages. The purpose of the correlation set is to act as a conversation identifier: it keeps together all messages intended for the same conversation. A message can have several properties, each defined as a property alias. Properties A property must be a schema simple type like an xsd:int or an xsd:string. For example, a property might be a purchase order number or a customer Id. A property exists within a WSDL message that is transmitted during a Web service interaction. A single message may contain multiple properties and a single property might exist in several messages. 258 What is a Correlation Set? Version 1.5

259 Property Aliases For each pairing of a message and a property there exists a property alias which identifies how to extract the value of a property from the given message, whether the message part is a simple type, schema element, or complex type. If the part is an element or a complex type then an XPath query is required to identify the location of the property within the element or type. For example, a purchase ordering process might define a property called OrderId. This property could exist in multiple messages like the purchase order, acknowledgement, and invoice messages. Each of these messages may store the value of the order Id in a different part of the message. A property alias must exist for each message that contains the property in order to determine how to extract the value for the order Id. A specific process instance is identified by a unique order Id such that no two processes will ever have the same value for order Id. This ensures that when a message arrives it is dispatched to the correct process instance. The following illustration shows how a message property alias is mapped to a property name. The property name is mapped to a correlation set. For more information, see: Creating Message Properties and Property Aliases WSDL Syntax for Property Names and Aliases Global and Local Correlation Sets Version 1.5 Chapter 13: Correlation 259

260 WSDL Syntax for Property Names and Aliases Use ActiveWebflow s wizard to automatically create message properties and property aliases, described in Creating Message Properties and Property Aliases. The wizard generates WSDL code shown in the following examples. The WSDL syntax for a property name is: <wsdl:definitions name= ncname xmlns:bpws= http//schemas.xmlsoap.org/ws/2003/03/businessprocess/ > <bpws:property name= ncname type= qname />... </wsdl:definitions> The WSDL syntax for a property alias is: <wsdl:definitions name= ncname xmlns:bpws= http//schemas.xmlsoap.org/ws/2003/03/businessprocess/ > <bpws:propertyalias propertyname= ncname messagetype= qname part= ncname query= querystring />... </wsdl:definitions> Property and Property Alias Example <bpws:property name="negotiateditem" type="xsd:string"/> <bpws:propertyalias propertyname="tns:negotiateditem" messagetype="tns:sellerinfomessage" part="inventoryitem"/> <bpws:propertyalias propertyname="tns:negotiateditem" messagetype="tns:buyerinfomessage" part= item /> <bpws:propertyalias propertyname="tns:negotiateditem messagetype="tns:shipmentnotificationmessage" part="notice query="/notice/s:item"/> In the example above the property negotiateditem exists in three different messages. Two of the messages contain the value of the property in a part of the message that is a simple type. In this case, the property alias needs to identify only the message type and part in order to extract the property. In the case of the shipmentnotificationmessage, the message part is a complex type and contains the inventory item as part of its type. In this case, an XPath query is required to extract the value of the property from the message. Global and Local Correlation Sets You can declare a correlation set for the process as a whole or for a scope. If you declare the correlation set locally for a scope, it is applicable only to the activities in the scope. You can hide a global correlation set by declaring a correlation set of the identical name in a scope. 260 What is a Correlation Set? Version 1.5

261 Creating Message Properties and Property Aliases You use message properties and property aliases to create a correlation set. For an overview, see What is Correlation? and What is a Correlation Set?. If your WSDL file does not include message property definitions, you can add them automatically to an existing WSDL or create a new WSDL for them. The property is automatically added to the corresponding process variables. Before you create message properties, ensure that your BPEL process references a WSDL file in the Imports section of the Outline view. See Importing WSDL Locations and Namespaces for details. To add message properties and aliases, see: Creating a Message Property Definition Creating a Message Property Alias Creating a Message Property Definition You can create a message property as follows: 1 From the Outline view, right-mouse click on Correlation Sets, and select Add Correlation Set. 2 In the Correlation Set Properties dialog, select New. 3 In the Property Definition dialog, select a Name for the message property (for example, OrderId). 4 Select a schema simple type from the list to identify the property type. 5 Select whether to add the message property definition to an existing WSDL or to create a new WSDL. If the WSDL referenced in your process is an URL or otherwise shared by many partners, it is probably best to create a new WSDL. 6 To create a new WSDL, do the following: a Type in a Target Namespace for the WSDL (for example, urn:mynewnamespace). b Select Browse, and in the Open dialog, browse to a Navigator project or file system location. c Type in a filename for the WSDL file, and click Open. d Click OK and skip to Step 8. Version 1.5 Chapter 13: Correlation 261

262 7 To add to an existing WSDL, select a WSDL from the drop-down list. The list consists of WSDLs that have been added to Web References. Click OK. 8 In the Available Properties list of the Correlation Set Properties dialog, notice that the new property is listed. 9 Do one of the following: Continue to Creating a Message Property Alias Click OK to close the dialog. You can add property aliases later. They are required before you can add a correlation set. If you create a new WSDL, ActiveWebflow does the following: Adds the WSDL to the Imports section of the Outline view Adds the new namespace to the process Adds an <import> element to the new WSDL to reference the process WSDL file. This allows you to select appropriate messages for property aliases. If you created the new WSDL in a workspace project, you can select the project in the Navigator and select Refresh from the right mouse menu. The new file appears after you refresh. If you added the message property definition to an existing WSDL, the existing WSDL in Web References has been modified. Creating a Message Property Alias You can create message property aliases after creating a message property in the Add Correlation Set dialog. 1 Select a message property from the Available Properties list in the Add Correlation Set dialog. 2 Select Property Aliases. 3 In the Property Aliases dialog, select New. 4 In the Define Property Alias Details dialog, select a Message Type from the list. The list contains messages from namespaces imported into the process. 5 Select a Message Part for the property alias, as shown in the example. 262 Creating Message Properties and Property Aliases Version 1.5

263 6 If the message part is a complex type, type in a Query or select the Dialog button to open the Query Builder and add the selection node from the part. 7 Click OK. 8 Repeat the steps above to add property aliases for all messages that should be included for the property. Your selections depend on how you want to group messages for correlation. After you add a property alias, ActiveWebflow displays the property for the process variable, as the example shows. ActiveWebflow also adds the property and property alias to the WSDL View of Web References, as shown. Version 1.5 Chapter 13: Correlation 263

264 Tips for creating property aliases: You can add property aliases one at a time. You need to refresh Imports to view a property added to a message. In Outline view, select Refresh Imports from the Imports right mouse menu. You can edit and remove property aliases as needed. The WSDL file and relevant process variables get updated correctly. Adding a Correlation Set Before adding correlation to an activity, you must create the correlation set. To create the correlation set, you identify message properties from a WDSL file that map to correlation properties, as described below. You can add a correlation set to process activities or to a scope. For more information, see Global and Local Correlation Sets. To add a correlation set: 1 Ensure that a WSDL file is available that contains defined message properties and property aliases. For more information, see What is a Correlation Set? 2 Do one of the following: To add a correlation set for the process, from the Outline view, right-mouse click on Correlation Sets, and select Add Correlation Set To add a correlation set to a scope, right-mouse click on the scope, and select Add Correlation Set 264 Adding a Correlation Set Version 1.5

265 3 Select a property from Available Properties and move it to the Selected Correlation Set Properties list. 4 Repeat by selecting more properties if applicable for this correlation set. XML Syntax <correlationsets>? <correlationset name= ncname properties= qname-list />+ </correlationsets> Example <correlationset name= PurchaseOrder properties= cor:customerid cor:ordernumber /> Deleting a Correlation Set You can delete a correlation set from the process or from a scope. To delete a correlation set from the process: 1 Click on a blank spot in the Process Editor canvas. 2 Select Process from the ActiveWebflow main menu. 3 Select Delete>Correlation Set. Version 1.5 Chapter 13: Correlation 265

266 4 Select a correlation set and click OK. To delete a correlation set from a scope: 1 In Outline view, expand a Scope node to view correlation sets 2 Right-mouse-click on a correlation set, and select Delete. Adding Correlations to an Activity You can add correlations to the Web service interaction activities, namely: Receive Reply Pick (OnMessage branch) Invoke Event handler (OnMessage variant) It is a best practice to create one correlation set per conversation. A conversation is an interaction between two services about one subject, such as an invoice or a customer order. Each activity that receives input or sends output about the subject should include correlation. After you add correlation to an activity and save your process file, the Problems view shows warning messages for the related activities that should be correlated. For a discussion of correlation attributes that you must set, see Initiating and Setting Patterns for Correlation. To add correlation, see Adding Correlation to a Receive, Reply, or OnMessage and Adding Correlation to an Invoke Activity. The following illustration shows activities (in boldface) that include correlation. The correlation set in use is associated with the Order Id message property. Because activities are correlated, messages arrive and leave from process instance they are intended for. 266 Adding Correlations to an Activity Version 1.5

267 Initiating and Setting Patterns for Correlation Each usage of a correlation set on an activity requires the setting of an initiate attribute. The value for this attribute is yes no. A yes means that the execution of the Web service interaction populates the correlation set with the values from the message being transmitted. This only occurs if the correlation set is currently empty since correlation sets are immutable and can have their values set only once. Correlation sets can be initiated with the transmission of a message or the receipt of a message. Note the following examples for different activity types. Receive and OnMessage These activities both receive messages. If the correlation initiate attribute is yes and the correlation set is currently empty, then the process accepts any message that matches the partner link, port type, and operation attributes for these activities. Upon receipt of that message, the correlation set is initiated with the properties contained in that message. If the correlation set has already been initiated from a previous Web service interaction then the process accepts a message for this activity only if it matches the correlation properties in addition to the partner link, port type, and operation. Reply Version 1.5 Chapter 13: Correlation 267

268 A reply transmits data. If its correlation initiate attribute is set to yes then the correlation set is initiated with the values from the message being transmitted. If it is set to no then the message is validated against the values currently in the correlation set to ensure that the message is being transmitted with the correct data. Invoke An invoke transmits data and can also receive a response from the target Web service. The invoke activity adds an additional parameter to the correlation usage to account for its dual nature. The pattern attribute describes when the correlation set should be used. If it is set to out then it applies only to the outbound message. In this case the input variable for the invoke is validated against the correlation set to ensure that the correct data is being transmitted. In the case of in, it ensures that the output variable populated from the invoked Web service matches the data in the correlation set. In the case of out-in the data is validated on the way out and the way in. If a correlation set is used prior to its initiation (i.e., the initiate attribute is no) then the BPEL engine throws a bpws:correlationviolation fault. This same error is thrown if a correlation set is used to validate the transmission of data that does not match. For more information, see Adding Correlation to a Receive, Reply, or OnMessage and Adding Correlation to an Invoke Activity. Adding Correlation to a Receive, Reply, or OnMessage Before adding correlation to an activity, create a correlation set. For more information, see Adding a Correlation Set. For help in initiating correlation, see Initiating and Setting Patterns for Correlation. 1 On the Process Editor canvas, select a Receive, Reply, or OnMessage branch of a Pick activity. 2 In the Properties view, click the Dialog Button next to Correlations. 3 Select a Correlation Set from the drop-down list. 4 Do one of the following: Select Yes for Initiate to start correlation in this activity. Select No if this activity does not initiate correlation. 268 Adding Correlations to an Activity Version 1.5

269 5 If desired, select Add to add another correlation set for this activity. 6 If desired, reorganize a correlation set by moving it up or down in the list. The order of correlation sets is not significant for processing. Organize the list as you prefer. Example <receive createinstance="yes" name="sellerreceive" operation="submit" partnerlink="seller" porttype="tns:sellerpt" variable="sellerinfo" <correlations> <correlation initiate= yes set="negotiationidentifier"/> </correlations> </receive> Adding Correlation to an Invoke Activity Before adding correlation to an activity, create a correlation set. For more information, see Adding a Correlation Set. For addtional help, see Initiating and Setting Patterns for Correlation. 1 On the Process Editor canvas, select an invoke activity. 2 In the Properties view, click the Dialog Button next to Correlations. 3 Select a correlation set from the drop-down list. 4 Do one of the following: Version 1.5 Chapter 13: Correlation 269

270 Select Yes for Initiate to start correlation in this activity. Select No if this activity does not initiate correlation. 5 Set Pattern to one of the following: In to correlate the input message Out to correlate the output message Out-In to correlate both messages 6 If desired, select Add to add another correlation set for this activity. Example <invoke partnerlink= Seller operation= SyncPurchase porttype= sp:purchasingpt inputvariable= sendpo > outputvariable= getresponse > <correlations> <correlation initiate= yes set="purchaseorder" pattern= out > <correlation initiate= yes set="invoice" pattern= in > </correlations> </invoke> Adding Missing Correlation It is recommended that you add correlation to all Web service interaction activities that exchange the messages containing the correlation property. 270 Adding Correlations to an Activity Version 1.5

271 After you initiate correlation and save the.bpel file, ActiveWebflow adds a warning to the Problems view for each activity in the process that should also include correlation. To view the warnings, you must have warning tasks enable in Window>Preferences>ActiveWebflow>Tasks. Rules for Declaring and Using Correlation Sets A correlation set is declared within a scope, similar to a variable declaration. You can declare both global and local correlation sets. You can hide a correlation set in an outer scope by declaring a correlation set with an identical name in an inner scope. If you declare the correlation set locally for a scope, it is applicable only to the activities in the scope. You can hide a global correlation set by declaring a correlation set of the identical name in a scope. A correlation set can be initiated only once during the lifetime of the scope it belongs to. A correlation set must be initiated. After a correlation set is initiated, the values of the properties for a correlation set must be identical for all messages in all operations in the scope. Version 1.5 Chapter 13: Correlation 271

272 272 Rules for Declaring and Using Correlation Sets Version 1.5

273 14 Event Handling What s in this chapter What is Event Handling? Adding Event Handlers Processing Rules for Events What is Event Handling? Event handling is an activity that runs concurrently with a scope. Events can be one of two types: a message or an alarm. When an event occurs, the event handler associated with it invokes an activity. Event handlers are especially helpful for events and requests that cannot be scheduled relative to the main activity, but may occur at unpredictable times. For example, a customer may cancel an order that is being processed. Event handlers are considered part of the normal behavior of the scope, unlike fault and compensation handlers, which take over normal processing. An event handler can be attached to the process as a whole or to a scope. This means events can occur and be handled while the corresponding scope is active. One or more events can occur and be handled at any time while the corresponding scope is active. An event handler cannot be enabled until a process instance is created. Event Types An event can be an incoming message that corresponds to a request/response or one-way operation in a WSDL. For example, a status query is likely to be a request/response operation, whereas a cancellation may be a one-way operation. An event can also be an alarm that goes off after a set time. Version 1.5 Chapter 14: Event Handling 273

274 Examples of Event Handler Activities When a message that triggers an event is received, one of the following may be the likely response by an event handler: Send a reply Terminate the process instance. For example, an order is cancelled, so the process instance should be cancelled, and there is no ongoing work to be undone and compensated. Throw a fault to cause the ongoing work to be undone and compensated Adding Event Handlers You can add event handlers to the process as a whole or to a scope. You can add two types of event handlers: Adding an OnMessage Event Handler Adding an OnAlarm Event Handler For conceptual information, see What is Event Handling? XML Syntax <eventhandlers>? <!-- there must be at least one onmessage or onalarm handler --> <onmessage partnerlink="ncname" porttype="qname" operation="ncname" variable="ncname"?>* <correlations>? <correlation set="ncname" initiate="yes no">+ </correlations> activity </onmessage> <onalarm for="duration-expr"? until="deadline-expr"?>* activity </onalarm> </eventhandlers> Adding an OnMessage Event Handler The onmessage element indicates that the event specified is an event that waits for a message to arrive. This element is very similar to a receive activity, except that a message event cannot create a new process instance. 274 Adding Event Handlers Version 1.5

275 An incoming message can correspond to a request/response or one-way operation in a WSDL. When the operation is a request/response type, the event handler is expected to use a Reply to send back the response. You can add an event handler to the process as a whole or to a scope. To add an onmessage event handler for the process: Ensure that you have added a WSDL file to Web References containing the partner link type information needed. Also you must create a partner link and (optionally) a variable for the event handler before you can complete the properties for it. 1 Click on the Event Handlers tab of the Process Editor. 2 Ensure that nothing is selected on the canvas, and right mouse click to select Add On Message. An onmessage handler is added and is selected. 3 In the Properties view, select the partner link, port type, operation and optionally a variable for the onmessage handler. 4 From the Activity palette, drag an activity into the event handler to respond to the event, such as a reply or terminate. 5 Fill in the properties for the activity that handles the event. The following illustration shows an example of an onmessage event handler added for the process. To add an onmessage event handler for a scope: Version 1.5 Chapter 14: Event Handling 275

276 Ensure that you have added a WSDL file to Web References containing the partner link type information needed. Also you must create a partner link and (optionally) a variable for the event handler before you can complete the properties for it. 1 Display a BPEL file in the Process Editor, and select a scope. 2 Right-mouse click and select Show Event Handlers. An event handler container is added to the scope. 3 Right-mouse click in the Event Handler, and select Add On Message. 4 In the Properties view, select the partner link, port type, operation and optionally a variable for the onmessage handler. 5 From the Activity palette, drag an activity into the event handler to respond to the event, such as a reply or terminate. 6 Fill in the properties for the activity that handles the event. The following illustration shows an example of an onmessage and an onalarm event handler added for a scope. The activity responding to each event is a reply. 1 onmessage event handler 2 onalarm event handler 276 Adding Event Handlers Version 1.5

277 Adding an OnAlarm Event Handler The onalarm element defines a timeout event. The for attribute specifies the duration after which the event will be signaled. The clock for the duration starts at the point in time when the associated scope starts. The alternative until attribute sets the specific point in time when the alarm will be fired. Only one of these two attributes may occur in any onalarm event. An alarm time can be set for the process using the data provided within the message that creates a process instance, as shown in the following example. In the WSDL file, a complex message is defined with a part specifying processduration. <wsdl:definitions targetnamespace=" xmlns:xsd=" <wsdl:message name="orderdetails"> <part name="processduration" type="xsd:duration"/> </wsdl:message> </wsdl:definitions> The message type above is used in the onalarm value in the BPEL process: <process name="ordercar" xmlns:def=" <eventhandlers> <onalarm for= "bpws:getvariabledata(orderdetails,processduration)"> </onalarm> <reply>...</reply> <terminate>...</terminate> </eventhandlers>... <variable name= orderdetails messagetype= def:orderdetails /> </variable>... <receive name= getorder partnerlink= buyer porttype= car operation= order variable= orderdetails createinstance= yes />... </process> Version 1.5 Chapter 14: Event Handling 277

278 In the above example, the onalarm element specifies a timer event that is fired when the duration specified in the processduration field in the orderdetails variable is exceeded. The value of the field is provided via the getorder activity that receives a message containing the order details and causes the creation of a process instance for that order. The activities that handle the alarm are a reply and a terminate. To add an onalarm event handler for the process: 1 Click on the Event Handlers tab of the Process Editor. 2 Ensure that nothing is selected on the canvas, and right mouse click to select Add On Alarm. An onalarm handler is added and is selected. 3 In the Properties view, do the following: a In the Alarm Expression field, type in or compose an expression representing the duration or deadline for the alarm. See the example below in the illustration. b In the Alarm Type field, select Deadline or Duration. 4 From the Activity palette, drag an activity into the event handler to respond to the event, such as a reply or terminate. 5 Fill in the properties for the activity that handles the event. The following illustration shows an example of an onalarm event handler added for the process. 278 Adding Event Handlers Version 1.5

279 To add an onalarm event handler for a scope: 1 Display a BPEL file in the Process Editor, and select a scope. 2 Right-mouse click and select Show Event Handlers. An event handler container is added to the scope. 3 Right-mouse click in the Event Handler, and select Add On Alarm. 4 In the Properties view, do the following: a b In the Alarm Expression field, type in or compose an expression representing the duration or deadline for the alarm. In the Alarm Type field, select Deadline or Duration. 5 From the Activity palette, drag an activity into the event handler to respond to the event, such as a reply or terminate. 6 Fill in the properties for the activity that handles the event. The following illustration shows an example of an onalarm and an onmessage event handler added for a scope. The activity responding to each event is a reply. 1 onmessage event handler 2 onalarm event handler Version 1.5 Chapter 14: Event Handling 279

280 Processing Rules for Events An alarm event can occur only once. A message event can occur multiple times. For example, while an order is being processed inside a scope, changes for the order can be accepted via a message event. Multiple message and alarm events can occur concurrently. If your process contains two concurrent scopes with shared variables and event handlers, be sure to enable variableaccessserializable for the scopes. Enabling this ensures consistent access to shared variables. 280 Processing Rules for Events Version 1.5

281 15 Fault Handling What s in this chapter What is BPEL Fault Handling? Defining Catch and CatchAll Fault Handlers Fault Handling for Service Invocations Adding a Fault Handler Fault Handling Processing Rules Tips on Fault Handling What is BPEL Fault Handling? Fault handling in a BPEL process is reverse work, undoing the partial and unsuccessful work of a scope in which a fault has occurred. Fault handling differs from compensation handling in that fault handling takes over when a fault occurs within a scope whereas compensation reverses the work of a successfully completed scope. A fault can occur for the following reasons: A web service operation cannot complete successfully, and the service returns a fault An internal process error occurs, and a standard BPEL fault is thrown. Refer to the list of BPEL Standard Faults for more information. A <throw> activity throws a fault A platform-specific fault, such as a communication failure, occurs in a BPEL process instance Fault handling can be global or local: you can add fault handlers to the process as a whole or to a scope within the process. Version 1.5 Chapter 15: Fault Handling 281

282 When a fault occurs, normal processing is terminated, and control is transferred to the corresponding fault handler, as defined in the <faulthandlers> section of the process or scope. Note that the process does not enable compensation for a scope in which a fault handler is invoked. Fault handlers do not rely on state to determine which nested scopes have completed successfully. For a discussion of fault handling and compensation handling for a scope, see Lifecycle of a Scope. Defining Catch and CatchAll Fault Handlers For information on how to add fault handlers to the Process Editor canvas, see Adding a Fault Handler. You can define two types of fault handlers: A <catch> fault handler, which defines a set of custom fault-handling activities which execute based on the fault name and or fault variable A <catchall> fault handler, which executes if a thrown fault is not caught by a <catch> fault handler You can define <catch> and <catchall> handlers for the process on the Process Editor Fault Handlers tab. The following illustration shows an example of fault handlers created on the Process Editor canvas. Note that the partner link Swimlane is shown to indicate the facing invoke activity for the reply. 282 Defining Catch and CatchAll Fault Handlers Version 1.5

283 You can also define fault handlers for a scope, as shown in the following example. You can define each catch activity to intercept a specific kind of fault, defined by a globally unique fault qname and a variable associated with the fault. XML Syntax <faulthandlers>? <catch faultname= qname? faultvariable= ncname?>* activity </catch> <catchall>? activity </catchall> </faulthandlers> Version 1.5 Chapter 15: Fault Handling 283

284 Catch Fault Name and Fault Variable Both the fault name and the fault variable are optional attributes, but you must provide at least one of them for a <catch>. These attributes are used to determine which catch in a fault handler will execute when a fault is thrown. In most cases, the values for these attributes are from the WSDL for a service being invoked. The name of the fault is typically the name of fault on an operation with the target namespace as the qualifying namespace value. The variable for a fault is typically the message sent when an operation in WSDL throws a fault. In the case where a catch includes a fault variable, that variable must be defined within the fault handler s scope or an enclosing scope. This variable gets populated with the data from the fault when the catch executes. For more details about the use of fault names and variables, see Fault Handling Processing Rules and Tips on Fault Handling. CatchAll Handler Examples The <catchall> catches any faults that were not caught by an existing catch block. The benefit of this construct is that you can be sure that your fault handler has an opportunity to execute your fault handling code in the event a fault is thrown. One drawback is that you will not have any details regarding the type of fault that was thrown since there is no fault name or fault variable available to a <catchall>. This construct is best used in cases where you do not care what fault is thrown or in cases where you want to be sure that no faults get past your existing fault handler logic. Fault Handling for Service Invocations A fault response to an invoke activity uses the definition of the fault in the WSDL operation. A WSDL fault is defined by using the target namespace of the port type and the fault name. Example: Purchase Order BPEL Process In a normal purchase order BPEL process, the following steps occur: A customer sends in a purchase order. The BPEL process receives a purchase order and performs tasks for calculating shipping and production costs. The BPEL process returns an invoice to the customer. 284 Fault Handling for Service Invocations Version 1.5

285 If something goes wrong, the process returns an error. Fault messages are defined in the WSDL file and used in the BPEL process as described in the following example: Table 33: WSDL Fault Definition <porttype name= POrderPT > <operation name= sendporder > <input message=... /> <output message=... /> <fault name= cannotcompletepo message= pos:orderfaulttype /> </operation> </porttype> BPEL Fault Handling for Service Invocation <faulthandlers> <catch faultname= lns:cannotcompletepo faultvariable= POFault > <reply partnerlink= purchasing porttype= lns:porderpt operation= sendporder variable= POFault faultname= lns:cannotcompletepo /> </catch> </faulthandlers> In the WSDL definition above, the operation called sendporder specifies the fault named cannotcompletepo that is used by the BPEL process if the purchase order cannot be completed. In the BPEL process fault handlers section, the catch activity contains a reply defined to return a message in the POFault variable in the event that a fault is received. When an invoke operation returns a fault message, it causes a fault in the current scope. The fault variable in the corresponding <catch> is initialized with the fault message received. For more information, see Adding an Inline Fault Handler for an Invoke Activity. Adding a Fault Handler Your BPEL process can catch standard faults as well as faults from a throw activity or service invocation. Once caught, a fault is handled by a catch activity you specify, such as a reply containing an error message or a compensate activity. While a <catch> or <catchall> can have ony a single child activity, this activity could be a structured activity which could have its own children. This allows for some rather sophisticated fault handling. There are several ways to add fault handlers, including: Adding a Fault Handler for the Process Version 1.5 Chapter 15: Fault Handling 285

286 Adding a Fault Handler for a Scope Adding an Inline Fault Handler for an Invoke Activity For background information, see Fault Handling. Adding a Fault Handler for the Process You can add multiple catch handlers and one catch all handler for the process. For explanations of these handlers, see Defining Catch and CatchAll Fault Handlers. To add a catch handler for the process: 1 Click on the Fault Handlers tab of the Process Editor canvas. 2 From the Other palette, drag a Catch to the canvas. A catch handler is added and is selected. 3 In the Properties view, select the following optional values: a b c Comment Fault Name. Select a fault name from the list. For a discussion on whether or not to add a fault name, see Fault Handling Processing Rules. Fault Variable. Select a fault variable from the list. For a discussion on whether or not to add a fault variable, see Fault Handling Processing Rules. 4 From the Activity palette, drag an activity into the catch handler, such as a reply or compensate. For an example, see Fault Handling for Service Invocations. 5 Fill in the properties for the activity to handle the fault. Tip: For service invocation fault handling, you can right-mouse click on the Process Editor canvas and select Show All Swimlanes to display the relationship between the fault handler activity and the service. To add the catch all handler for the process: 1 Click on the Fault Handlers tab of the Process Editor canvas. 2 Ensure that nothing is selected on the canvas, and right mouse click to select Add Catch All. A catchall handler is added and is selected. 3 In the Properties view, type in a comment, if desired. 286 Adding a Fault Handler Version 1.5

287 4 From the Activity palette, drag an activity into the catch all handler, such as an assign or compensate. 5 Fill in the properties for the activity to handle the fault. The following illustration shown an example of fault handlers added for the process. Adding a Fault Handler for a Scope You can add multiple catch handlers and one catch all handler for each scope in your process. For explanations of these handlers, see Defining Catch and CatchAll Fault Handlers. To add a catch handler to a scope: 1 Select a scope container on the Process tab of the Process Editor canvas. 2 Right-mouse click and select Show Fault Handlers. 3 Select the fault handler, and right-mouse click to select Add Catch. 4 In the Properties view, select the following optional values: a b c Comment. Click the Dialog Button to add a comment. Fault Name. Select a fault name from the list. For a discussion on whether or not to add a fault name, see Fault Handling Processing Rules. Fault Variable. Select a fault variable from the list. For a discussion on whether or not to add a fault variable, see Fault Handling Processing Rules. Version 1.5 Chapter 15: Fault Handling 287

288 5 From the Activity palette, drag an activity into the catch handler, such as a reply. 6 Fill in the properties for the activity to handle the fault. To add the catch all handler for a scope: 1 Select a scope on the Process tab of the Process Editor canvas. 2 If needed, right-mouse click, and select Show Fault Handlers. 3 Select the fault handler, and right-mouse click to select Add Catch All. A catch all handler is added and is selected. 4 In the Properties view, type in a comment, if desired. 5 From the Activity palette, drag an activity into the catch all handler, such as an assign or compensate. 6 Fill in the properties for the activity to handle the fault. The following illustration shows an example of fault handlers added for a scope. Adding an Inline Fault Handler for an Invoke Activity When an invoke activity contains both an input and an output message, you can add a fault handler to catch any output message errors. To add a fault handler to an invoke activity: 288 Adding a Fault Handler Version 1.5

289 1 Display the Process tab of the Process Editor canvas. 2 From the Activity palette, drag a scope container to the drawing canvas. 3 Drag the invoke activity into the scope. 4 Follow the steps in Adding a Fault Handler for a Scope. Fault Handling Processing Rules When a fault occurs in a process, the flow of execution moves from the activity that generated the fault (e.g., the invoke that faulted during execution or a throw activity) to the immediately enclosing scope s fault handler. If there is no immediately enclosing scope, then the execution moves to the process s fault handler. Once at the fault handler, a single <catch> or <catchall> is matched in order to execute. The rules for matching a fault are as follows. If the fault contains data then a <catch> that matches the fault name and fault variable message type is considered first. If one is not found then a <catch> that contains only a fault variable is matched. If the fault has no data, then it matches against a <catch> with the same name but without a fault variable attribute If fault cannot be matched to a <catch> using the rules above, then it executes the <catchall> If there is no <catchall> within the fault handlers, then the implicit fault handling logic executes. This logic acts like there is a <catchall> present that contains a single compensate activity which executes the default compensation routine for all enclosed scopes. Once executed, the original fault is rethrown to the next enclosing scope or the process if none is available. If the handler is already at the process level, then the process terminates with the fault. It is worth noting that prior to the execution of the matched <catch> or <catchall>, all of the activities within the scope are terminated. Once a scope catches a fault, it is considered to have not completed normally and as such is not eligible for compensation for that execution. If the scope catches the fault without rethrowing the fault, then normal process execution can resume from the point of the scope on. If this happens at the process level, then the process completes normally but would not be eligible for process instance compensation. Version 1.5 Chapter 15: Fault Handling 289

290 In the following example, notice that the fault name and fault variable are not unique across catch activities. Example <faulthandlers> <!-- catch the fault specified by the name and variable type --> <catch faultname= x:foo faultvariable= bar > <empty/> </catch> <!-- catch all faults with a matching name, but no data --> <catch faultname= x:foo > <empty/> </catch> <!-- catch all faults with the matching variable type, regardless of the name--> <catch faultvariable= bar > <empty/> </catch> <!-- catch all faults not caught by a specific handler --> <catchall> <empty/> </catchall> </faulthandlers> Tip: The catch and catch all activities in the faulthandlers section are not in sequence. You can arrange them in any order. Links and Fault Handling A link that crosses a fault handler boundary must be outbound, that is, it must have its source activity within the fault handler and its target within a scope that encloses the scope associated with the fault handler. 290 Fault Handling Processing Rules Version 1.5

291 Tips on Fault Handling Note the following tips: WSDL faults always have fault data. If you attempt to catch a fault thrown by an operation then you must specify a fault variable or the fault does not match against a <catch>. It still matches against a <catchall> or the implicit fault handler. The name of the fault and its associated data are unavailable to a <catchall>. If you need access to this information then you should be sure to provide a specific <catch> with the fault name and fault variable. You can throw a fault from your <catch> or <catchall>. In the case where you have access to the fault name and variable, you can rethrow the same fault that you caught by using the <throw> activity. You are not limited to working with faults defined in a service s WSDL. You can define a <throw> activity to use a fault name and variable of your own creation. The standard runtime BPEL faults can occur due to errors in the design of the process (e.g., having two receives executing concurrently on the same partner ink, port type, and operation results in a bpws:conflictingreceive) as well as standard runtime errors. In general, it is not good design practice to catch these faults since they mostly represent errors which should be caught during simulation or testing of the process. There are some exceptions to this. For example, bpws:joinfailure is useful for identifying a situation where an activity does not execute due to its inbound links resulting to false. Version 1.5 Chapter 15: Fault Handling 291

292 292 Tips on Fault Handling Version 1.5

293 16 Simulating and Debugging What s in this chapter What is the ActiveWebflow Debug Perspective? ActiveWebflow Debug Perspective Views and Menus Simulating Execution of a BPEL Process Using and Inspecting Sample Variable Data During Simulation Selecting Simulation Paths and Properties Inspecting Standard Faults During Simulation Simulation Preferences Setting Debug Preferences Debugging Remote Processes Running on the Server What is the ActiveWebflow Debug Perspective? The ActiveWebflow Debug perspective contains the views, editors, menus, and toolbars that support the execution of a BPEL process that you create or import into ActiveWebflow Designer. Processes can be simulated within ActiveWebflow, using sample data, or remotely debugged from the ActiveBPEL server. During simulation, you can debug your process by using breakpoints or stepping. In simulate/run mode, the process executes but the execution cannot be suspended or examined. In simulate/step mode, execution can be suspended and resumed and variables can be inspected and modified. In remote debugging mode, the process is suspended when it is first instantiated and remains suspended until you run or step through it. For concepts and tips on using perspectives, see Windows, Perspectives, Views, and Editors. Version 1.5 Chapter 16: Simulating and Debugging 293

294 For Debug perspective details, see: Opening the ActiveWebflow Debug Perspective Switching Between ActiveWebflow Perspectives Opening the ActiveWebflow Debug Perspective ActiveWebflow automatically switches to the Debug perspective when you begin simulation or remote debugging. However, you can manually display the perspective in one of the following ways: From the Perspective bar on the top right of the Navigator, select the ActiveWebflow Debug Perspective icon From the Window menu, select Open Perspective>ActiveWebflow Debug Tip: You can open a perspective in the same window or in a new window. Open a perspective in a new window from the Window>New Window menu. There is also a Workbench preference for always opening a new perspective in a new window. Switching Between ActiveWebflow Perspectives There are two ActiveWebflow perspectives: Design and Debug. Each perspective has a set of views and menus supporting a set of related tasks. Use one of the following ways to switch between perspectives: Click the icons on the Perspective bar Select Window>Open Perspective and select a Perspective If both perspectives are open, use the keyboard shortcuts for Next Perspective (Ctrl +F8) and Previous Perspective (Ctrl +Shift + F8) Tips for displaying perspectives: The window titlebar displays the name of the currently active perspective, helping you manage open perspectives If you have closed or rearranged views, you can reset the perspective to its default display by selecting Window>Reset Perspective Select color and font preferences for the Debug perspective. See Setting Debug Preferences. 294 What is the ActiveWebflow Debug Perspective? Version 1.5

295 ActiveWebflow Debug Perspective Views and Menus The following illustration shows the views and menus that make up the Debug perspective: 1 Simulate Process and Clear Execution State toolbar icons. See Starting and Ending Simulation of a BPEL Process and Clearing the Process Execution State 2 Debug view. See Using the ActiveWebflow Debug View 3 Breakpoints view. See Using Breakpoints in BPEL Process Simulation 4 Console. See Using the ActiveWebflow Debug Console Using the ActiveWebflow Debug View The ActiveWebflow Debug perspective contains a Debug view that lets you manage the running or stepping through of a BPEL process that you have created or imported into ActiveWebflow Designer. It displays an execution tree associated with the process you are debugging. Note: The ActiveWebflow Debug view is based on the Eclipse Debug view, and not all functions apply to ActiveWebflow. You will notice that some icons, options, and preferences are unavailable in ActiveWebflow. Version 1.5 Chapter 16: Simulating and Debugging 295

296 The following illustration shows a sample Debug view. 1 Resume Resumes a suspended thread. Allow the process to run until the next breakpoint is encountered or until the process is completed. (F8 key) 2 Terminate Terminates the selected debug target 3 Step Over The process executes until the next activity in the process is reached. If a breakpoint is encountered, the execution suspends at the breakpoint (F6 key). In addition to the toolbar options, there are more options on the right mouse menu of a simulation thread item. The following illustration shows only the additional options, not all the options available on the right mouse menu. 296 ActiveWebflow Debug Perspective Views and Menus Version 1.5

297 Copy Stack Terminate and Remove Relaunch Terminate All Copies the selected stack of suspended threads as well as the state of the running threads to the clipboard Terminates the selected debug target and removes it from the view Start a new simulation Terminates all active simulations in the view Using Breakpoints in BPEL Process Simulation The Breakpoints view is part of the ActiveWebflow Debug perspective. You can set a breakpoint on an activity and then run to the breakpoint when simulating or remotely debugging the process s execution. The Breakpoints view lists all the breakpoints you have set in BPEL processes. You can double-click a breakpoint to display its location in the Process Editor. In the Breakpoints view, you can also enable, disable, skip, or remove breakpoints. The following illustration shows a sample Breakpoints view and process. The breakpoints were added next to an activity, and the list of breakpoints appears in the Breakpoints view. Version 1.5 Chapter 16: Simulating and Debugging 297

298 1 Removes selected breakpoints 2 Removes all breakpoints for all targets 3 Shows breakpoints supported by selected target 4 Goes to file for breakpoint 5 Ties the view to always show the current file being debugged 6 Skips all breakpoints Adding a breakpoint: 1 From the Navigator, open a BPEL file. 2 Right-mouse click on an activity where you want to set a breakpoint and select Add Breakpoint. A red circle appears next to the activity to indicate the breakpoint, as shown. 298 ActiveWebflow Debug Perspective Views and Menus Version 1.5

299 Tips for working in the Breakpoints view Select Remove All Breakpoints from the toolbar to delete all breakpoints displayed Double-click a breakpoint to highlight its location in the Process Editor Right-click a breakpoint and select Go to File to go to the activity in the Process Editor where the breakpoint is set. If the file is not already open, this option opens the file and finds the breakpoint. Each breakpoint shows the name of the BPEL file and activity where the breakpoint is set. All breakpoints are listed for all files you are debugging. You can Enable and Disable breakpoint(s) by selecting/deselecting the check mark in the box next to the breakpoint. A disabled breakpoint appears as a grey circle next to an activity icon. See also Running to a Breakpoint in a BPEL Process. Using the ActiveWebflow Debug Console The Console view is part of the ActiveWebflow Debug perspective. This view shows execution events and provides a view into the evaluation of expressions and results. The following illustration shows a sample of the Console. Version 1.5 Chapter 16: Simulating and Debugging 299

300 1 Terminate. Stops the current simulation 2 Removes all terminated launches 3 Scroll Lock. Automatically wraps long lines to avoid horizontal scrolling. 4 Clears console 5 Pin Console. Not applicable. As your process executes, the following types of events are displayed: Activity type, name, and path Link name, link transition condition, and path On Alarm Wait Join Condition While Condition Case Condition Unhandled events Tips for using the Console: Executing, completed normally, or completed with a fault Example: Receive:Executing </process/flow/receive> Status and evaluation of expression Example: Link receive-to-assess Condition true : bpws:getvariabledata('request','amount') < </process/flow/links/ link[@name='receive-to-assess']> Duration or deadline Wait value and simulated Wait value Evaluation of expression Evaluation of expression Evaluation of expression Ancillary event information Use the right-mouse menu to go to an activity that has already executed Use the right-mouse menu to find a simulation event in the Console 300 ActiveWebflow Debug Perspective Views and Menus Version 1.5

301 Simulating Execution of a BPEL Process Ensure you are ready to simulate execution of your process. See Prerequisites for Simulation. You can start simulation from either the Designer or the Debug perspective. Select a topic for more information: Starting and Ending Simulation of a BPEL Process Running to a Breakpoint in a BPEL Process Stepping to the Next Activity in a BPEL Simulation Viewing the Execution State of an Activity or Link Modifying a BPEL Process During Simulation Terminating and Removing BPEL Process Simulations Clearing the Process Execution State Prerequisites for Simulation Before starting simulation, do the following: Ensure that you have filled in all the required properties for each activity, such as partner link, port type, operation and variable for receives, picks, invokes, and replies Ensure that the Abstract Process property is set to No for the process. The default is No. Make sample data available for all variables. For more information, see Using and Inspecting Sample Variable Data During Simulation. If your process contains a Pick activity, you can select a branch to execute. For more information, see Selecting Simulation Paths and Properties. Starting and Ending Simulation of a BPEL Process To simulate your process: Version 1.5 Chapter 16: Simulating and Debugging 301

302 1 Open your BPEL file. 2 Click your mouse in the Process Editor canvas to activate the editor toolbar. 3 Select the Simulate Process icon on the toolbar, as shown. The simulation target stops at the first activity in the process and suspends execution. 4 In the Debug view, do one of the following: Click the Resume icon to run to completion or to a breakpoint Click the Step Over icon to step to the next activity or breakpoint As the process executes, the following events occur: Each activity is highlighted as it prepares to execute In Process Variables view, sample data is cleared at the beginning of simulation and then is displayed as the corresponding activities execute The Console view shows simulation events If an error occurs, an error message pops up, the simulation terminates, and the activity is marked with an X, as shown in the following illustration. For more information, see Inspecting Standard Faults During Simulation. 302 Simulating Execution of a BPEL Process Version 1.5

303 You can end a simulation thread by stepping to the end or by terminating it. You can select Terminate from the context menu of the process s thread in the Debug view to terminate the simulation. When a simulation terminates, the process diagram shows the simulation path. The following illustration shows both the path taken (highlighted) and not taken (grayed out). Running to a Breakpoint in a BPEL Process When you are debugging a BPEL process, the simulation suspends before the first activity is executed. Version 1.5 Chapter 16: Simulating and Debugging 303

304 You can resume execution and run to a breakpoint that you have set next to an activity in a process. See Using Breakpoints in BPEL Process Simulation for information on setting breakpoints. To run to a breakpoint: 1 Select a process in the Debug view. 2 Click the Resume button in the Debug view toolbar (or press the F8 key). The process resumes its execution. Stepping to the Next Activity in a BPEL Simulation You can step through the execution of a BPEL process one activity at a time. While you are stepping through the simulation, you can see execution results in the Console. Click the Step Over button in the Debug view toolbar, or press the F6 key. The currently-selected activity is executed and suspends on the next executable activity. The following illustration shows one step at a time of an execution path. Note: If a breakpoint is encountered during a step operation, the execution suspends at the breakpoint, and the step operation ends. 304 Simulating Execution of a BPEL Process Version 1.5

305 Viewing the Execution State of an Activity or Link During simulation and remote debugging, BPEL activities and links can have one of the following states: Inactive Active (links only) Ready to execute Executing Dead Path (will not run because of links or conditional execution) Execution Completed (activity only) Execution Faulted (activity only) You can view the execution state in the Properties view for the activity or link. Modifying a BPEL Process During Simulation It is possible for you to make changes to the BPEL process during simulation. For example, you can change sample data values and expressions. The simulator determines whether or not the change causes the process model to be out-of-sync with the process currently being executed. Terminating and Removing BPEL Process Simulations Use one of the following options to stop a simulation and to remove a simulation from the Debug view. Table 34: Option Location Description Terminate Terminate All Debug view toolbar and Run menu Right mouse menu of simulation thread Console toolbar Right mouse menu of simulation thread Terminates the simulation of the associated process Terminates all active simulations Version 1.5 Chapter 16: Simulating and Debugging 305

306 Table 34: Option Location Description Terminate and Remove Remove All Terminated Right mouse menu of simulation thread Debug view toolbar Right mouse menu of simulation thread Terminates the simulation of the associated process and removes it from the view Clears all terminated simulations from the view Clearing the Process Execution State When you terminate a BPEL process simulation, the highlighting that had been added to activities and links remains in view in the Process Editor and the simulation state of each activity and link is displayed in Properties view. To remove highlighting and simulation states, click the Clear Execution State icon, as shown. 306 Simulating Execution of a BPEL Process Version 1.5

307 Using and Inspecting Sample Variable Data During Simulation ActiveWebflow offers several ways for you to use sample data values for process variables. When you simulate process execution, you can use different data values to test different execution paths in your process. Add, load, and change sample data as follows: Add sample data files for message data When you add WSDL files to Web References, you can view a list of the defined messages and then add one or more sample data files per message. One data file per message defines default values for the message parts. The data file can be used universally across all BPEL projects. For a discussion of adding sample data, see Using Sample Data for WSDL Messages. Select default values for message data If you add multiple data files to Web References messages, you can specify one file as the default. See Selecting a Default Sample Data File. Change default values for process variables used in Receive, Invoke, and OnMessage activities Load sample data values to initialize process variables As you simulate execution of a process, you can override the default data values for input, output, and fault messages. For more information, see Setting up Sample Data Values for Input, Output, and Fault Messages. For a specific BPEL process, you can type in data values or load a data file for each process variable. The file you load is one that you added to Web Reference messages. For more information, see Using Sample Data. During process simulation, you can view variable assignments. For more information, see Inspecting Process Variables during Simulation. Setting up Sample Data Values for Input, Output, and Fault Messages You can simulate execution with different data values that might be received by the process from Receive, Invoke and OnMessage activities. You can load sample values from either the Process Variables view or the Properties view of an activity. For information on loading and saving sample data in the Process Variables view, see Using Sample Data. During simulation, you can override data values on-the-fly for any activity that has not yet executed. Version 1.5 Chapter 16: Simulating and Debugging 307

308 To override loaded sample data for an input and output messages: 1 From the Process Editor canvas, select a Receive, Invoke, or OnMessage activity. 2 In the Properties view, do one of the following: For a Receive or OnMessage, click the Dialog Button at the end of the Input Message row For an Invoke, click the Dialog Button at the end of the Output Message row 3 In the Set Simulation Data dialog, do the following: Select the checkbox next to Override sample data for simulation Select the Dialog Button at the end of a row, as shown. 4 For simple data types, edit the data value in the Sample dialog and click OK. For complex message types, load a data file from Web References or the file system. 5 Edit any additional values for other message parts and click OK. To override loaded sample data for an Invoke fault message: 308 Using and Inspecting Sample Variable Data During Simulation Version 1.5

309 1 From the Process Editor canvas, select an Invoke activity that has an output and a fault message defined. 2 In the Properties view, set the Result property to Fault. 3 Select a Fault Name from the drop-down list. 4 Select a Fault Message, and click the Dialog Button at the end of the row. 5 In the Set Sample Data dialog, type in a value for the fault message. Inspecting Process Variables during Simulation During simulation, as each activity executes, you can inspect variable values in the Process Variables view. The values are those you loaded into Process Variables or into the simulation properties for Receives, Invokes, and onmessage branches of Picks or Event Handlers. For information on loading and changing data values, see Using and Inspecting Sample Variable Data During Simulation. Here is a recommended way to inspect variable values, by opening and closing variables as you need to. 1 Display the Process Variables view. Tip: Display the list of variables with all variables closed. To close all variables, select a variable from the list, and select Close All from the right-mouse menu. 2 Start simulation. For details, see Simulating Execution of a BPEL Process. 3 Step to the first Receive or onmessage branch of a Pick activity. For more information, see Stepping to the Next Activity in a BPEL Simulation. 4 Notice that the variable in use is highlighted in the Process Variables list. The following example shows the buyerinfo variable highlighted. 5 Double-click the highlighted variable to open it. Version 1.5 Chapter 16: Simulating and Debugging 309

310 6 Right-mouse click the variable and select View Data. 7 Step to the next activity to execute the current activity. The following example shows the normal result of variable processing. 8 Continue stepping through the simulation, inspecting variables as needed. Selecting Simulation Paths and Properties Every activity and link in a BPEL process has a simulation property called State, as described in Viewing the Execution State of an Activity or Link. In addition, some activities have additional properties that you can modify to cause different simulation events to occur. For example, you can change a data value in a Receive message variable to cause a link transition to be true or false. You can also change sample data values for output and fault messages. The following table lists simulation properties for each activity that you can modify. Table 35: Activity Simulation Property Description Receive Input Message Set the instance data for the simulated message to receive 310 Selecting Simulation Paths and Properties Version 1.5

311 Table 35: Activity Simulation Property Description Pick Execute Select the OnMessage or OnAlarm branch to execute for simulation. You must select an option before you simulate a Pick. onmessage branch of Pick or Event Handler Input Message Set the instance data for the simulated message to receive Invoke Output Message Set the instance data for the simulated message to return Result Fault Name Fault Message Set the result of the output message to Normal or Fault When the Result is set to Fault, you can select a Fault Name from the list. Fault names are defined in the associated WSDL file. Set the instance data for the simulated Fault message Wait Wait in Seconds Actual wait time in seconds for simulation. The activity wait time may be longer than you want to wait during simulation. This is a way to shorten that time. Simulating Event Handlers During simulation, there are different debug targets for the main process and for event handlers. You can step into an event handler at any point in the simulation of its scope, and then select the main target to continue simulating the scope in the main process. The following illustration shows the running and suspended simulation targets. Version 1.5 Chapter 16: Simulating and Debugging 311

312 Simulating Fault Handlers During simulation, you can execute a fault handler by setting a simulation property for the relevant invoke activity. In the Properties view, set the Result property to Fault and then select the appropriate fault name and variable. For more information, see Setting up Sample Data Values for Input, Output, and Fault Messages. Inspecting Standard Faults During Simulation The BPEL4WS specification defines several standard faults. If one of these faults is encountered during simulation, the simulation terminates and shows a red X next to the activity where the fault occurred. Also, you see a listing for the fault in the Console. An example is: Assign AssignYestoAccept: Completed with fault: mismatchedassignmentfailure : </process/flow/ assign[@name='assignyestoaccept']> For a list and description of faults, see BPEL Standard Faults. 312 Inspecting Standard Faults During Simulation Version 1.5

313 Simulation Preferences When you simulate execution of a process in ActiveWebflow, the simulation engine behaves identically to the server engine, where your deployed processes run. You can set preferences to modify the server engine behavior, and you can set the same preferences for the simulation engine. Note: To learn more about setting server engine behavior, refer to the ActiveWebflow Server documentation. Select Window>Preferences>ActiveWebflow>Simulation to view simulation preferences, described in the following table. Simulation Preference Description Validate input/output messages against Validates the sample data loaded into process variables schema against the WSDL schema. If you add a sample data file to a complex message, and the data file is not valid, ActiveWebflow warns you and allows you to add it with errors. Enable this option to validate data before simulation starts. Disable this option for faster simulation. This option is enabled by default. Disable bpws:selectionfailure fault Enabling this option allows a null value to be returned from a function or assignment that contains an XPath query string. You can enable this to override XPath behavior, for cases that handle data samples with optional elements. By default, this option is not enabled, and if the query string returns an empty selection from an assign copy FROM, the process throws a bpws:selectionfailure fault, which is the standard response described in the BPEL4WS spec. See Disable bpws:selectionfailure Fault Example and Disable bpws:selectionfailure Fault and Auto Create Target Path for Copy/To Example for more information. Version 1.5 Chapter 16: Simulating and Debugging 313

314 Simulation Preference Auto create target path for Copy/To Description Determines if ActiveWebflow is allowed to create a location path for a non-existent node in a complex variable in a process instance document. When an assignment refers to a non-existent node (or to more than one node), the standard BPEL fault, bpws:selectionfailure, must be thrown, according to the BPEL specification. Enabling this option allows selections to be created onthe-fly. This means an assign copy TO operation can refer to a non-existent node and assign a value to it. This option is disabled by default. See Auto Create Target Path for Copy/To Example and Disable bpws:selectionfailure Fault and Auto Create Target Path for Copy/To Example for more information. Disable bpws:selectionfailure Fault Example The following example shows the effect of enabling and disabling the Disable bpws:selectionfailure Fault preference. For a description of this preference, see Simulation Preferences. Code sample: <assign> <copy> <from part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable= var1 /> <to part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable=var2 /> </copy> </assign> In the code sample, the Assign From/To query is for an optional element, as shown in the schema snippet below. Schema Snippet for Var1 and Var2: <xs:complextype name="addressinfotype"> <xs:sequence> <xs:element ref="ord:name"/> <xs:element ref="ord:addr1" minoccurs="0"/> 314 Simulation Preferences Version 1.5

315 <xs:element ref="ord:addr2" /> <xs:element ref="ord:city"/> <xs:element ref="ord:st"/> <xs:element ref="ord:zip"/> <xs:element ref="ord:cntry" /> </xs:sequence> </xs:complextype> <xs:element name="billtoinfo" type="ord:addressinfotype"/> Var1 Sample Data Var2 Initialization <ns1:orderinfo <ns1:orderinfo xmlns:ns1=" xmlns:ns1=" <ns1:orderheader> <ns1:orderheader> <ns1:ordid>78</ns1:ordid> <ns1:ordid/> <ns1:billtoinfo> <ns1:billtoinfo> <ns1:name>name1</ns1:name> <ns1:name/> (Addr1 is missing) <ns1:addr1/> <ns1:addr2>1 Main St <ns1:addr2/ </ns1:addr2> <ns1:city/> <ns1:city>albany</ns1:city> <ns1:st/> <ns1:st>ny</ns1:st> <ns1:zip/> <ns1:zip>12012</ns1:zip> <ns1:cntry/> <ns1:cntry>usa</ns1:cntry> </ns1:billtoinfo> </ns1:billtoinfo> With Disable bpws:selectionfailure Fault disabled, the simulation ends in a Selection Failure fault because Var1 is missing the query selection node, and it cannot be assigned to the Var2 query selection node. With Disable bpws:selectionfailure Fault enabled, the process terminates normally because the empty selection node is allowed. A null value is added to Addr1 during the assignment. Auto Create Target Path for Copy/To Example The following example shows the effect of enabling and disabling the Auto Create Target Path for Copy/To preference. For a description of this preference, see Simulation Preferences. Code sample: <assign> <copy> Version 1.5 Chapter 16: Simulating and Debugging 315

316 <from part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable= var1 /> <to part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable=var2 /> </copy> </assign> In the code sample, the Assign From/To query is for an optional element, as shown in the schema snippet below. Schema Snippet for Var1 and Var2: <xs:complextype name="addressinfotype"> <xs:sequence> <xs:element ref="ord:name"/> <xs:element ref="ord:addr1" minoccurs="0"/> <xs:element ref="ord:addr2" /> <xs:element ref="ord:city"/> <xs:element ref="ord:st"/> <xs:element ref="ord:zip"/> <xs:element ref="ord:cntry" /> </xs:sequence> </xs:complextype> <xs:element name="billtoinfo" type="ord:addressinfotype"/> Var1 Sample Data Var2 Initialization <ns1:orderinfo <ns1:orderinfo xmlns:ns1=" xmlns:ns1=" <ns1:orderheader> <ns1:orderheader> <ns1:ordid>78</ns1:ordid> <ns1:ordid/> <ns1:billtoinfo> <ns1:billtoinfo> <ns1:name>name1</ns1:name> <ns1:name/> <ns1:addr1>apt 12 (Addr1 is missing) </ns1:addr1> <ns1:addr2/> <ns1:addr2>1 Main St <ns1:city/> </ns1:addr2> <ns1:st/> <ns1:city>albany</ns1:city> <ns1:zip/> <ns1:st>ny</ns1:st> <ns1:cntry/> <ns1:zip>12012</ns1:zip> </ns1:billtoinfo> <ns1:cntry>usa</ns1:cntry>... </ns1:billtoinfo> Simulation Preferences Version 1.5

317 With Auto Create Target Path for Copy/To disabled, the simulation ends in a selectionfailure fault because Var1 contains the query selection node, but it cannot be assigned to the Var2 query selection node because the location path is missing. With Auto Create Target Path for Copy/To enabled, the process terminates normally because the location path for Addr1 is built, and the value is added to Addr1 during the assignment. Disable bpws:selectionfailure Fault and Auto Create Target Path for Copy/To Example The following example shows the effect of enabling both Disable bpws:selection- Failure Fault and Auto Create Target Path for Copy/To preferences. For a description of these preference, see Simulation Preferences. Code sample: <assign> <copy> <from part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable= var1 /> <to part= OrderInfo query="/ns1:orderinfo /ns1:orderheader/ns1:billtoinfo/ns1:addr1" variable=var2 /> </copy> </assign> In the code sample, the Assign From/To query is for an optional element, as shown in the schema snippet below. Version 1.5 Chapter 16: Simulating and Debugging 317

318 Var1 Sample Data Var1 and Var2 Schema Snippet <ns1:orderinfo <xs:complextype xmlns:ns1=" name="addressinfotype"> <ns1:orderheader> <xs:sequence> <ns1:ordid>78</ns1:ordid> <xs:element ref="ord:name"/> <ns1:billtoinfo> <xs:element ref="ord:addr1" <ns1:name>name1</ns1:name> minoccurs="0"/> (Addr1 is missing) <xs:element ref="ord:addr2" <ns1:addr2>1 Main St /> </ns1:addr2> <xs:element ref="ord:city"/> <ns1:city>albany</ns1:city> <xs:element ref="ord:st"/> <ns1:st>ny</ns1:st> <xs:element ref="ord:zip"/> <ns1:zip>12012</ns1:zip> <xs:element ref="ord:cntry" <ns1:cntry>usa</ns1:cntry> /> </ns1:billtoinfo> </xs:sequence>... </xs:complextype> <xs:element name="billtoinfo" type="ord:addressinfotype"/> With Disable bpws:selectionfailure Fault and Auto Create Target Path for Copy/ To enabled, the process terminates normally because the empty selection node is allowed, and the location path to the empty selection is built. A null value is added to Addr1 during the assignment. Setting Debug Preferences You will find several pages of preference settings for the Debug perspective when you select Window>Preferences from the main toolbar. Most of the settings are default Eclipse settings and are not applicable for ActiveWebflow. The following settings are applicable for ActiveWebflow. Table 36: Run/Debug Preference Page Console External Tools Launching Applicable Setting All settings on this page apply to the ActiveWebflow Console not applicable Remove terminated launches when a new launch is created 318 Setting Debug Preferences Version 1.5

319 Table 36: Run/Debug Preference Page String substitution View Management Applicable Setting not applicable not applicable Debugging Remote Processes Running on the Server As described in Deploying Your Processes, you can run your BPEL processes on an ActiveWebflow server. You can connect to a running or completed process from within ActiveWebflow Designer for remote debugging. When the process instance is opened in Designer, you have full access to the debug features you use during simulation, such as setting a breakpoint, stepping or running to a breakpoint, following highlights along the execution path, and inspecting process variables. Before you can debug a process remotely, you must complete the following: Create and validate a BPEL process Create a process deployment descriptor file Create a business process archive Deploy the business process archive to the ActiveWebflow server Keep a copy of the BPEL and WSDL files in your workspace project Start the server Instantiate the process by sending an appropriate message to it Select the following topics for remote debugging details. Configuring a Remote Process Connection Selecting Processes for Remote Debugging Setting Breakpoints on a Process for Remote Debugging Using the Debug View, Process Editor, and Variable View for Remote Debugging Version 1.5 Chapter 16: Simulating and Debugging 319

320 Remote Debugging Preferences Selecting a Launch Configuration from the Toolbar Checking for an Out of Sync Process Server Interactions During a Remote Debugging Session Setting Options for Console Output Configuring a Remote Process Connection As a first step in remote debugging, you must set up a configuration to indicate where processes are running and how you want to attach to them. 1 From the Run menu, select Debug. 2 In the Debug dialog, select New. 3 In the Name field, you can change the default configuration name, if desired, to make it more meaningful. This is useful if you set up multiple configurations to various servers or for various authenticated users. 4 In the Main tab, the default Server URL is displayed for the ActiveBPEL server included with ActiveWebflow Professional. Modify this URL if you want to point to the ActiveBPEL engine in another location or to a different ActiveWebflow server. 5 In the Process Selection panel, select what processes you want to debug, and refer to Selecting Processes for Remote Debugging for details. Manual process selection or breakpointsa list of attached processes appears in the Debug view, and you can right-mouse click on the process to connect to it. Prompt for process selection from list When you select Debug, a dialog box appears displaying running or completed processes available for debugging Stop on next process instance creation When you select Debug, a Waiting message appears until a process instance is created for any deployed process. Once the process is instantiated, the local copy of the process opens in the Process Editor for debugging. Refer to Options Tab below to hide the waiting message for the current debug configuration and to Remote Debugging Preferences to hide the waiting message for all processes. 320 Debugging Remote Processes Running on the Server Version 1.5

321 6 In the Process location field, type in a process name, if desired. Only processes of this name are attached to during instance creation and are used as the default filter for process lists. If desired, you can type in the qualified name, enclosing the namespace in curly braces, as shown in the example. By using the qualified name, you can pinpoint processes of similar names using different namespaces. 7 Enable the option Attach to any process on breakpoint, if desired, to indicate that any local copy of a process containing a breakpoint will be attached to, if not already attached, when a breakpoint is hit. Note: Do not enable this option for processes running on a high volume server. Remote debugging may impact performance. Authentication Tab 1 Select one of the following: No credentials required. No username and password are required to access the ActiveWebflow Server. Always prompt for credentials when connecting. Prompt for username and password when beginning a remote debug session for a running process on ActiveWebflow Server. Use supplied credentials when connecting. Use the Username and Password filled in below when connecting to the ActiveWebflow Server. 2 Enter a Username and Password, if required, for the Server URL. User authentication is set up on the server for the ActiveBPEL engine service. Options Tab You can select options for a particular debug configuration that override the default settings listed in Preferences. Preferences are located in Window>Preferences>ActiveWebflow>Remote Debug. For details on the default settings, see Remote Debugging Preferences. Common Tab 1 Select the Common tab. 2 Modify the following defaults, if desired: Version 1.5 Chapter 16: Simulating and Debugging 321

322 Local or Shared configuration. You can select Shared and then save the currently named configuration to a workspace folder to share it. The configuration settings are added to an XML file named configuration_ name.launch. Debug mode perspective. This setting controls the perspective that is switched to when an application is launched in debug mode. By default, each launch configuration inherits this setting. However, a launch configuration may also override this setting by specifying an explicit perspective. Favorites menu. By default the Debug and Run icons are displayed on the ActiveWebflow toolbar (also known as the favorites menu). Starting a Debug Session Select one of the following to start or delay a remote debug session. Select Apply to save this configuration and continue creating another configuration If the server is running, select Debug to save and begin remote debugging for the current configuration If the server is not running, select Close. The configuration is saved, and you can run it from the Debug drop-down list in the main toolbar. Selecting Processes for Remote Debugging When you create a configuration for attaching to remote processes, as described in Configuring a Remote Process Connection, you can select how you want to attach to a process. Here are some details on each selection type. Manual process selection or breakpoints You can set up a launch configuration and then connect to a process to debug it. As the example shows, select Connect to Process from the launch configuration. The Select Process dialog displays. 322 Debugging Remote Processes Running on the Server Version 1.5

323 Select process by Id or from a list When you start up debugging, by selecting Debug in the Debug dialog, the Select Process dialog appears, as shown in the example. By default, the Process List displays running processes. To make other selections, do one of the following: Select a process from the list or type an ID in the Connect to ID box. Select process instances of a process by typing a name in the Name field and selecting Refresh. Select All, Running, or Complete from the State menu Version 1.5 Chapter 16: Simulating and Debugging 323

324 Note: The Select Process dialog can display the namespace plus the process name, if desired. For details, see Remote Debugging Preferences. Stop on next process instance creation When you start up debugging, the following dialog can appear, if you set a preference to show it. When any deployed process is instantiated, the local copy of it in your workspace is opened in the Process Editor. The process is suspended at the initial activity. You can run through or step through the process. Note: You can set a preference to show/hide the Waiting to Start dialog. For details, see Remote Debugging Preferences. Setting Breakpoints on a Process for Remote Debugging You can set a breakpoint on any process. Set the breakpoint on your workspace copy of the process. You do not need to deploy a process with breakpoints set. For more information, see Running to a Breakpoint in a BPEL Process. You can attach to any running process on breakpoint by enabling an option in the Debug dialog. With this option enabled, all workspace copies of your processes are scanned to see if any breakpoints are set. ActiveWebflow connects to any running process when a breakpoint is hit and begins a remote debug session. Using the Debug View, Process Editor, and Variable View for Remote Debugging In remote debugging, the debug target is the remote process engine. The debug target contains multiple processes which have been attached to for debugging. When you attach to a process, it is suspended by the debug target until you resume or step the process. 324 Debugging Remote Processes Running on the Server Version 1.5

325 In the Debug View, you can use all the same functions that apply to simulation. In addition, you can suspend, disconnect, and terminate all threads, as shown in the illustration. 1 Suspend Suspends the selected running process 2 Disconnect Disconnects from the remote server resuming any processes, which have been suspended 3 Remove All Removes all terminated processes Once a process is attached, ActiveWebflow automatically opens the workspace copy of it in the Process Editor. The Process Editor shows the state of the attached process instance, in the same way as it does for simulation, as the example shows. Version 1.5 Chapter 16: Simulating and Debugging 325

326 The Process Variables view is automatically updated to follow the instance data of the selected process. Remote Debugging Preferences You can set remote debugging preferences as follows: 1 From the Window menu, select Preferences. 2 Select ActiveWebflow>Remote Debug. 3 Set preferences for: Process List Limit. Set the number of processes to view in the Select Process dialog. This dialog appears when you want to be prompted for a process to debug. Show qualified process names. Enable this setting to view the process name qualified by a namespace. The process name is displayed in the Select Process dialog. If you have two similar process names from different namespaces, this option helps you select the correct process. Show Waiting to Start dialog. When you want to debug the next process instance that occurs, the Waiting for Process dialog appears. Enable this setting to show the dialog. When the next process is instantiated, the local 326 Debugging Remote Processes Running on the Server Version 1.5

327 copy of the process appears in the Process Editor and is suspended in the Debug view. Disconnect launch when last connected process terminates. Enable this checkbox to automatically disconnect the launch and server when the last executing process terminates. If you leave the checkbox blank, you can select the Disconnect icon on the Debug view toolbar for each launch. Check for out of sync process definition when connecting. Enable this setting to check that the BPEL process definition on the server matches the BPEL process definition in your Navigator view. The process you want to debug remotely may be an older or newer version than the process in your workspace. During remote debugging, ActiveWebflow uses your workspace copy of the process and the actual instance data from the server to perform debugging. This means the workspace copy of the process should be identical to what is running on the server. It is recommended that you leave this option checked. If a process is out of sync, ActiveWebflow displays an error message during remote debugging. On disconnect of suspended process, select whether you want to be prompted, resume running the process, or take no action. Selecting a Launch Configuration from the Toolbar You can select a named debug configuration from the toolbar. You can use this shortcut to start a remote debugging session. The Debug drop-down list shows connection configurations, as the example shows. See Configuring a Remote Process Connection for more information. Checking for an Out of Sync Process You can set a Remote Debug preference to check for an out of sync process definition. This means that ActiveWebflow checks that your local copy of the process matches the server copy when connecting to the server. Version 1.5 Chapter 16: Simulating and Debugging 327

328 During remote debugging, ActiveWebflow uses your workspace copy of the process and the actual instance data from the server to perform debugging. The workspace copy of the process should be identical to what is running on the server. However, if the process definitions do not match, you can perform remote debugging anyway, and ActiveWebflow does its best to step through the activities. With the preference enabled, if the server copy and the local copy of your process are out of sync, ActiveWebflow give you an option to choose another process, cancel, or continue to starting remote debugging, as the illustration shows. You can ignore the warning and continue to debug or select another process definition. If you disable the out of sync option, remote debugging begins, but an error messages is displayed when the mismatch is reached. Server Interactions During a Remote Debugging Session During remote debugging, the following occurs: When you suspend a process, the process is suspended on the server When you step the process, the process resumes on the server When you terminate the process, the process terminates on the server The Console shows processing steps For more information about Console output, see Setting Options for Console Output. Setting Options for Console Output When a remote debug session attaches to a process manually, or by connecting on a breakpoint, some event logging for that process may have already taken place in 328 Debugging Remote Processes Running on the Server Version 1.5

329 the BPEL Server engine. If so, that log is sent to the remote debug target and displayed in the Console view. If logging is turned off in the engine, then no log exists, and the message "Preceding events for this process are not available" appears, followed by individual events, logged as they are received by the debugger from the engine. For more information regarding setting logging options, refer to the ActiveWebflow Server documentation. Version 1.5 Chapter 16: Simulating and Debugging 329

330 330 Debugging Remote Processes Running on the Server Version 1.5

331 17 Deploying Your Processes What s in this chapter What is Deployment? Preparing for Deployment Overview of Process Deployment Steps Creating a Process Deployment Descriptor File Editing a Process Deployment Descriptor File Creating a Partner Definition File Creating a Business Process Archive File Using a BPRD Script to Regenerate and Deploy a BPR File Deploying Your Process to the ActiveBPEL Server Deploying Your Process to ActiveWebflow Enterprise or Standard Starting the Server and Running a Process What is Process Versioning? What is Deployment? Deployment is the act of publishing your BPEL process to an ActiveWebflow server where it can run. In ActiveWebflow Designer, you create the BPEL process as well as some additional files required for the ActiveBPEL engine that runs on the server. When your process runs, the ActiveWebflow server ensures that the correct partner services and messages interact with your process. The required files you create during deployment provide this information. The ActiveWebflow server uses the WS Addressing protocol to identify the partner endpoints that the process communicates with. In addition, if you have purchased ActiveWebflow Standard or Enterprise, you can maintain different versions of your deployed processes. Version 1.5 Chapter 17: Deploying Your Processes 331

332 Preparing for Deployment Preparing your BPEL process for deployment to the ActiveWebflow server requires two tasks: Preparing BPEL Files for Deployment Selecting an ActiveWebflow Server Platform for Deployed Processes In addition, you may wish to read Endpoint References and WS-Addressing Considerations before creating the process deployment descriptor file. This topic describes the details you may need for providing necessary deployment information. If your partner s service requires authenticated access, see Endpoint References Requiring Credentials for Access. Preparing BPEL Files for Deployment A BPEL file is ready for deployment to the ActiveWebflow server when there are no errors in the Problems view and when a simulated execution of the process terminates normally. To ensure your process is deployment-ready, complete this checklist: Ensure that you have filled in all the required properties for each activity, such as partner link, port type, operation and variable for receives, invokes, and replies Ensure that at least one receive or pick activity s Create Instance property is set to Yes. Ensure that the Abstract Process property is set to No for the process Ensure that the WSDL file(s) that your process references is valid Step through a simulated execution of the process, as described in Simulating and Debugging Selecting an ActiveWebflow Server Platform for Deployed Processes Your BPEL process can run on any BPEL server. However, to deploy it to an ActiveWebflow server, make a package of files (.bpel,.wsdl,.pdd) for deployment as described in Creating a Business Process Archive File. ActiveWebflow Designer includes the ActiveBPEL server in your installation folder. You can deploy processes to this development server as you design and test 332 Preparing for Deployment Version 1.5

333 processes. Instructions for deploying to this server are included in Creating a Business Process Archive File. Depending on the version of ActiveWebflow you purchased, you may have additional server platforms available that include advanced features such as process persistence, versioning, and cluster management. Endpoint References and WS-Addressing Considerations At deployment time, you need to specify the location information for each partner link endpoint reference. Also, you can assign an endpoint reference dynamically, detailed in Copy Operation Dynamic Endpoint Reference Example. The protocol to specify location information for an endpoint reference is based on the Web Services Addressing (WS-Addressing) specification. The WS-Addressing specification standardizes the format for referencing a Web service allowing you to create uniquely identified Web services and Web service instances that are not bound to a specific transport mechanism, such as HTTP. Using WS-Addressing, the endpoint information is added to the header of a SOAP request and not to the URL specified in the SOAP body. Having endpoint reference information in a SOAP header means that you can do the following: Specify Web service instance IDs Select Reply To and Fault To addressees Select From endpoint references in the case where an acknowledgement needs to be sent back to the sender The basic WS-Addressing syntax is as follows: <wsa:endpointreference> <wsa:address>anyuri</wsa:address> <wsa:servicename PortName= portname >Service QName </wsa:servicename> </wsa:endpointreference> where: Address is a mandatory element that identifies an endpoint. It may be a network address or a logical address. ServiceName is the qualified name, or QName, for the service being invoked. This service must be defined in a WSDL file that is deployed with the process or one that is available in the ActiveBPEL engine s WSDL catalog. Version 1.5 Chapter 17: Deploying Your Processes 333

334 PortName identifies the service port being invoked. Note that you can add credential details to the endpoint reference, described in Endpoint References Requiring Credentials for Access. You can review the WS-Addressing specification at the Web site of any of the specification s contributors, including IBM, BEA Systems, and Microsoft. Endpoint References Requiring Credentials for Access At deployment time, you must specify the location information for each partner link endpoint reference. If a partner s service requires authentication for access, you can add credential details to the partner link definition in the process deployment descriptor file. The following example shows how to include credentials for a partner service in the process deployment descriptor file. <partnerlink name="worldcallbackservice"> <partnerrole endpointreference="static"> <wsa:endpointreference xmlns:s=" <wsa:referenceproperties xmlns:aecred= > <aecred:username>authorizeduser</aecred:username> <aecred:password>guest</aecred:password> </wsa:referenceproperties> <wsa:address>...</wsa:address>... </partnerlink> The tags and values in bold are required. A password is not required, but you must use the prefixed password tag if you are including a password. Note the following details about the credentials definition: A WS-Addressing reference property points to the required namespace Add a prefix, such as aecred, to the namespace Use the prefix in the username and password tags For details on how to add the WS-Addressing properties, see Creating a Process Deployment Descriptor File and Editing a Process Deployment Descriptor File. Overview of Process Deployment Steps The following illustration shows how you can take your BPEL process from design to deployment. 334 Overview of Process Deployment Steps Version 1.5

335 1 In ActiveWebflow Designer, add WSDL files to Web References as needed, create the BPEL file and the Process Deployment Descriptor (.pdd) file. See Creating a Process Deployment Descriptor File for details. 2 Create a Partner Definition file to list often-used partners for multiple processes, if desired. See Creating a Partner Definition File for details. 3 In ActiveWebflow Designer, create the process deployment package (.bpr) file. See Creating a Business Process Archive File for details. 4 During design and testing, export the.bpr file to the ActiveWebflow server deploy folder. See Deploying Your Process to the ActiveBPEL Server for details. Once the process is deployed, it becomes active when an initial receive activity (or pick or event) receives a message. Creating a Process Deployment Descriptor File A Process Deployment Descriptor (.pdd) file describes the relationship between the partners defined in the BPEL file and the implementation required to interact with actual partner endpoints (Web services). You create a.pdd file to indicate where you want your endpoint references to come from. Version 1.5 Chapter 17: Deploying Your Processes 335

336 In addition, if you are deploying a process to a production server, you can specify process version details. To create the process deployment descriptor file: 1 In ActiveWebflow Designer, select File>New>Deployment Descriptor. 2 Select a Deployment Platform. For details see Deployment Platforms. 3 Select a BPEL file to be deployed, and select Next. 4 For information on platform-specific deployment options, see Deployment Platforms. Select Next. 5 Fill in the Partner Links page for each partner link as follows. a b c d Select a partner link from the list. If the partner link has a Partner Role defined, select the Endpoint Type for the partner link. For explanations and examples of Endpoint Types, see Partner Role Endpoint Types. If the Endpoint Type is Static, see the notes below. If the partner link has a My Role defined, select the Binding style and Service Name. Optionally, you can specify Allowed Roles. For explanations of these properties, see My Role Binding, Service Name, and Allowed Roles Options. 6 Select Next, and select a folder and a process deployment descriptor filename, if you want to change the defaults. 7 Click Finish. The.pdd file opens in an editor. You can manually edit the file if necessary. For example, you may need to add credentials for authenticated access to a service, as described in Endpoint References Requiring Credentials for Access. Notes for Static Endpoint Type: If you select Static for an Endpoint Type, WS Addressing is automatically provided, based on the service bindings in the imported WSDL, as the following example shows. 336 Creating a Process Deployment Descriptor File Version 1.5

337 If the WSDL does not include bindings, WS Addressing elements are added with placeholders, as the following example shows. You can edit the placeholders within wizard or within the.pdd file when the wizard closes. For more information, see Editing a Process Deployment Descriptor File. If you want to select a different service, you can. See Selecting a Service for a Deployment Descriptor Partner Link for details. Deployment Platforms During the creation of the Process Deployment Descriptor file, you can select one of the following deployment platforms: ActiveBPEL Engine. Select this option if you are in a design and testing phase and do not need to specify process version details. The process version page of the wizard, which applies only to Active Webflow Standard or Enterprise servers, is skipped. The ActiveBPEL Engine is included in the ActiveWebflow Designer installation. ActiveWebflow Standard. Select this option if you have purchased ActiveWebflow Standard and want to provide version details for processes deployed to the Standard server. If you are in a design and testing phase, select ActiveBPEL Engine. ActiveWebflow Enterprise. Select this option if you have purchased ActiveWebflow Enterprise and want to provide version details for processes deployed to the Enterprise server. If you are in a design and testing phase, select ActiveBPEL Engine. Version 1.5 Chapter 17: Deploying Your Processes 337

338 Platform-Specific Deployment Options You can select platform-specific deployment options for new and running versions. If you do not change any settings, the server uses the defaults. Note that only one version of a process can create new process instances. Process Version Effective Date Expiration Date Running Process Disposition By default, the ActiveWebflow Standard or Enterprise server autoincrements the version number for new versions. Auto-incrementing is based dropping the minor version number and incrementing the major version number by one. For example, 1.5 becomes 2.0. To define your own version number for this process, type in a number, such as 1.5. If the effective date is blank or in the past, then the process immediately becomes the current version. The current version for a process QName is the one capable of creating new process instances. If the date is in the future, the server makes this version the current version when the effective date arrives. If you intend to deploy your process to a server in a different time zone, be sure to edit the deployment descriptor file to include a time zone expression. For details, see What is Process Versioning?. If the expiration date is blank, then the process will not expire. Providing an expiration date is useful if you want the process to run for a limited period of time. An expired process version cannot create new process instances, but running process instances complete normally. You can specify an expiration date. If you intend to deploy your process to a server in a different time zone, be sure to edit the deployment descriptor file to include a time zone expression. For details, see What is Process Versioning?. By default, the all process instances are maintained. The default value of Maintain allows process instances created under previous versions to run to completion when this version becomes effective. You can select Migrate Version to convert process instances running against an earlier version to use the new version. This is useful if you have made only a small change to the BPEL process and want to apply the change to process instances already running. The only permitted changes are XPath expression changes. Select Terminate to terminate running processes so that you can inspect them and decide whether to continue to run them to completion. For details, see What is Process Versioning? If you do not change the defaults, the.pdd file does not include any version details. To add or change version details, see Editing a Process Deployment Descriptor File. 338 Creating a Process Deployment Descriptor File Version 1.5

339 Partner Role Endpoint Types During the creation of the Process Deployment Descriptor file, you must select an endpoint type for each partner role defined in a partner link. An endpoint type is a binding property that indicates how to communicate with the Web service the process interacts with. The different types give you control over specifying services you work with now and in the future. For example, you can hard-code a service binding by making it static, or you can select more versatile options for changing and adding new service partners dynamically without redeploying the process. The endpoint types are defined in the following table. Endpoint Type Dynamic Invoker Principal Static Description Indicates that the service location (that is, the endpoint reference) is provided dynamically within the BPEL process. The location must be assigned dynamically within a Copy Operation of an Assign activity. Indicates the endpoint reference will be extracted from an inbound SOAP message s headers. This setting implies a partner link that defines an asynchronous conversation. The BPEL process plays one role of the partner link and uses the inbound message from the invoker in order to determine where to call back on the partner link. Indicates the endpoint reference is determined based on the value of the authenticated principal that sent the request to the BPEL process. In this configuration, it is assumed that service endpoints for the BPEL process are secured. When a message arrives on one of these endpoints, the authenticated user s principal (typically their username) is used as a lookup in ActiveWebflow server. The server determines the proper endpoint to use based on the principal and the partner link type being invoked. You can deploy a Partner Definition (.pdef) file to the server for partner lookups. See Creating a Partner Definition File for details. The principal endpoint type provides the security of knowing whom you are dealing with and the flexibility of being able to configure the endpoints independently from the process and its deployment. As in the invoker type, the use of principal implies an asynchronous conversation since it is used to populate the partner role used for a callback. Indicates the endpoint information is defined in the deployment descriptor file and is used for all invocations of the partner link. Note: If the partner service requires authenticated access, see Endpoint References Requiring Credentials for Access. Version 1.5 Chapter 17: Deploying Your Processes 339

340 My Role Binding, Service Name, and Allowed Roles Options During the creation of the Process Deployment Descriptor file, you must select a binding style and service name for each service partner link of my role type. The binding styles are the standard SOAP styles of RPC (remote procedure call), Message, and External. Select the SOAP style that is appropriate for the simple, schema, or complex message variable manipulated by your service s operation. An RPC invocation means that the body of a SOAP request has an outer element which matches the operation name and contains inner elements each of which maps to a parameter of the operation. A Message invocation means the entire SOAP message consists simply of a single entity which is an XML document. An External invocation applies only to ActiveWebflow Enterprise. The primary reason for deploying with the external binding is to take advantage of facilities offered by the application server with regard to securing or managing the web service. Instead of using the built-in mechanism provided by ActiveWebflow for service publication, you can control the publication of your services through WS4EE. The detailed documentation to help you implement a WS4EE service that interfaces with ActiveWebflow server is under construction. Look for information on the support forums at Note: Selecting External prevents the server from executing your service unless you have built a custom service requester. Do not select this binding style for any deployments other than an ActiveWebflow Enterprise custom deployment. The Service Name is the name of the endpoint that ActiveWebflow server creates for the BPEL process. This name must match the address in the binding section of the WSDL file. Allowed Roles is optional and specifies one or more security roles that an authenticated user must have in order to communicate with the BPEL process. If the application server is not configured with security then the allowed roles field is ignored. Refer to your application server documentation on how to secure individual web applications. 340 Creating a Process Deployment Descriptor File Version 1.5

341 Selecting a Service for a Deployment Descriptor Partner Link During the creation of the Process Deployment Descriptor file, you must select an endpoint type for each partner role defined in a partner link. If you select a static type, to hard-code a service binding, you can select the service to use. By default, the binding information from the imported WSDL is used. However, if you want to bind to a different service, you can select the Dialog button as shown in the illustration. The WSDL you select must contain binding information. See Creating a Process Deployment Descriptor File for details on opening the New Deployment Descriptor dialog. Editing a Process Deployment Descriptor File After you create a.pdd file, as described in Creating a Process Deployment Descriptor File, the file opens in an editor, where you can edit and view details for: Static endpoint references Process version details Note: If you have an endpoint reference that is a principal, see Creating a Partner Definition File. Version 1.5 Chapter 17: Deploying Your Processes 341

342 Editing Static Endpoint References The syntax for adding static attributes is based on WS-Addressing, as described in Endpoint References and WS-Addressing Considerations and Endpoint References Requiring Credentials for Access. The Process Deployment Descriptor editor validates the.pdd file against a schema. If the editor detects errors, it generates errors and displays an error or warning icon in the marker bar next to each line in the.pdd file where the error occurs. If you edit the file, you must specify actual endpoint locations for each Web service. The partner links you defined in your process must reference actual services. You accomplish this work by specifying the Web service address and port names using the WS-Addressing protocol. To add static endpoint references: 1 For each partner link, do the following: Replace FILL_IN_NAMESPACE with the target namespace from the WSDL file where the partner link type is defined. Replace FILL_IN_ADDRESS_URI with the URI of the service as specified in the <service> section of the WSDL file for the service. Replace FILL_IN_PORT_NAME with the service port name as specified in the <service> section of the WSDL file for the service. Replace FILL_IN_SERVICE_NAME with the service name as specified in the <service> section of the WSDL file for the service. 2 Save the file. The following illustration shows a sample.pdd file before editing, when the service binding has not yet been provided. Note that a warning icon in the marker bar indicates that namespace information must be configured. 342 Editing a Process Deployment Descriptor File Version 1.5

343 The following illustration shows the <service> section of a WSDL file and the information needed for the.pdd file. The namespace information is not shown. Tips for using the pdd editor: Be sure to check the Problems view for a list of errors and warnings. Doubleclick an error to go to the line that caused it in the editor. You can display line numbers in the editor, if desired. In the main menu, select Window>Preferences>Workbench>Editors>Text Editor> to enable Show Line Numbers. Version 1.5 Chapter 17: Deploying Your Processes 343

344 Editing Process Version Details If you added process version details while creating the.pdd file, you can edit them if needed. Note that if you did not change the defaults, there is no version information added to the.pdd: the server uses the defaults. The following example shows the syntax for version information. <version effectivedate=" t00:00:00-05:00" expirationdate=" t00:00:00-05:00" id="1.5" runningprocessdisposition="migrate"/> For details on process versions, see What is Process Versioning?. Creating a Partner Definition File A partner definition file contains the endpoint information for a single service partner. The file contains one endpoint reference for each partner link type that the partner implements. The endpoint information applies to all partner links in BPEL processes that are deployed with the principal endpoint source. The authenticated principal must match the principal in the partner definition file. For example, a service partner named National Bank can send an authenticated request to a BPEL process to assess the risk of loaning funds to a customer. The server looks up the authenticated principal to determine the correct endpoint to use to call back National Bank after the risk is assessed. This is useful because National Bank might have partner link types for additional services such as refinancing rates and insurance quotes. The partner definition file can contain one endpoint reference for each partner link type. You can deploy the partner definition file by adding it as the only file in a business process archive, if desired. If partner definition details change, you do not need to redeploy a BPEL process. You can redeploy the.pdef file. There is only one.pdef file for each principal so the most recently deployed file for a principal sets all of the endpoints for that principal. Note: To take advantage of a partner definition, the endpoint type for the partner link must be principal. For details, see Creating a Process Deployment Descriptor File. To create a partner definition file: 1 Select File>New>Partner Definition. 2 Select a workspace folder to store your partner definition file. 344 Creating a Partner Definition File Version 1.5

345 Tip: For convenience select the project folder where your process deployment descriptor (.pdd) file is located. 3 In the Partner definition name field, name the file. The wizard automatically adds a.pdef extension. 4 In the Principal field, type in a name identifying your service partner. For example, use the service name or company name. 5 Select Finish. The partner definition file opens in an editor, as the example shows. 6 From the right mouse menu, select Add Partner Link Type. 7 Select the Partner Link Type and Role from the drop-down lists. Tip: To filter the partner link type list, you can create a Web References Reference Set. For details, see Filtering the Web References View by Reference Set. 8 If the endpoint binding is not automatically added, you can choose service information from a different WSDL file by selecting the Dialog button at the right of the text box. The following illustration shows a sample of a completed Add Partner Link Type dialog. Version 1.5 Chapter 17: Deploying Your Processes 345

346 9 After you select OK, the partner definition appears in the editor, as shown in the example. 10 Continue adding more partner definitions, if desired, by repeating steps six through nine. Then save the file. When you create a business process archive to deploy files, be sure to select the.pdef file for inclusion. For details, see Creating a Business Process Archive File. Example File: <?xml version='1.0' encoding="utf-8"?> <partnerdefinition principal="acme" xmlns=" pdef.xsd" 346 Creating a Partner Definition File Version 1.5

347 xmlns:wsa=" xmlns:s=" <partnerlinktype name="s:storelt"> <role name="customer"> <wsa:endpointreference xmlns:store=" <wsa:address>store:anyuri</wsa:address> <wsa:referenceproperties xmlns:credentials=" active-endpoints/endpoint-credentials"> <Credentials:username>MyUser</Credentials:username> <Credentials:password>MyPassword </Credentials:password> </wsa:referenceproperties> <wsa:servicename PortName="StorePort">store:StoreService </wsa:servicename> </wsa:endpointreference> </role> </partnerlinktype> </partnerdefinition> Creating a Business Process Archive File To deploy your process to an ActiveWebflow server, you must add all relevant files to an archive file (.bpr file), which is similar to a Web archive file. The archiving process is automated for you in ActiveWebflow Designer. Before creating a.bpr file, you must create a.pdd file, described in Creating a Process Deployment Descriptor File. Optionally, you can create partner definitions, as described in Creating a Partner Definition File. Tip: You may want to create a workspace project folder called bpr to hold your archive files. Select File>New>Other>Simple>Folder to create a new folder in your project. To create a.bpr file: 1 Select File>Export>Business Process Archive File. 2 Select the process deployment descriptor file(s) (.pdd files) and partner definition files (.pdef files) to include in the archive, as shown in the following example. Version 1.5 Chapter 17: Deploying Your Processes 347

348 3 Select the export location and filename for the archive. Tip: You may want to store archive files in a project folder called bpr. 4 Select a Deployment Type: None. Select this option if you do not wish to deploy your BPR archive upon completion of the file export. File. Select this option to deploy the archive upon export. In the Deployment location field, browse to the deployment folder on the ActiveWebflow server. The default location is \ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bpr\. By specifying a deployment folder, you can automatically deploy processes to the server. You can provide the information later by editing the.bprd file. Web Service. For details, see Deploying Your Process to ActiveWebflow Enterprise or Standard. 5 If desired, select the option to Save the archive specification as an Ant task in the workspace, and select a location for this file. For details on this option, see Using a BPRD Script to Regenerate and Deploy a BPR File. 348 Creating a Business Process Archive File Version 1.5

349 6 Click Finish to create the.bpr file and optional.bprd file. If you added a new folder to hold these files, you can select File>Refresh to view the filenames, as the example shows. Using a BPRD Script to Regenerate and Deploy a BPR File When you create a.bpr file, as described in Creating a Business Process Archive File, you have the option to create an Ant script (a.bprd file) that you can use to quickly regenerate and deploy a.bpr file. Use the BPRD Ant script to: Update a.bpr file after modifying a BPEL or process deployment descriptor file Add deployment path information for automatically deploying a.bpr file Regenerating a.bpr File You must update a.bpr file after you have modified one or more files in the original archive. If your archive contains many BPEL and.pdd files, you may find it quicker and more convenient to update the archive by using the Ant script you created when you first created the.bpr file. If you want to add any new files to the archive, you must create a new.bpr using the File>Export option or modify the.bprd file by hand to add syntactically correct references to the new files. To modify the.bprd file by hand, you must be familiar with the Ant scripting language. To regenerate a.bpr file: 1 In the Navigator, select the.bprd file you created the first time you created the business process archive (.bpr) file. 2 Right-mouse click and select Execute. ActiveWebflow informs you when the new.bpr is generated. Version 1.5 Chapter 17: Deploying Your Processes 349

350 Automatically Deploying a.bpr File If you did not select a Deployment Type when you created the.bpr archive, you can add deployment information to the BPRD script and execute the script. 1 From the Navigator, double-click the.bprd file to open it. 2 Follow the comments in the script to provide File or Web Service deployment information. You must specify a valid archive deployment location and enable the deploy target. 3 Save the file. 4 In the Navigator, select the right-mouse menu for the.bprd file and select Execute. ActiveWebflow informs you when the new.bpr is generated. Deploying Your Process to the ActiveBPEL Server ActiveWebflow Professional includes the ActiveBPEL server in your local installation folder. You can deploy processes to this development server as you design and test processes. Instructions for deploying to this server are included in Creating a Business Process Archive File. Depending on the version of ActiveWebflow you purchased, you may have addition server platforms available that include advanced features such as process persistence, versioning, and cluster management. To run a process on the ActiveBPEL server, you must copy the BPEL process archive (.bpr file) to a server folder called bpr. When the ActiveBPEL engine is running, it scans this folder for new, changed, and deleted files. You can deploy your.bpr file to the ActiveBPEL server automatically or manually. For information on automatic deployment, see Using a BPRD Script to Regenerate and Deploy a BPR File. To deploy and run your process on ActiveBPEL server for design-time testing: 1 Select File>Export>Business Process Archive File. 2 Select the process deployment descriptor file(s) (.pdd files) and partner definition files (.pdef files) to include in the archive, as shown in the following example. 350 Deploying Your Process to the ActiveBPEL Server Version 1.5

351 3 Select the export location and filename for the archive. Tip: You may want to store archive files in a project folder called bpr. 4 If you want to deploy the archive upon export, select the check box next to Copy created archive (.bpr) to deployment location, and browse to the deployment folder on the ActiveWebflow server. The default location is \ActiveWebflow Professional Installation folder\server\activebpel_ Tomcat\bpr\. By specifying a deployment folder, you can automatically deploy processes to the server. You can skip this step, if desired, and provide the information later by editing the.bprd file. 5 If desired, select the option to Save the archive specification as an Ant task in the workspace, and select a location for this file. For details on this option, see Using a BPRD Script to Regenerate and Deploy a BPR File. 6 Click Finish to create the.bpr file and optional.bprd file. If you added a new folder to hold these files, you can select File>Refresh to view the filenames, as the example shows. Version 1.5 Chapter 17: Deploying Your Processes 351

352 See also Starting the Server and Running a Process. Deploying Your Process to ActiveWebflow Enterprise or Standard If you have purchased ActiveWebflow Enterprise or Standard, you can deploy your processes directly to the running server. You may find it convenient to use ActiveWebflow Designer to deploy your processes. Process deployment can also be accomplished in the ActiveWebflow Enterprise or ActiveWebflow Standard Administration Console. To deploy your process to ActiveWebflow Enterprise or Standard from ActiveWebflow Designer: 1 Select File>Export>Business Process Archive File. 2 Select the process deployment descriptor file(s) (.pdd files) and partner definition files (.pdef files) to include in the BPR archive. 3 Select the export location and filename for the.bpr archive. This allows you to save the BPR file to the file system. 4 In the Deployment section, select Web Service as the Type, as shown in the following example. 352 Deploying Your Process to ActiveWebflow Enterprise or Standard Version 1.5

353 5 In the Deployment URL field, change localhost:8080 to match the address of your server. If required for your server, specify the username and password. 6 Click Finish to deploy the archive to the server. The Deployment Complete dialog appears when you deploy a BPR file to the server. Deployment Complete The Deployment Complete dialog displays the results of deploying a.bpr file to ActiveWebflow Enterprise or ActiveWebflow Standard. The following illustration shows an example of this dialog. Version 1.5 Chapter 17: Deploying Your Processes 353

354 Note the following: Each process successfully deployed has a version number. The version is the one specified in the.pdd or the auto-incremented number. You can select a process definition to view a brief deployment log for it. For a complete deployment log, check the server Administration Console. Partner definition files (.pdef files) and WSDL files are not validated and are automatically deployed Starting the Server and Running a Process After you deploy a process, described in Deploying Your Process to the ActiveB- PEL Server, you can run the process by starting the server and sending the appropriate message to instantiate the process. The ActiveWebflow Server that comes with ActiveWebflow Designer consists of the ActiveBPEL engine running under Apache Tomcat. Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies. You must start Tomcat, and then the ActiveBPEL engine automatically starts. When it starts, it scans for new, updated, and deleted.bpr files. 354 Starting the Server and Running a Process Version 1.5

355 1 Double-click startup.bat, located in: \ActiveWebflow Professional Installation folder\server\activebpel_tomcat\bin 2 Tomcat starts up in a command window, and the ActiveBPEL engine also starts. Minimize the command window. You can use the ActiveBPEL Administrative Console to manage deployed and active processes. To display the Console, type the following into your browser: For more information, select Help in the Console, or view a printed copy of the Help. Refer to ActiveWebflow_DevelopmentServer_UserGuide.pdf in ActiveWebflow Professional Installation folder\docs folder. Tips on running a process: To run your process, you may want to create a test client, designed to send the appropriate message to instantiate the process and receive a reply from the process. Refer to ActiveWebflow Tutorial for an end-to-end example of creating, deploying, and running a process using a test client. You can re-deploy a process to the server even if the process is actively running. As a best practice: Suspend the process before overwriting the.bpr file. The ActiveBPEL engine scans the deployment folder to see what has changed. What is Process Versioning? ActiveWebflow Standard and Enterprise products include a server that manages process versioning. Process versioning allows different versions for a given process to exist in ActiveWebflow server. Two deployments are considered to be different versions of the same process if they have the same target namespace and name in the BPEL file, but one deployment differs from the other in some way. Process versioning allows you to control when processes become effective and for how long. You can also control what happens to processes created by older versions when a new version becomes effective. While multiple versions of a process can exist concurrently, only the latest effective version is capable of creating new process instances. The latest effective version is in a current state. Other states include future, to describe versions that have an effective date in the future, expired to describe ver- Version 1.5 Chapter 17: Deploying Your Processes 355

356 sions whose expiration date has arrived or has been set, and inactive to describe expired versions that no longer have running process instances. The process deployment descriptor provides selections for describing how a deployment is to be versioned. These selections are all optional and have default values as described below. If desired, you can provide version information as described in Creating a Process Deployment Descriptor File. The following example shows the syntax for version information in the.pdd file. <version effectivedate=" t00:00:00-05:00" expirationdate=" t00:00:00-05:00" id="1.5" runningprocessdisposition="migrate"/> where: effective date is the date the new version becomes the current version and all new process instances run against it. Depending on the disposition selected for running processes, some may continue to run until complete using the older version. The effective date is an XML schema datetime value. Time is indicated as the midnight hour plus or minus the number of hours ahead of or behind Coordinated Universal Time (UTC) for the computer s time zone. In the example above, the computer time zone is eastern standard time, which is five hours behind UTC. For date/time details, refer to Deadline and Duration Expressions. If you do not provide an effective date, it defaults to the date and time the process is deployed to the server. expiration date is the date, beyond the effective date, the current version expires. An expired version is not capable of creating new process instances. Once all of the running processes tied to an expired version complete then the version becomes inactive. All process instances for the current version run to completion. The expiration date is an XML schema datetime value. (Same as effective date). If you do not provide an expiration date, the version does not expire until you manually expire it in the Server Administration Console or until a newer version is deployed. id is the process version number in major.minor format. You do not need to provide a version number. The ActiveWebflow Standard or Enterprise Server auto-increments new versions. The server increments a version number by dropping the minor value and adding 1 to the max number. For example, version 1.5 increments to version What is Process Versioning? Version 1.5

357 runningprocessdisposition is the action the server takes on any other versions of the same process that currently have processes executing once this version s effective date arrives. Valid dispositions are: Maintain. Indicates that all process instances for the previous versions should run to completion. This is the default value. Terminate. Indicates that all process instances running under previous versions should terminate on the effective date of the new version, regardless of whether or not the process instances are complete. Migrate. All running process instances created by previous versions will have their state information migrated to use the newly deployed process definition once its effective date arrives. If there are incompatible changes between the versions that would not permit them to be migrated, you receive an error message during deployment of the new process, and its deployment fails. Changes should be limited to XPath expression changes in the BPEL XML file. Criteria for a New Version A new version of a deployed process must meet the following criteria: The fully qualified process name must not change A new version can include a change to either the BPEL XML or the process deployment descriptor file A version is not new if the autoincrement feature determines that the BPEL XML and the deployment descriptor are the same as the deployed version having the highest version number. If the BPEL XML and the descriptor file do not contain any differences, then the version on the server is up-to-date and no deployment occurs. If you need to modify WSDL-related properties, such as partner links or correlation properties, then you should create a new process, not a new version Version 1.5 Chapter 17: Deploying Your Processes 357

358 358 What is Process Versioning? Version 1.5

359 18 Creating and Using Custom Functions What s in this chapter Custom Functions Technical Requirements and Sample Files Adding Custom Functions to Expression and Query Builders Specifying Custom Function Simulation Setup Adding Custom Functions to the ActiveWebflow Server Custom Functions Technical Requirements and Sample Files You can use custom functions in ActiveWebflow for process simulation and for process execution. Use custom functions by implementing the jaxen FunctionContext interface. Jaxen (java XPath engine) provides an API for XPath expression evaluation. Visit jaxen.org for detailed information on the jaxen API documentation. Custom functions must be implemented by classes that know how to resolve XPath function names and namespaces to implementations of these functions. By using a custom FunctionContext, new or different functions may be installed and available to the ActiveWebflow XPath expression writer. To provide valid files, you must be familiar with the jaxen API documentation for FunctionContext. To help you get started with custom functions, ActiveWebflow contains a Samples folder with all the files you need to see a working example of a custom function. Version 1.5 Chapter 18: Creating and Using Custom Functions 359

360 The sample files are located in \\ActiveWebflow Professional\ActiveWebflow_Samples\Other Samples\XPathCustomFunctions: Location File Description \PreferenceInfo\lib customxpathfunctionsamples.jar Contains the class files generated from the java source implementing the custom function \PreferenceInfo\Function- custom_xpath_demo_picklist.xml Descriptions To use the sample files, do the following: 1 Complete the steps described in Specifying Custom Function Simulation Setup. 2 Complete the steps described in Adding Custom Functions to Expression and Query Builders to add the function builder xml file. 3 Add the WSDL file to Web References. 4 Open the BPEL file. 5 Add sample data, and simulate the process. Document describing display elements for the Expression and Query Builders. \testbpel custom_xpath_func_demo.bpel Process illustrating the use of sample custom functions. custom_xpath_func_demo.wsdl Web Reference for the process Adding Custom Functions to Expression and Query Builders You can add custom functions to ActiveWebflow by completing the following: Write functions as described in Custom Functions Technical Requirements and Sample Files Register the functions with the simulation engine, as described in Custom Functions Technical Requirements and Sample Files After you complete these steps, you can, if desired, display the functions in expression and query builders. To display custom functions in expression and query builders, you must fill in values in the sample Custom Function XML file, or create your own file. The sample file is included in the ActiveWebflow Designer Samples folder. The XML syntax is shown as follows. 360 Adding Custom Functions to Expression and Query Builders Version 1.5

361 Note that the function builder schema namespace location is a required attribute for the <picklist> element. XML Syntax <picklist xmlns=" tionbuilderschema"> <pickheader pickdisplay="ncname" hoverhelp="ncname">+ <pickitem pickdisplay="ncname" syntax="prefix namespace:ncname Description: ncname" caretoffset="colnum-expr" hoverhelp="prefix namespace:ncname"/>* </pickheader> </picklist> Here is a sample of the file: <?xml version='1.0' encoding="utf-8"?> <picklist xmlns=" tionbuilderschema"> <pickheader pickdisplay="custom XPath Demo Functions" hoverhelp="sample custom XPath functions"> <pickitem pickdisplay="gethostname()" syntax="samplexpath:gethostname()" caretoffset="25" hoverhelp="samplexpath:gethostname() Description: Returns host name of the local system."/> <pickitem pickdisplay="gethostaddress()" syntax="samplexpath:gethostaddress()" caretoffset="28" hoverhelp="samplexpath:gethostaddress() Description: Returns IP address of the local system."/> </pickheader> </picklist> Once you have replaced the pick header, hover help, pick items and other details in this file with your own information, do the following: 1 Select Window>Preferences>ActiveWebflow>Custom Functions. 2 In the Function Description File Name section, select Add. 3 Browse to the folder where your function builder XML file is located, and select it. 4 Click OK. ActiveWebflow validates your file against the function description schema. Your custom functions are now available in expression and query builders, as shown in the following example. Version 1.5 Chapter 18: Creating and Using Custom Functions 361

362 Note the following about the display: Hover help displays the prefix and name of the function and its description The description appears on line two, after the line break When you click on the function to add it to the Expression text box, the cursor appears in the column set by the caretoffset element Specifying Custom Function Simulation Setup In ActiveWebflow, you can register custom XPath functions for use in expressions. When you simulate execution of your process, the functions are executed. Note: Custom functions must meet technical requirements described in Custom Functions Technical Requirements and Sample Files 1 Select Window>Preferences>ActiveWebflow>Custom Functions. 2 In the Specify simulation setup section, select Add. 3 In the Add Custom Function Details dialog, do the following: Type in a Prefix or a Namespace (or both). Use the prefix/namespace that is specified in your container file that implements the Custom Function. Note that the name is case-sensitive. 362 Specifying Custom Function Simulation Setup Version 1.5

363 Type in the fully qualified Class name of the container file that implements the custom function. Browse to the Classpath location of the folder, jar or zip file containing the class files for the custom function. The following illustration shows a sample custom function context. 4 Click OK. 5 In the Custom Functions Preferences page, select Test to test that the function(s) can be loaded by the engine classloader. The classloader is an URL classloader with the requested jar file as the URL. After selecting Test, You should see a message similar to the following: Your custom functions are available for use in expressions. You can also display custom functions in the expression and query builders, as described in Custom Functions Technical Requirements and Sample Files. See also Adding Custom Functions to the ActiveWebflow Server. Version 1.5 Chapter 18: Creating and Using Custom Functions 363