JBoss.orgCommunity Documentation

JBoss BPEL User Guide

Grid Qian

Version: 1.0.0.trunk

1. JBoss BPEL project Overview
1.1. Key Features of JBoss BPEL project
2. Tasks
2.1. Creating and editing a BPEL project
2.1.1. Creating a BPEL project
2.1.2. Creating a BPEL process
2.1.3. Editing a BPEL process file
2.1.4. Adding Service to WSDL file
2.2. Deploy a JBoss BPEL project to JBoss BPEL Runtime
2.2.1. Creating a deploy.xml file
2.2.2. Creating JBoss BPEL Server
2.3. Creating correlation sets
3. Reference
3.1. Wizards
3.1.1. New BPEL project
3.1.2. New BPEL Process file
3.1.3. New BPEL Deployment Descriptor
3.2. Perspectives
3.2.1. BPEL Perspective
3.3.1. Outline
3.3.2. Palette
3.3.3. Dashboard
3.3.4. Property sections
3.4. Editors
3.4.1. BPEL Designer
3.4.2. BPEL Deployment Descriptor editor
3.5. Preference pages
3.5.1. Editor
3.5.2. Expression editors
3.5.3. WSIL browser
3.6. Dialogs
3.6.1. XPath expression editor (embedded control)
3.6.2. Quick pick (embedded control)
3.6.3. Type selection
3.6.4. Select WSDL property
3.6.5. Create WSDL property
3.6.6. Create WSDL property alias
3.6.7. Cheat sheets
3.7. Icons, buttons and menus
3.7.1. Context menu
4. Troubleshooting
4.1. Error messages
4.2. Warning messages
4.3. Information messages
5. Summary
5.1. Other relevant resources on the topic

JBoss BPEL is based on WS-BPEL 2.0, and provides a way to create, edit, validate and deploy BPEL files to JBoss BPEL runtime. It is based on Eclipse BPEL project.

It improves the Eclipse BPEL project in the following ways:

  • Implements close integration with JBoss BPEL runtime, and adds a new project type for the deployment to the JBoss BPEL runtime.

  • Supports two deployment methods. The first method is to deploy a BPEL project directly to the JBoss BPEL runtime. The second method is to deploy BPEL files in JBoss ESB project to the JBoss BPEL runtime.

  • Enhances the BPEL validator and improves the quality of the Eclipse BPEL editor.

WS-BPEL 2.0 stands for Web Service Business Process Execution Language. Like EAI, BPEL is an XML-based language, but BPEL is more specific and targeted. BPEL is used by developers to join sometimes disparate functions into an integrated process, resulting in a seamless use of the Internet to conduct business transactions ranging from simple money exchanges to complex calculations and asset reallocation.

In this chapter we describe the necessary steps to create a new BPEL project and edit the BPEL files. You can get the example source code from riftsaw/samples/quickstart/hello_world. In this guide we will create a simple echo example, used to respond to a message with a modified version of the request message.

The first step is to create a BPEL project.

Now you should create a BPEL process. You can create it by selecting FileNewOthers...BPEL 2.0New BPEL Process File.

Click the Next button. Enter the following information:

Click the Next button. On the second page, you can customize your WSDL service details. Enter the following information:

Click the Next button. On the third page, you can select a folder for the process file from the projects in your workspace. If a folder is not selected, the default folder HelloWorld/bpelContent will be used. Click the Finish button.


All of your files that are used in your BPEL project must be under the bpelContent folder of a BPEL project. Only in this case these files can be deployed to JBoss server.

This will create a simple BPEL process as shown in the image below.

If the Properties view and Palette view are not opened, you can open the views by right-clicking the BPEL editor and selecting the Show in Properties or Show Palette in Palette view options. Then you should have the view like this:

In the Palette view, you can drag a BPEL element to the BPEL editor and drop it in the place you want.

In the Properties view, you can view the information on every element in the BPEL process. The contents of the Properties view is automatically updated as elements are selected in the BPEL editor. The table below describes the tabs shown in the Properties view:

In order to see how a simple BPEL process works in action, you should do some steps as below:

Correlation sets are used to identify ongoing conversations between a client and the BPEL process. Typically, a correlation is an element in a message that uniquely identifies the conversation between client and service; for example, an Order ID or Social Security Number. This also identifies a specific process instance being managed by the BPEL engine.

In many cases a single element of a message is not enough to make it unique, so correlations can be defined as composites of several fields. Since a conversation can involve many different types of messages. Different correlations will need to be defined for each message type.

To create a correlation for a messaging activity (for example: Invoke, Receive, Reply), select the activity and then click Add on the Correlation Detail property tab. This will display the Select a Property dialog.

You canselect an existing property defined in the WSDL or click New to create a new WSDL property, which will display the Create Message Property dialog.

Enter a name for the new WSDL property and its type. Either an XSD simple type or an XML Schema element.

Next, click the Browse button to select a type. This will display the Type Selection dialog.

Click New in the Aliases section to create a new WSDL property alias.

Select either the Message Type, XSD Simple Type or XML scheme Element radio button and click Browse to select its type. Then click OK.

Described are the user interface controls of BPEL Designer, and how they relate to the OASIS standard. If you are new to BPEL it is recommended that you first become familiar with the concepts surrounding the technology, detailed in ???.

The New BPEL Process File Wizard will create a BPEL process based on one of several templates defined by the wizard. The wizard assumes the new BPEL process is to be created in the curently selected project of the Project Explorer or Navigator view. If a BPEL process of the same name already exists within the project, a warning message will be displayed before any action is performed.

This section describes the Property Sheet tabs that are common to many activities.

This section describes the Property Sheet tabs that are unique to process activities.

This section describes the Details tab and its attributes as they will appear for individual activities. Several activities share common detail elements, but all are presented here for your reference.

The Assign section is probably one of the more complex pages in the BPEL Designer, due to the nature of the BPEL Assign activity. The figure below shows the detail tab of an empty Assign activity with callouts describing each component:

  1. List (initially empty) of assignment operations currently defined.

  2. From combo box for selecting the source element category.

  3. To combo box for selecting the target element category.

  4. Contents and order management buttons. The New button adds a new assignment operation to the list. When clicked, the From and To combo boxes become active and display Variable. These allow you to select the source and categories for target items.

  5. Validate checkbox; when enabled will cause the BPEL engine to validate the data after the assignment. If an error is detected it will cause a fault, which can be caught by a fault handler in the BPEL process.

  6. Ignore Missing Source Data checkbox; When enabled, missing source data is not considered an error (no fault will be generated).

  7. Keep Source Element Name checkbox; when enabled, the complex target variable element names will not be replaced by the source element names if they differ.

The following figure shows the detail tab of an Assign activity which has an XPath expression as the source (From) and a process variable element as the target (To):

A requirement of the BPEL language is that all complex variables must be initialized with valid XML before they are referenced either as a target of an assignment, or in another BPEL activity. The BPEL Designer understands this and, once you have selected the target of an assignment operation, it will ask if you would like to have an XML fragment generated for the target variable:

Unless you are certain that the variable has been initialized during a previous assignment operation or other activity, you should click Yes. The figure below shows the Assign details tab after the initializer has been generated:

Assignment Operation Categories

Additional type selection or data entry widgets will appear below the From and To combo boxes, depending on the source and target item categories selected in the combo boxes. Initially these will be controls for the selection of process variables, since the default combo box selection is Variable. The possible source and target categories are described in the following table:

This section discusses the features of the BPEL Designer. See Section 3.3, “Views” for a detailed discussion of each of these features.

  1. Drawing Canvas: This contains the graphical representation of the BPEL process and is displayed when the Design tab at the bottom of the editor window is selected. The primary mouse click action (default is left mouse button) on any of the activity names activates an in-line editor, allowing you to edit the process name. To finish editing, simply press the ENTER key or change focus by clicking on a different window control.

    The Source tab displays the XML (text) representation of the process. Any changes made in one view are immediately reflected in the other. The default layout of activities is top-to-bottom, but can be changed to horizontal layout from the context menu.

  2. Palette: The primary editing, creation and viewing tools of the BPEL Designer are accessed from the tool Palette.

  3. Dashboard: Provides an overview of the BPEL process.

  4. Property Sheet: When an activity is selected in the drawing canvas, its properties are displayed in the tabbed Properties sheet.

  5. Outline: This panel provides a structural view of the BPEL process.

The BPEL Designer will validate your business process every time it is saved. If an activity is found to be incomplete or incorrectly configured, it will be decorated with an error icon (red circle with an X) as for example the Assign activity below:

Hovering your mouse over this icon will display an error message in a tooltip:

The remainder of this section discusses some basic BPEL concepts and how they relate to the BPEL Designer.

Basic activities are represented on the drawing canvas as rounded rectangles containing an icon and the user-defined name of the activity. The Actions section of the Palette contains all of the basic activities. For example: Assign, Invoke and Receive.

Most basic activities will require some additional configuration. See Section 3.3.4, “Property sections” for more information.

Structured activities can be thought of as containers that can hold one or more activities. The Controls section of the Palette contains all of the structured activities. When you drag and drop one of these onto the drawing canvas, the BPEL Designer will create a basic skeleton of the activity, and assign default properties.

All structured activities will require some additional configuration before they are considered valid. For example, BPEL does not allow an empty Sequence activity. Invalid structured activities will be decorated with an error icon similar to basic activities.

Structured activities can be expanded and collapsed on the drawing canvas by clicking the plus and minus buttons at the bottom of the figure. Illustrated below is a collapsed and expanded Sequence:

The following sections describe the structured activities and how each must be configured to be considered vaid for BPEL.

The Flow activity allows multiple activities to be executed in parallel. All activities or Sequences of activities that are contained in a Flow, are executed (or begun) at the same time by the BPEL engine. A Flow completes when all of its enclosed activities have completed.

Parallel processing is typically used to save time by doing more than one thing at a time and as a result, speed up the process. However, in many situations several tasks can be started at the same time, but one or more tasks may depend on the successful completion of other tasks. This task dependency sequencing is called synchronization and is achieved using Links.

For example, a process that handles purchase orders for material goods needs to:

All of these activities can be started at the same time, however the shipping cost must be finalized before the total order price can be determined, and the invoice can be sent.

To create a Link, right-click on the activity that must be completed first (the activity that is the source of the dependency) and select Add Link from the context menu. Next, move the mouse to the activity in the Flow that depends on this one (the target) and click the left mouse button to create the link.

A Link is identified by a name that must be unique within the Flow. The BPEL Designer generates a reasonable default name, but you can change this in its properties. You can also add a test to the Link that defines the conditions for considering an activity to be complete. For example an activity in a Flow may require two pieces of information, provided by other services, in order to continue. Consider the process Flow shown below:

In this example, the Billing department can begin preparation of a customer invoice, but it needs to know if sufficient stock is on hand to fulfill the order and if an outside vendor needs to provide the additional quantities ordered. The following condition would enable the Link so that execution can continue for the price calculation and customer invoicing:

This process is only partially complete though as it does not consider the number of outside vendors, or if the total quantity being ordered can ever be filled.

Handlers allow a BPEL process to recover from exception conditions. Exception conditions include: a timeout waiting for a response from a partner service, invalid or missing message data, a fault condition returned by a service. There are four types of handlers:

Handlers are defined for the process or for certain activities. To create a new handler right-click an activity and select the desired handler from its context menu. The BPEL Designer will generate a skeleton of the handler within a collapsible window that is attached to the activity. The figure below illustrates all of the different types of handlers in their fully expanded view. The handler windows can be collapsed and expanded by clicking on their respective icon.

The behavior of handlers and the order of exception processing is complex and beyond the scope of this document. Refer to the OASIS WS-BPEL 2.0 specification at http://docs.oasis-open.org/wsbpel/2.0/wsbpel-v2.0.html for more information.

Before a BPEL project can be deployed to the runtime engine, you must create what is called a deployment descriptor. This is simply a manifest file, serialized as XML, that describes all of the BPEL processes and their interfaces to the BPEL engine. The deployment descriptor file must be created in the root folder of your project. See Section 3.1.3, “New BPEL Deployment Descriptor” more information.

The deployment descriptor editor traverses the folder hierarchy in your project and searches for all BPEL files. Each process is then represented in a separate tab in the editor. The figure below shows two processes (HelloWorld and GoodbyeWorld). Each process must be configured before the project can be deployed.

  1. Process selection tabs: Click on these tabs to display the configuration page for each process.

  2. Initial process state: The process can be deployed in either an active, inactive or retired state.

  3. Inbound interfaces selection: Select the WSDL port type that clients will use to invoke this service.

  4. Output interfaces selection: Each invoked service (if any) will require you to select its port type.

  5. Process-level monitoring events: Allow you to select which events are generated by the BPEL engine. This is currently unused but will be used in future for debugging the process.

  6. Scope-level monitoring events: The BPEL engine can be configured to generate monitoring events for each Scope defined in the process.

The only action required to configure a processes is to select the interfaces for inbound and outbound services used by the process; all other settings are optional.

This section lists all of the messages generated by the BPEL Validator. The SA (Static Analysis) column contains hyperlinks to the OASIS WS-BPEL 2.0 specification entry for each validation rule to which the message applies. It is possible that one message is applicable to more than one BPEL element or attribute, therefore all of the SA rules that are relevant are listed for each message.

Refer to the OASIS documentation linked in the SA column for a detailed explanation of the BPEL requirement, and for possible resolutions for the error.


The substitution parameters (for example: {0} and {1}) are placeholders for the BPEL element, attribute or value identified by the Validator.

Table 4.1. Error messages

Message textSA
{1} "{2}" of type "{4}" is not compatible with WSDL message "{3}". 00048 00058 00087
The start activity <{0}> must be the first activity in the process. 00056
Standard fault "{1}" cannot be handled in <{0}> when exitOnStandardFaults is set to yes. 00003
The partner link "{1}" referenced from this <{0}> must have "{2}" defined. 00037
Target scope "{2}" does not exist. 00077
Target {3} "{2}" must have a compensationHandler or a faultHandler. 00078
{1,choice,0#Node|1#Activity} <{0}> must contain at least {5,choice,1#one node|1<{5} nodes} from {3} 02002
The <{1}> node present in this <{0}> has {2,choice,0# unspecified text value (is empty)| 1<="" td=""> 00038
<{3}> can only occur at most {5,choice,1#one time|1<{5} times} in parent {1,choice,0#node|1#activity} <{0}> 02002
<{1}> name "{2}" is already defined in this scope/process. 00018 00023 00044 00064 00068 00069
This <{0}> with name="{1}" was already defined previously 00022
Cannot import type "{1}" from location "{2}" 01234
The XSD type "{1}" of {2} "{3}" in this <{0}> is not a simple XSD type. 00045
This <{0}> uses undefined message part "{1}" in message type "{2}". 00021
There is no "{2}" message that is used by this <{0}> - {3,choice,0#node <{4}> |2#attribute "{4}"} must be omitted. 00047
Solicit-response operation "{4}" in portType "{3}" cannot be used in a BPEL process. 00001
XSD element <{0}> in import {1} conflicts with element of the same name in {2}. 00014
{1,choice,0#Node|1#Activity} <{0}> must have {2} {3,choice,0#node|1#activity|2#attribute} present. 00080 00081 00083 00090
The variable name "{1}" is used as a counter name in <{2}>. 00076
The link "{1}" used as a {0} is not defined in the enclosing flow. 00065
Scope "{1}" cannot have a <{2}> because because it is itself inside an FCT-hander. 00079
The <link> "{1}" has a control cycle where the source "{2}" has the target "{3}" as a preceding activity. 00072
<{0}> cannot be a child of <{1}>; it can only be a child of {2} 02001
The link "{1}" does not have a source. 00066
{0} attribute refers to an unsupported language URI {1} 00004
A catch for fault "{1}" already exist. 00093
Extension "{1}" is not supported by this implementation. 00009
{1,choice,0#Node|1#Activity} <{0}> must specify one {3,choice,0#node|1#activity|2#attribute} {2}. 00081 00090
The attribute {1} must be set to "{2}" on this <{0}> 00057
Attribute "{0}" must not be set on this <{1}> {2,choice,0#node|1#activity}. 00046
{3,choice,0#Node|1#Activity|2#Attribute} {2} must not be specified on {1,choice,0#node|1#activity} <{0}>. 00090
Attribute "{1}" cannot be set because {2} "{3}" is not an element. 00042
Immediately enclosed {0} "{1}" must have a unique name within the outer scope "{3}". 00092
"{1}" is set to "{2}" on this <{0}> {4,choice,0#node|1#activity} but it can only be set to {3} 00017 00032 00046 00090 01001 01010 02003 02004
The {1} of "{2}" is not compatible with {3} of "{4}" - {5} 00043
Message part "{1}" does not exist in message "{2}" 00034 00054
partnerLink "{1}" uses portType "{3}" (via partnerLinkType "{2}") which has an overloaded operation "{4}". 00002
Attribute "{1}" is not set on this <{0}> {2,choice,0#node|1#activity}. 00000 00010 00024 00032 00046 00047 00081 00088 00090 01001 01004 01010 02003 02004
The <{0}> activity named "{1}" must be in a fault, compensate, or termination handlers. 00007 00008
The "{1}" cannot be used on <{0}> that does not have {2} defined. 00017
<{0}> activity "{1}" specifies a portType "{2}", yet this portType does not match the portType derived from "{4}" of partnerLink "{3}" defined in WSDL "{5}" 00005
Isolated scope "{1}" cannot exist within another isolated scope (scope "{3}"). 00091
<{0}> activity "{1}" is trying to use partnerLink "{2}" which does not have a "{3}" defined. 00084
Part "{3}" must be specified on this <{2}> - activity <{1}> requires it. 00050
The targetNamespace {2} of the imported document is not the default namespace. 00012
This <{0}> activity is a start activity and cannot have an onAlarm component. 00062
The import namespace {1} and the imported document target namespace {2} do not match. 00011
The {1} start activities must share at least one correlation. 00057
Either "{1}" or "{2}" attribute is required on this <{0}> 00019 00020
The partner link "{1}" referenced from this <{0}> must have "{2}" defined. 00035 00036
The <{1}> activity named {0} must be in a fault handler. 00006
The part "{1}" is already specified in another <{0}>. 00053
The link "{1}" is not unique - the link "{2}" also makes an identical connection. 00067
The form of <{0}> is not valid (too many variants detected). 00032
The variable name "{0}" contains an illegal period (.) character. 00024
Notification operation "{4}" in portType "{3}" (via partnerLinkType "{2}") cannot be used in a BPEL process. 00001
The link "{1}" does not have a target. 00066
The link "{1}" crosses repeatable boundary on <{2}>. 00070
The "{0}" attribute of this <{1}> is set to "{2}" - it is not a valid NCName. 00000 00024 01004
Either <{1}> *or* attribute "{2}" must be specified on <{0}>. 00051 00052 00055 00059 00063 00085
The {1} "{2}" is not of messageType and a "part" is specified in this <{0}> node. 00034
"{1}" is set to "{3}" on this <{0}> {2,choice,0#|1#activity} but it cannot be resolved (check value of "{1}", imports, WSDLs or XSDs). 00010 00017 00021 00032 00045 00081 00088 00090 02003 02004
Link "{1}" must be outbound only; target activity must be outside of the enclosing <{2}>. 00071
Variable "{0}" must be have either messageType,element, or type defined. 00025
There is no start activity in process "{1}" 00015
{0} "{1}" must have "{2}" and/or "{3}" set. 00016

This document highlights the capabilities of BPEL Tools, as well as providing the steps required to create and configure BPEL process and deployment descriptor files. If you have questions or suggestions concerned both the documentation and tools behavior please visit the JBoss Tools Users forum.