DiggingDeeperBPELGlassFishESB1 2

SUN MICROSYSTEMS
Digging Deeper into BPEL

with GlassFish ESB
Version 1.2
September 3, 2009
Please send feedback to:

Thomas.Barrett@sun.com
- 1 of 99 -
Table of Contents
Objectives ..................................................................................................................................... 4
Environment ................................................................................................................................. 5
Tutorial Format ........................................................................................................................... 5
Scenario
Business Conversation ..................................................................................................... 6
Technical Architecture ...................................................................................................... 8
Project 0: Preparing the Environment

Checking Installation of the soapUI Web Testing Plug-In ............................................. 9
Installing the soapUI NetBeans Plug-in ............................................................................ 9
Downloading HermesJMS ............................................................................................... 11
Installing HermesJMS ........................................................................................................ 11
Configuring HermesJMS ................................................................................................... 12
Project 1: Creating Shared Components

Creating a Project Group .................................................................................................. 18
Exploring Project Groups .................................................................................................. 18
Creating a Common Project ............................................................................................. 20
Building the PO Schema ................................................................................................... 21
Building the Delivery Note Schema .................................................................................. 22
Configuring Custom Encoding for Delivery Notices ....................................................... 24
Testing Decoding of Delivery Notices ............................................................................. 28
Testing Encoding of Delivery Notices .............................................................................. 29
Organizing Your XSDs ....................................................................................................... 30
Creating WSDL for Purchase Orders .............................................................................. 32
Exploring the WSDL for Purchase Orders ...................................................................... 33
Project 2: Building the Supplier Application

Creating the Supplier Project ........................................................................................... 35
Adding References to the Project .................................................................................... 36
Creating WSDL for Delivery Notes .................................................................................. 36
Creating the Supplier BPEL Process .............................................................................. 38
Adding Partner Links ......................................................................................................... 38
Specifying Logic for the Supplier BPEL Process .......................................................... 43
Defining a Loop in a BPEL Process ............................................................................... 45
Creating a Predicate ......................................................................................................... 48
Exploring the ForEach Loop BPEL Syntax ..................................................................... 51
Creating the Supplier Composite Application ................................................................ 53
Deploying the Supplier Composite Application .............................................................. 54
Creating a Web Service Testing Project ......................................................................... 55
Testing the Supplier Application ...................................................................................... 56
Finding the HTTP BC Port ................................................................................................. 57
Moving the DN Destination Directory for Testing ............................................................ 61
- 2 of 99 -
Table of Contents (continued)
Project 3: Developing the Purchaser Application

Creating the Purchaser BPEL Project ............................................................................ 64
Adding References to a Project ..................................................................................... 64
Constructing WSDL to Accept POs with Store Front .................................................... 64
Constructing WSDL to Accept DN from Supplier .......................................................... 66
Constructing WSDL to Send Confirmations to Finance ................................................ 68
Constructing WSDL to Record Processing Errors ........................................................ 69
Building the Purchaser BPEL Process ........................................................................... 70
Adding Partner Links ......................................................................................................... 70
Specifying Logic for the Purchaser BPEL Process ....................................................... 72
Adding Support for Asynchronous Processing ............................................................... 76
Defining a Correlation ....................................................................................................... 86
Testing the Purchaser Application .................................................................................... 89
Viewing Contents of JMS Queues .................................................................................... 95
Summary ........................................................................................................................................ 97
References .....................................................................................................................................99
- 3 of 99 -
Objectives
This tutorial supports knowledge transfer for technology in the Sun-sponsored OpenESB
community. The GlassFish ESB product from Sun provides support for a subset of the
capabilities developed in OpenESB. This material is designed to help you develop skills so
you can start using some of the BPEL-related technical aspects of GlassFish ESB.
This tutorial documents an excellent GlassFish ESB demonstration delivered in the

“GlassFish ESB” lecture section presented at Sun's CEC conference in November 2008. The
demonstration was designed and delivered by Michael Czapski of Sun. I was so impressed
by his work, I eagerly put on my educator/technical writer hat and crafted a tutorial based on
his work.
This tutorial document provides complete, step-by-step exercises for self-study lab time to so
you can create this GlassFish demonstration. In the projects that follow, you will build the
demo from scratch and see insights into both the business case and technical features.
This document is intended to be a stand-alone, hands-on experience. No additional exercise

files are required. With the exception of the required software mentioned in the Environment
section and in Project 0, the exercise is self-contained. After completing all the projects, we
hope this document provides good reference material for later as you revisit key product
features and tool usage steps.
Thanks to Michael Czapski for his excellent demo. He's a real pro. I hope that I have done his
demo justice in this document. You may want to follow Michael's ongoing SOA/BI work at his
blog at http://blogs.sun.com/javacapsfieldtech/.
I appreciate your interest in GlassFish ESB, OpenESB and/or Java CAPS and am very
interested in your feedback on this tutorial.
-- Thomas.Barrett@sun.com
- 4 of 99 -
Environment
You'll need a modern computer with at least 2GB of RAM (the more the merrier) and about
1GB of free disk space. Although the JDK and NetBeans work on a broad range of
operating systems, we'll assume that you are using Windows XP. Since the products are
written in 100% pure Java, you will likely be successful with another operating system, but the
instructions were tested on a Windows XP (SP3) laptop.
You'll need to have JDK 6 and the latest GlassFish ESB installed. Download the latest JDK
from http://java.sun.com/javase/downloads/index.jsp and install it. Then, download and
install the latest builds of Sun's ESB technology from: https://open-
esb.dev.java.net/Downloads.html. This version of the tutorial was last successfully tested with
JDK 6 Update 10 and the GlassFish ESB 2.1.
Tutorial Format
In the pages that follow, you'll see a 3-column format. In the first column, we'll include headings
to act as mileposts to remind you of the purpose of the steps in the section. Hopefully, these
headings will also be helpful later as you use this document as a reference. Each heading is
listed in the table of contents to help you find a section quickly.
In the second column, we've included detailed, step-by-step guidance on the keystrokes and
mouse clicks required to accomplish the tasks. Along the way, you will find illustrations so you
can compare what you see on your screen to what we intend.
In the third column, you'll find narrative (in green) that provides background to the steps listed
in the second column. I call this the “buddy column” since these it contains things I might point
out if we were sitting together at the keyboard. I have included some conceptual topics,
informal advice and some deeper technical tips in the column 3. Having these comments in a
separate column hopefully keeps the second column more concise while providing some
deeper insight into the projects.
In step-by-step exercises, it's easy to get into “mind-numbing” keyboard and mouse clicking
and not understanding what's really going on. Hopefully, the “buddy column” provides some of
the “whys” for all the “whats” and “hows” covered in column 2.
- 5 of 99 -
Scenario
The focus of this tutorial is an abbreviated supply chain. We'll feature OpenESB capabilities that
are packaged in Sun's GlassFish ESB offering. The same OpenESB technology is also a part
of Java CAPS and the Sun ESB Suite. Before we dive into the technical details, let's overview
the overarching business policy and scenario for the projects we'll tackle.
Business We are running an Internet Shop portal where

Conversa- consumers can shop and place orders for goods
tion offered for sale there. The Internet Shop doesn't
store inventory. It relies on third parties to
warehouse and ship the goods.
As soon as the shopping portal receives an order, it

creates a purchase order and sends it to the back-
end purchasing system which, in turn, sends orders
out to one or more suppliers for fulfillment.
Once a supplier receives a purchase order (PO), it

pulls the items from the warehouse bins and
assembles them for shipping. The supplier then
hands over the goods to the shipper to be delivered.
When the goods have been delivered, a delivery
notice (DN) is produced by the shipper and sent to
the supplier.
The supplier then submits the DN to the shopping We will not implement the
portal which forwards it to the purchasing system so shipper system in this
tutorial. We'll just assume
it can match the DN with the initiating PO. As the that as soon as the supplier
DNs and POs are matched, a note is sent to the receives a PO that they will
finance department so that the customer can be return a DN to the purchaser.
billed, the supplier paid and the shipper reimbursed.
- 6 of 99 -
As shown below, we conceive the business By “Internet Shop”, we mean
environment as four distinct entities. The Internet and Internet-based storefront
like Amazon.com.
Shop encompasses the Web Portal, Purchasing
Back Office and the Finance department. The
Supplier is a separate function not under the control
of the Internet Shop. The Shipper is another
independent third-party. On the top, we have the
most important entity of all – the customer.
In this demonstration lab, we will implement the

Back Office and the Supplier functionality. The Back
Office is exposed as a Web service. The Web
Portal uses that endpoint to submit purchase orders.
The Supplier also offers a Web service endpoint that
the Back Office uses to pass purchase orders along
for order fulfillment. The Supplier uses FTP to pass
delivery notes to the Back Office after shipment. To keep things simple in the
The Supplier matches the delivery note with its tutorial, instead of using FTP,
the Supplier will just write
corresponding purchase order and submits a DNs to a file in a specific
request for payment to Finance. directory The Back Office will
pick them up by polling that
directory.
- 7 of 99 -
Technical The technical scenario is a fairly rich one. The two
Architecture key processes, Purchaser and Supplier are
implemented as BPEL processes. They orchestrate
interactions that utilize SOAP, file and JMS. A
typical flow through the system is illustrated below
and includes these processing steps:
● Internet Shop Front submits a purchase order (PO) via SOAP

over HTTP to the Purchaser Process.
● Purchaser Process instantiates a BPEL process for the PO
sends the PO to the Supplier Process via SOAP over HTTP.
● Although it is beyond the scope of our scenario here, the
Supplier Process would arrange picking of items from stock and
Here is where we get a
interfacing with the Shipper to arrange shipment of the order to
chance to do BPEL
the customer. All our Supplier Process will do is write a delivery
correlation. As a DN comes
notice (DN) to a file as a delimited record that indicates that the into the BPEL engine, the
order has been shipped. engine needs to make it
● Purchaser Process constantly polls the directory where DNs are available to the process
written. When it finds one, it transforms the delimited flat file instance that submitted the
record into an XML document and matches it with an existing original PO to the supplier.
business process instance based upon PO#.
● Purchaser Process sends matched PO/DN combinations to a The matching of incoming
JMS queue watched by Finance for further processing. If the message to the right
Purchaser Process does not receive a DN from the Supplier business process instance is
Process within a reasonable time period, it records the problem called correlation.
to a JMS error queue to be researched by purchasing staff.
The BPEL processes run inside the BPEL service

engine (SE). Communications with entities outside
the BPEL SE are handled by three binding
components (BC): HTTP BC, File BC and JMS BC.
- 8 of 99 -
Project 0: Preparing the Environment
Before we can get started building the Purchaser and Supplier processes, we need to make
sure that we have all we need in our GlassFish ESB environment. Let's take a moment to check
that we have all the plug-ins and additional tools we'll use in this tutorial.
Checking In this tutorial, we want you to explore using a Of course, you'll need to start
Installation valuable web service testing plug-in for NetBeans NetBeans first. You may
have a GlassFish ESB
of the created by eviware.com. It has much of the same desktop shortcut or just use
soapUI Web functionality as their soapUI desktop application. It's the Windows Start menu
Testing very popular with web service developers. We need option.
Plug-In to check to see if it is installed in your environment.
You can also execute the
start_netbeans.bat in your
In NetBeans, access the Plugins management C:\GlassFishESBv21
window by using the Tools / Plugin menu bar option. directory.
The Plugins window displays.
Click on the Installed tab to see a list of plug-ins that

are part of your environment:
Click on the Category column heading to sort the list

based on category name. Look for a category called
“Testing Tools” and see if “soapUI Web Service
Testing” is listed in that category.
Installing If you didn't see “soapUI Web Service Testing”

the soapUI listed, perform the following steps to download and
NetBeans install it.
Plug-in
Go to the soapUP download page at
sourceforge.net:
http://sourceforge.net/project/showfiles.php?
group_id=136013
Click on the soapui-netbeans-plugin link and

download the latest version to your desktop.
For me, that version was 3.0:
- 9 of 99 -
After download is complete, select the Downloaded
tab and click the Add Plugins button.
Browse to where you downloaded the plug-in and For me, the download landed
select it. Then, click the Install button: on my Desktop.
Complete the wizard sequence and elect to restart

the IDE when installation is complete.
After restart, use the Tools / Plugins menu bar Let's make sure that the plug-
option to again display the Plugins window. in was installed successfully.
Click on the Installed tab and look for “soapUI Web

Service Testing” in the “Testing Tools” category:
Click the Close button to close the Plugins window.
We now have the add-on plug-in we need for this

tutorial.
- 10 of 99 -
Download- In this tutorial, we will want a convenient way to look Here's what the Hermes
ing at the contents of JMS queues. HermesJMS is an website has to say about
HermesJMS:
HermesJMS open source tool that I think you will find quite “HermesJMS is an extensible
handy. Let's download it. console that helps you interact
with JMS providers making it
easy to browse or search
Go to the Hermes JMS homepage at: queues and topics, copy
http://www.hermesjms.com/confluence/display/HJMS/Home messages around and delete
them. It fully integrates with
JNDI letting you discover
Find the link to the latest stable version and click on administered objects stored,
the link to go to Sourceforge: create JMS sessions from the
connection factories and use
any destinations found.”
Download the Hermes installer to your desktop:
After, selecting the Download link, select the jar file

containing the binary distribution to download it to
your desktop:
Installing When download is complete, open a command This is an all-Java tool, so

installation steps will be
HermesJMS window, make your desktop the current directory similar for all platforms.
and start the installer:
For cut and paste convenience, here is the

You'll find complete
command: installation instructions at:
java -jar hermes-installer-1.13.jar http://www.hermesjms.com/c
onfluence/display/HJMS/Inst
The install wizard appears. I clicked through the alling
steps taking all the defaults.
- 11 of 99 -
Configuring In order to use the tool with our environment, we If you have trouble starting
HermesJMS need to do some configuration. Let's do that now. HermesJMS, make sure your
JAVA_HOME variable is set
appropriately since it is used
Make sure your JAVA_HOME property is set to point in the hermes.bat file that
to your JDK 6 installation. starts the program. My
JAVA_HOME is set to:
C:\Program Files\Java\jdk1.6.0_10
Use Start / All Programs / HermesJMS / Hermes to
start HermesJMS on Windows. You can also start it
by executing the hermes.bat file in the C:\Program
Files\HermesJMS\bin\ directory. The HermesJMS
window displays.
Right-click on sessions and select New / New

session:
The Preferences window appears. Change the

value of the Session field from <new> to: JavaMQ
Click on the Providers Tab at the bottom of the

window.
Right-click in the Providers tab window and select

Add Group.
- 12 of 99 -
For Classpath group name, enter:
JavaMQClasspathGroup
Click OK.
Right-click on the Library control and select Add

JAR(s):
For me, that's

Navigate to your GlassFish ESB imq/lib directory. C:\GlassFishESBv21\glassfis
h\imq\lib
Choose the following jar files: Use Ctrl-click to select all the
● fscontext.jar files at one time before
● imq.jar clicking Open.
● imqadmin.jar
● imqbroker.jar
● imqjmx.jar
● imqutil.jar
● imqxm.jar
● jaxm-api.jar
● jhall.jar
● jms.jar
- 13 of 99 -
Click Open. When prompted, allow Hermes to scan
for connection factories by clicking the Scan button.
When Hermes is done scanning, it lists all the jar

files that will be added to its library:
Click Apply to record your library selections.
Select OK to close the Preferences window. The savvy reader will wonder
in a moment while we are
closing the Preferences
window here just to open it
up again right away. We'll,
that's just how I got things to
work! It seems that
HermesJMS has a few rough
edges. I found that if you
don't follow this sequence,
things just don't work
smoothly. Bear with me.
- 14 of 99 -
We need to configure the JavaMQ session so it can
interact with the GlassFish JMS messaging broker.
Expand the sessions hierarchy, right-click on

JavaMQ and select the Edit option:
The Preferences window appears again.
In the Sessions tab (the default), select

JavaMQClasspathGroup from the Loader pull-down
menu:
Select com.sun.messaging.QueueConnectonFactory
from the Class pull-down menu:
Click the Apply button to record your changes.
Click OK to close the Preferences window.
- 15 of 99 -
We need to configure access to two queues
(qFinanceOut and qErrorOut ) that we'll use in the
tutorial. So, right-click on JavaMQ and select New /
Add queue:
Add a queue with Name: qFinanceOut Press Enter Remember to press Enter
to record the name. Click OK to finish configuring after adding or editing a field.
Otherwise, your data entry
access to the queue. may not “stick.”
Expand the JavaMQ node and see that

qFinanceOut appears:
Perform the same steps to configure access to the

other queue named qErrorOut
- 16 of 99 -
The two sample entries (examples.xml and fix.xml)
still appear in the hierarchy under JavaMQ. Right-
click on each and select Delete to remove them from
the list:
Now that the JavaMQ session is established and

queues of interest are configured, we can interact
with the Java MQ message broker to view
messages in destinations, truncate destinations and
delete all messages. These capabilities will come in
very handy later in the tutorial.
Exit HermesJMS by using the File / Exit sequence.
- 17 of 99 -
Project 1: Creating Shared Components
We will create a number of WSDL documents and XSD schemas that we will want to share
across several projects. A best practice is to create these in a separate “common” project and
then import references into other projects as they are needed. In this project, we will build these
shared artifacts that we'll use later as we build the Supplier and Purchaser processes.
Creating a You are likely to have many different NetBeans

Project projects. It is convenient to collect them into groups
Group so you can easily focus on one subset at a time.
First, in Windows Explorer, create a new directory

named: C:\MyBPELTutorial
Next, use the File / Project Group / New Group

sequence in NetBeans to create a new group by
clicking on the Folder of Projects radio button and, Notice that the Name field is
for Folder, browse to C:\MyBPELTutorial automatically populated once
you have browsed to your
directory.
Click the Create Group button. A new group is
created for you called “MyBPELTutorial.” Widen the Projects panel to
see that the name of the
We will include a number of projects into this group. project group is included in
the label on the Projects
Having them in a group will make it easy for us to panel:
load them into a NetBeans session in one step.
Exploring I didn't find the Project Group feature real intuitive at

Project first. So, let's use the following steps to get the hang
Groups of how it works.
First notice the label of the Projects panel:
This indicates that we are focusing on projects in

MyBPELTutorial project group. We don't have any
projects yet.
Create a project by using the File / New Project /

Java / Java Application menu sequence. Click Next.
- 18 of 99 -
For Project Location, make sure to specify:
C:\MyBPELTutorial
Click Finish to quickly create a dummy project. The

new project appears in the Projects panel.
Repeat the sequence again to create another

dummy project. Your Projects panel will look sorta
like this:
Your project names will

probably be different than
mine.
Let's exercise our Project Group by first closing it.

Use the File / Project Group / (none) sequence to
close the group. The Projects Panel is empty.
Now, open all the projects in your group all at one

time by using the File / Project Group / Without a Project Group, you
MyBPELTutorial sequence. Your two projects are would have had to open and
close each of your projects
opened in NetBeans.
individually.
Clean up you project group by deleting both dummy

projects. To do this, right-click on each on
individually and select Delete. When prompted to
delete the directory elect to do so by toggling on the
check box:
You usually want to “Also

Delete Sources” when you
delete a project. Otherwise,
files hang around on disk and
take up space you could use
for other NetBeans projects.
Delete is destructive. If you

just want to temporarily
When you have deleted both projects, you are back remove a project from your
to an empty MyBPELTutorial project group. NetBeans IDE, just use the
Close option.
- 19 of 99 -
Creating a Sometimes on a project, you find yourself having a
Common collection of common WSDL and XSD documents
Project that you want to manage as a group. One useful
technique is to create a “common” project to house
them. When you need them in another project, you
can import the artifacts in from the common project.
A “common” project can be of any type, but let's Why choose a web
create a web application project to store our WSDL application module if any
and XSD artifacts in this demonstration lab. type will work? Well, there is
no particular reason.
Use the File / New Project / Java Web / Web
Application to create a new project with Project
Name: CommonComponents
Make sure that the Project Location is set to:

C:\MyBPELTutorial and click Next and then, Finish.
The new project appears in the Projects panel:
We have two basic schema documents we need to We'll import the XSD into our
build and store in the common project. One will WSDL document so we'll
specify the structure of a purchase order (PO). The have the data definitions we
need. It is good practice to
other specifies the details for a delivery notice (DN). define your data types in an
XSD instead of embedding
We won't need the index.jsp page, so click on the X the definitions into your
in the index.jsp tab in order to close it: WSDL. That way, you can
reuse the data type
definitions by importing the
XSD into several WSDL
documents.
- 20 of 99 -
Let's create an XSD by right-clicking on the If you have previously
CommonComponents node and using the New / created an XSD in your
NetBeans installation, you'll
Other / XML / XML Schema sequence. The wizard find a New / XML Schema
is invoked. Click Next. option and that's quicker than
New / Other / XML route.
For File Name, enter: PO and click Finish. The new
PO.xsd file appears in the Projects panel under
Source Packages and the XSD editor is opened.
This is a pretty typical
purchase order data
structure. The PO has
Building the We could create this XSD from scratch using the attributes for PONumber,
PO Schema graphical editor, but that would take a bit of time. PODate and Items. There
We could also import it from someplace on your can be an unlimited number
disk. However, we want to keep this tutorial self- of Item entries contained in
Items. For each Item, we
contained with no separate exercise files required. see attributes for
So, the XSD is provided below to copy and paste. ItemNumber and Item
Quantity.
Click on the Source control in the XSD Editor, delete
the current content and copy/paste the following
statements into the XSD:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://MCZ01:14000//PO"
targetNamespace="http://MCZ01:14000//PO"
elementFormDefault="qualified">
<xsd:element name="PO">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="PONumber" type="xsd:integer">
</xsd:element>
<xsd:element name="PODate" type="xsd:string">
</xsd:element>
<xsd:element name="Items">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ItemNumber"
type="xsd:string">
</xsd:element>
<xsd:element name="ItemQuantity"
type="xsd:int">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
- 21 of 99 -
This looks like a pretty typical XML schema After you copy and paste the
definition. Click on the Schema control and use the XML statements and are still
in the Source view, use the
Tree view tool to explore it: Alt-Shift-F feature to reformat
the statements. It makes for
much easier reading of XML.
Note that you can edit the

XSD in any of the three
modes (Source, Schema and
Design). The editor attempts
to keep all modes
synchronized. However,
sometimes, you may need to
close and reopen the XSD
editor in order to synchronize
changes across all modes.
Click on the Validate XML control to make sure the

copy and paste didn't introduce some problems.
Watch the Output panel for errors.
Save All your work.
Building the Let's build the second XML schema definition, this Sometimes you'll see that the
Delivery time for delivery note. Save All control is grayed
out. This indicates that no
Note changes have been made
Schema Again, right-click on the CommonComponents node since that last save.
and use the New / XML Schema option to start the
wizard. You might notice that you
don't need to take the New /
For File Name, enter: DN and click Finish. The Other / XML route to find the
XML Schema option. Since
new XSD node appears in the under Source you have already exercised
Packages node and the XSD editor is opened. it, the option appears earlier
in the menu sequence. You
can use File / New / XML
Schema instead. However,
you can still find it at New /
Other / XML too.
- 22 of 99 -
As before, click on the Source control in the XSD The structure of the DN is
Editor, delete the current content and copy/paste the very similar to that of the PO.
following statements into the XSD Editor:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
xmlns:tns="http://MCZ01:14000//DN"
targetNamespace="http://MCZ01:14000//DN"
elementFormDefault="qualified"
>
<xsd:element name="DN">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="PONumber" type="xsd:integer"/>
<xsd:complexType>
<xsd:sequence>
<xsd:complexType>
<xsd:sequence>
<xsd:element
name="ItemQuantity"
type="xsd:int">
</xsd:element>
<xsd:element
name="ItemNumber"
type="xsd:string">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="DeliveryDate" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
As before, click on the Validate XML control to make

sure the copy and paste was successful. Watch the Again, use Alt-Shift-F to
Output panel for errors. reformat (“pretty print”) the
statements.
Save All your work.
We have quickly created the data type definitions for

the two important data structures: POs and DNs.
We aren't done yet. We need to annotate the DN so
This is called encoding and
that we can perform XML to flat file record and flat decoding.
file record to XML transformations.
- 23 of 99 -
In the Source mode of the XSD editor, review the
structure of a delivery notice:
<xsd:element name="DN">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="PONumber" type="xsd:integer">
</xsd:element>
<xsd:complexType>
<xsd:sequence>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ItemQuantity" type="xsd:int">
</xsd:element>
<xsd:element name="ItemNumber" type="xsd:string">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="DeliveryDate" type="xsd:string">
</xsd:element>
...
You see that each DN identifies the PONumber of its

matching PO. Notice that the Items element
contains an “unbounded” collection of Item elements
and that each Item holds two data elements:
ItemQuantity and ItemNumber. Finally, each DN
has a DeliveryDate element to indicate when the
associated shipment was delivered to the customer.
Configuring We have some more work to do on our DN schema

Custom before we are done with the data definitions in our
Encoding common project. DNs are to be generated by the
for Delivery supplier whenever an order has been shipped. In
Notices our scenario, the supplier is old-fashioned and the
DN is a flat record structure (non-XML).
Individual records are separated by a carriage return

/ line feed pair (\r\n). The individual record fields are
separated by various special characters including |
and ~ and ^.
- 24 of 99 -
Here is a sample DN record:
1001|101^11~102^12~103^13|2008-10-04Y13:45:50.123456+10:00
Here is how the rest of the record is encoded:

• | separates the PO number from the items
• ~ separates one order item from the next
• ^ separates the fields in each item
At the end, there is an invisible \r\n we can't see in a

typical editor like Notepad.
We want to annotate our DN XSD to designate how

the rich XML structure can be transformed into a flat
record structure (and visa versa) as shown above.
This involves encoder/decoder configuration.
To start encoder/decoder configuration, right-click on

the DN.xsd node in the Projects panel and select
Encoding / Apply Custom Encoding. A wizard
window appears. Just click the Process button to The W3C Recommendation
proceed. for XML Schema includes
two facilities for you to add
documentation to an XML
The statements in the Source view have been schema. These include
annotated. comment and annotation
nodes. These nodes can be
Scrutinize the source statements now. Notice that added to any node in a
schema. Comments are
lots of annotation tags like this are sprinkled
included just for humans to
throughout: read. In contrast,
annotations allow for
<xsd:annotation> automated processing under
<xsd:appinfo source="urn:com.sun:encoder"/> control of a style sheet.
</xsd:annotation>
These are skeleton statements that we will embellish

with the Delimeter List editor to specify the four
levels of delimeters in our flat record (\r\n, |, ~ and ^).
Save All your work and move on to recording the

encoding scheme.
- 25 of 99 -
View your XSD in Schema mode and Column view.
Expand the Elements / DN / annotation hierarchy to

find the encoding node.
Right-click on encoding and select Properties to

view the Properties window.
Toggle on the check box for the Top property to

indicate that the DN is the top-level element of our
record structure:
Now, we need to provide details of our record

structure so click on the not specified value in the
Delimeter List property. The Delimiter List Editor
window appears.
We need four levels since we
Click the Add Level button four times to add four have four delimeters for
which to account:
rows to the list editor:
• \r\n denotes the end
of a record
• | marks the
beginning of the PO
number
• ~ separates one
order item from the
next
• ^ separates the
quantity from the
item number
- 26 of 99 -
For each level, click in its row and select the Add
Delimeter button and and fill-in the Bytes cell of each
row as shown below:
Note: Make sure you press Enter after adding each

delimiter. Otherwise, your entry won't be “stick” in
the row.
Click OK to dismiss the Delimeter List Editor.
Back on the Properties window, you see that

Delimiter List now has a value of 4 levels.
Click Close to exit the Properties window.
Save All your work.
Return to the Source view and scroll across the first

annotation for the DN element (your top-level
element). See that the specifications for the four
levels have been added:
- 27 of 99 -
Testing Let's test the encoding/decoding by right-clicking on
Decoding of DN.xsd in the Projects panel and selecting
Delivery Encoding / Test. The Test Encoding window
Notices appears.
You see sections for Decode and Encode. Decode Decode means: delimited
means converting from non-XML to XML while record --to-> XML
Encode converts in the other direction: Encode means: XML --to->
delimited record
To test decoding, we need a non-XML file, a

delimited flat file, to specify as input so we can Make sure you don't add an
extra carriage return/line feed
watch as an XML version is created. So, in
(/r/n) pair. This should be
Notepad, create a new text file with the following just one record in the file.
contents:
1001|101^11~102^12~103^13|2008-10-04T13:45:50.123456+10:00
Name the file DN.txt and store it in your

C:\MyBPELTutorial directory.
Make sure that the Decode radio button is toggled

on.
On the Data File field, browse to your new DN.txt file

and select it.
Click the Process button to start decoding. A

DN.xml file is created in the CommonComponents
project and the file is opened in an editor window.
- 28 of 99 -
Use Alt-Shift-F to reformat the generated XML file
and see that the flat file structure was successfully
decoded into XML:
Save All your work.
Testing Let's test the other direction (encoding) by right-

Encoding of clicking on DN.xsd and selecting Encoding / Test
Delivery again. The Test Encoding window appears.
Notices
Make sure that the Encode radio button is toggled
on this time.
On the XML Source File field, browse to the new This is the directory where
DN.xml file that was just created in the the DN.xml file was just
created by the Decode
C:\MyBPELTutorial\CommonComponents\src\java operation.
directory, select it and click Open.
Click the Process button to start encoding. A

DN.out file is created in the CommonComponents
project and the file is opened in an editor window:
This seems to match the flat file record you saw

earlier. So, it appears that encoding worked too.
- 29 of 99 -
Organizing Our next task is to create the WSDL document that OK. I've got to come clean
Your XSDs defines the contract to send purchase orders in from on something. You may ask:
“Why all this work to
the web storefront. However, before we do that, let's reorganize the PO and DN
reorganize the files under the <default package> documents? Seems like a lot
under Source Packages. of extra work we could skip.”
Let's create two new named packages, one for POs Well, as I tested with
GlassFish ESB v2.1 Release
and one for DNs. Then, we'll move the documents Candidate 2, I couldn't build
to their appropriate packages. the WSDL in the next step
while the related XSD was in
Right-click on Source Packages and select the the <default package>. If I
New / Java Package option. For Package Name, moved it out of that package,
WSDL creation worked as
enter: PO and click Finish. A new package, named expected. So, I added this
PO, now appears under Source Packages. Organizing Your XSDs topic
so you would be successful.
Perform the same steps to create another new Java
package called DN: Hopefully, in a future revision
of the tutorial (and software),
I can remove this section.
Now, let's move the PO.xsd document from the

<default package> to the new PO package. Right-
click on PO.xsd and select Copy.
Right-click on your new PO package node and

select the Paste / Refactor Copy option. The Copy
File – PO window appears.
For New Name, enter: PO and for To Package,

select PO. Click the Refactor button. Expand the
new PO package and see that PO.xsd appears.
Since we move the document, we can delete the

PO.xsd file under <default package>. So, right-click
on it there and select Delete. Confirm the deletion.
- 30 of 99 -
Now, let's move the three DN-related files under the
new DN Java package node.
For each of the three files (DN.out, DN.xml and

DN.xsd), perform the following steps:
1. Right-click under <default package> on the

file to be moved.
2. Select the Copy option
3. Click on the new DN package node and

select the Paste option. For the DN.xsd file,
select the Paste / Refactor Copy option
instead. or New Name, enter: DN and for To
Package, select DN. Click the Refactor
button.
4. Expand the new DN package and see that

your file has been copied.
5. Delete the original file under <default

package> by right-clicking on it and selecting
the Delete option. Confirm that you want to
delete the file.
Here is how the new package organization should

look:
- 31 of 99 -
Creating With our PO and DN-related files organized, let's
WSDL for focus on the purchaser side and create the WSDL
Purchase document that defines the contract to send purchase
Orders orders in from the web storefront.
Right-click on CommonComponents in the Projects

panel and use New / WSDL Document to create a If you don't see New / WSDL
WSDL with a File Name of Common_POIn_SOAP Document, you can go the
New / Other / XML menu
route.
Click on the Concrete WSDL Document radio button
for WSDL Type so we can define the binding type. Every WSDL artifact needs a
name that is unique across
Select SOAP from the Binding drop-down list and the JBI container. The
naming convention being
then, select Document Literal from the Type drop- used here concatenates the
down list. Click Next. project name to description of
the structure type/usage plus
Select One-Way Operation for Operation Type and the protocol being used. So,
change the Message Part Name from part1 to we have “Common_” + POIn
+ “_SOAP” here.
sPOIn
For Element Or Type, click on the ... icon and select

the PO element:
- 32 of 99 -
Click OK to select the PO element. This dismisses
the Select Element or Type window.
Click Next. Then, click Finish to accept the defaults

for Concrete Configuration and to complete the
wizard sequence.
The Common_POIn_SOAP.wsdl node appears in

the Projects panel.
Exploring Let's take a moment to explore the WSDL through

WSDL for the three views supported by the WSDL editor. By You'll find that you will
Purchase default, after you first create a new WSDL, it is develop a favorite view. At
this point, you may be new to
Orders displayed in the WSDL view: flexibility that the editor
provides. So, spending a few
minutes exploring is probably
a good idea.
If you have the Properties

panel open in NetBeans, the
properties are immediately
You can right-click on a node and select the displayed as you click on a
node in the WSDL view.
Properties option to view details.
If you don't see the
Notice within WSDL view, you have two styles: Properties panel, use the
Tree View (the default) and Column View: Window menu bar option and
select Properties.
I call this “Macintosh view” as

it reminds me of a favorite
Try out Column View by clicking the right-most display mode in the OS X
control shown above. Finder where columns keep
being added to the right as
you descend a hierarchy.
- 33 of 99 -
Click on the Partner control to display a more
graphical representation of the WSDL.
Expand the Partner Link Types section by clicking

where the mouse cursor appears below:
The built-in
Help facility
(Help / Help
Contents)
was “helpful”
here helping
me
understand
why Partner
View is neat.
In the Search
tab, I
searched for
“Partner
View” to find
the “About
the Partner
View”
discussion.
By the one-way arrow, you see confirmation that this I learned that this view
features an abstract view of
is a one-way, inbound message exchange. the relationships between
partners. The key is the
Our “common” project is complete. Here is what it partner link type
contains: (<plnk:partnerLinkType>)
section of the WSDL.
Here, we see that one of the

three roles defined in this
partner link type is called
“Common_POIn_SOAPPortT
ypeRole” and it involves an
interaction initiated from “the
outside” into a specific
portType called
“Common_POIn_SOAPPortT
ype.” The display shows a
flow of information into the
portType, but not out. If you
look at the WSDL in the
Source view, you'll see that
this portType, in fact, has just
one operation
We'll now focus on building the Supplier Process (Common_POIn_SOAPOper
application that accepts orders from the purchasing ation) and it specifies only an
system and responds with delivery notices. Along input, not a output.
the way, we'll import artifacts we created in our
“common” project.
- 34 of 99 -
Project 2: Building the Supplier Application
In this project, we'll focus on the Supplier Process shown in the diagram below. It will receive
POs from the Purchaser Process and send back delivery notices (DNs). We have already
created the Common_POIn_SOAP.wsdl to describe the one-way, inbound message that
delivers a PO to the Supplier Process. We'll use that WSDL here.
When the Purchaser receives and processes the PO message, the Supplier must create a DN
that contains item number and quantity information from the PO. Then, it delivers the DN, in a
delimited flat file record, to the file system where the Purchaser can find it. In “real life,” the
Supplier and Purchaser wouldn't have access to the same file system and an FTP transfer would
be required.
Creating the Close all the tabbed windows that may be open from To quickly close all tabbed
Supplier Project 1 work. Also, collapse the windows, right-click on a tab
Project CommonComponents hierarchy in the Projects and select Close All
panel to reduce the clutter. Documents.
Now, we'll build the Supplier's BPEL process that

accepts the PO coming in via SOAP over HTTP and
generates a DN as a delimited flat file record.
Use the File / New Project / SOA / BPEL Module

sequence to create a new BPEL project with a
Project Name of Supplier
Click Finish to add the new skeleton project to the

Projects panel.
- 35 of 99 -
Adding We want to add references to the XSD and the These steps work well for
References WSDL documents we created in our “common” Windows. However, we have
noticed that on other
to the project so we can use them in our new project. platforms, like OpenSolaris,
Project you need to instead copy all
So, right-click on the Referenced Resources node the referenced items from
under Supplier and select Add / Project Resource. CommonComponents
hierarchy and paste them
into the Supplier hierarchy.
In the pop-up window, browse to Just highlight the nodes to
CommonComponents / src / java / DN and click to copy in the Projects panel,
select DN.xsd. Then, click Open to add a copy them to the system
reference to the XSD to your project. buffer, click on the Supplier
project and paste.
Perform the same steps to add a reference to the
PO.xsd file.
Perform similar steps again to add a reference to the

Common_POIn_SOAP.wsdl file.
Expand the References Resources node to see that

the references have been added:
Creating Let's use that DN.xsd reference we just added as we

WSDL for create the interface definition that our Supplier
Delivery Process will use to write DNs to the file system.
Notes
Right-click on Supplier and use the New / WSDL
Document sequence to create a new WSDL with a Watch for trailing spaces in
the File Name. That may
File Name of: Supplier_DNOut_FileEncoded result in a error message
indicating that the name “is
Click on the Concrete WSDL Document radio not a valid NCName.”
button for WSDL Type.
For Binding, select FILE so we will use the File BC

(Binding Component) to process the data.
For Type, select Write to specify a one-way out

message exchange type. Click Next to move on in
the wizard.
- 36 of 99 -
For File Name, enter: DNFromSupplier_%d.txt and %d is a pattern that will
for Path, enter: C:\MyBPELTutorial cause the File BC to insert a
sequential integer in the file
name.
For Payload Processing, select encoded data in the
Message Type drop-down list and click on the ...
icon at the XSD Element/Type field to reference your
DN schema element:
Click OK to dismiss the Select Element Or Type

pop-up window.
In the encoded type field, enter: customencoder-1.0

So, we have a
WSDL that
specifies a one
way message
exchange of DN
data that will be
written in flat file,
delimited record
form via the File
binding
component.
- 37 of 99 -
Click Finish to complete the WSDL definition. The
new WSDL document appears in the Projects panel
hierarchy and it is opened in the editor.
Creating the Let's build our Supplier Process as a BPEL process

Supplier that uses the WSDL document we just created to
BPEL process incoming DN data from a file.
If you are copying and
Process pasting data entry from this
Right-click on the supplier.bpel node in the project document into the NetBeans
panel. This process was automatically created fields, be careful about
when the BPEL module was created. Select trailing spaces. You'll see a
Rename. For New Name, enter bpSupplier and message like: “Target
Namespace should not
select OK. The BPEL process is renamed. Double- contain whitespace.”
click it and a shell of a process appears.
Note: These steps work well

Adding A good place to start when building a new BPEL for Windows. However, we
have noticed that on other
Partner process is to consider how data will come into the platforms, like OpenSolaris,
Links top of the process. In the case of the Supplier you need to have copied all
Process, PO data is received from the Purchaser the referenced items from
Process. Find the Common_POIn_SOAP.wsdl under CommonComponents
Referenced Resources. This WSDL defines the hierarchy and pasted them
into the Supplier hierarchy.
inbound one way message exchange of PO data Just highlight the nodes to
that we are looking for here. copy in the Projects panel,
copy them to the system
Drag CommonComponents/Common_POIn_SOAP.wsdl buffer, click on the Supplier
from under the Referenced Resources node and project and paste. Then,
drag the WSDL from the
drop it onto the left side of the process modeling Supplier project and not from
canvas to create a new partner link: CommonComponents.
- 38 of 99 -
The Create New Partner Link window appears. For
Name, enter: POIn Click OK to dismiss the window.
The partner link is added to the model so we have a

way of getting POs into our BPEL process.
Now, let's add a partner link to allow the model to

output the DNs. Drag and drop
Supplier_DNOut_FileEncoded.wsdl from your
Supplier/Process Files hierarchy onto the right side
of the process modeling canvas.
Double-click on the new partner link's default name

(PartnerLink1) and rename it: DNOut
Thanks to the two partner links, the “channels” are in “Channels” isn't a term that
place for our BPEL process to communicate outside BPEL purists would use, but I
the BPEL engine. found the notion of a partner
link hard to comprehend at
first. I started thinking about
them as a way to “tunnel out”
of the BPEL engine to get to
the outside world. The term
“communication channel”
helped me.
Let's move on to create the logic of the BPEL

process.
- 39 of 99 -
Drag a Receive element and an Assign element It is best to rename elements
from the palette and drop them onto the canvas at added to the model so that
their labels have real
an insertion point just below the Process Start node. business meaning. We are
taking shortcuts here by
We need connect Receive1 with the POIn partner leaving labels like Receive1
line and to define a variable in the POIn partner link and Assign1 stand. So, do
that is to contain the PO data. as we say, not as we are
doing here.
So, click on the pencil edit Edit icon above Receive1

to display the Property Editor window.
In the Partner Link field, select POIn.
Use the Create button to specify vPOIn as the name

of the Input Variable:
Click OK to record the variable name and OK to

close the Property Editor.
The Receive1 element is connected to the POIn

partner link.
- 40 of 99 -
Your model looks like this:
Drag in an Invoke element from the palette and drop

it onto the canvas right under Assign1.
We want to connect Invoke1 to DNOut but let's use

a different UI technique than we did earlier. Click on
the Invoke1's small gray envelop and drag it and
drop it onto the DNOut partner link:
An arc appears showing the Receive1 sees DNOut

as the target.
- 41 of 99 -
Let's define a variable in the DNOut partner link that
is to contain the DN data. So, as you did earlier for
Receive1, click on the pencil Edit edit icon above
Invoke1 to display the Property Editor window.
Use the Create button to specify vDNOut as the

name of the Input Variable: Wait. We have an Input
Variable with a name like
“VDNOut?' What's up with
that? Our convention is to
name the partner link
variables from the
perspective of the BPEL
process. So, our BPEL
process will be sending DN
data out through the partner
link. Following this
convention makes mapping
inputs to outputs less
confusing later.
Click OK and OK to dismiss both the New Input

Variable and Property Editor windows.
Your model looks like this now:
- 42 of 99 -
Specifying We now have PO data coming in as SOAP over
Logic for HTTP through the POIn partner link using the HTTP
the Supplier BC. We are invoking the File BC to write out DN We haven't yet actually
BPEL data via the DNOut partner link. We now need to declared which binding
components will be used as
Process map the PO input data to the outbound DN data. our communication proxies to
Here's where the graphical Mapper is very handy. world outside the BPEL
engine, but you'll see later
Double-click on Assign1 to display the Mapper. that these are the defaults
Make the assignments as shown below by dragging that will be offered as we use
the CASA Editor to configure
from the inputs (on the left) to the outputs (on the our service assembly prior to
right). Map the PONumber from inputs to outputs: deployment.
Notice the All, Output and Input controls above the

input and output areas. They filter out some of the Filtering out variables can
“noise” of showing non-input variables appearing on make for a less confusing
Mapper session. I'd
the left and non-output variables appearing on the advocate making this the
right. Click the Output control over the left panel and default view rather than the
click on the Input control atop the right panel: All default.
- 43 of 99 -
We need to map the DeliveryDate from source to Clicking on the target first is
target. So, click on DeliveryDate in the right (output) important. That click
activates what I call the “blue
panel. mapping lane.” This is the
area where you can add a
Notice that the DeliveryDate “blue mapping lane” is menu element like Current
highlighted: Date & Time and have it
effect the target. If you don't
select the target first and see
the blue mapping lane before
adding a menu element, the
mapping won't work.
Now, click on the Date & Time menu option at the

top of the mapper and choose Current Date & Time.
A Current Date & Time element is added to the blue
mapping lane.
Connect the Current Date & Time element to

DeliveryDate in vDNOut:
Save All your work.
Click on the Design control to return to Design

mode.
- 44 of 99 -
All the red notations you may have seen in the
canvas earlier has disappeared as we have
addressed all unspecified details so far:
Defining a To populate the DN data for output, we need to loop

Loop in a through all the Items in the incoming PO and map
BPEL them to Items in the DN:
Process
Notice that the maximum cardinality for a PO Items

is “unbounded.” This is XSD lingo for a repeating
group of data.
- 45 of 99 -
We will use the BPEL ForEach construct to Here is how the tool's online
designate the loop. help introduces ForEach:
“Repeatedly executes the
activities contained inside a
Drag a ForEach element from the palette and drop it Scope activity N+1 times, where
onto the canvas right below Assign1: N equals the Final Counter
Value minus the Start Counter
Value.”
Note the red X icon indicating an error. Click on it to

see:
So, we need to specify the parameters for the

ForEach. Click the X in the error message area to
close the error message display.
Double-click on the diamond node inside ForEach1

to display the Mapper. Select the All control on both
sides at the top of the Mapper to show all possible
variables that could be mapped
Here is where we condition the loop control settings:

Start Value, Final Value and Completion Condition.
- 46 of 99 -
Click on Start Value at the right to display the blue Unlike in Java, array
mapping lane. We want to start our loop at 1 so processing begins at element
1 instead of 0 in BPEL.
click on the Number menu item and select Numeric
Literal. A Numeric Literal element is added to the
mapping lane.
Double-click on the Numeric Literal and change the

default value (0) to 1. Then, connect it to Start
Value:
Click on Final Value at the right to display its blue

mapping lane.
We want to stop the loop when we have iterated the

same number of times as there are Item structures
in the incoming PO. Click the Node menu item and
select Count from the options. A Count element is
added to the blue mapping lane.
Connect the Count element to

vPOIn/sPOIn/Items/Item and then connect the result
(Number) to Final Value:
Notice the small asterisk (cog wheel) beside Item on The asterisk indicates a
the left side. This indicates that it is a repeating repeating group (think array).
group of data.
- 47 of 99 -
Save All your work.
Click on the Design control to return to the Design

view.
Add an Assign node inside the ForEach1 loop: This is where we will do
mapping of the repeating
Item data.
Again, shame on us for not

renaming Assign2 to
something more descriptive.
Double-click on the Assign2 element inside the loop.

The Mapper displays so we can map data from the
PO coming in to the DN structures we will send out.
Creating a We'll need to define predicates to produce an The Help / Help Contents
indexed list of Item data that over which we can menu bar option was helpful
Predicate for the term “predicate.” I
loop. Getting access to an element in a repeating learned the following:
group is really a “side effect.” Predicates are – A predicate applies a
comparators expressed as a condition. They do condition to a node that
filtering and provide a subset of records to be can have multiple values.
processed in subsequent logic. – The result of a predicate
application is a subset of
data that satisfies the
Expand the vDNOut structure on the input (right) condition.
side of the Mapper to find the Item node. Click on – Once I create predicate, I
Item to display its blue mapping lane. Then right- can use it in an
click on Item and select Add Predicate: assignment to map
sources to destinations.
– Predicates are
constructed with XPath
functions.
You'll see that we won't really

specify a condition in our
predicate here. We'll just
enjoy the side effect that it
allows us to reference a
repeating group of data via
an index like we access
elements in an array.
Check out the online help!

The Predicate Editor window appears.
- 48 of 99 -
Perform the mapping as shown below to specify the Not much of a “condition,”
predicate: right? Again, we are using a
predicate here for its “side
effect” of giving us an
indexed data structure that
we can iterate over.
Notice the “Item

[ForEach1Counter]”
additions. This is the side
effect of our predicate. It
gives us access to individual
elements in the repeating
group.
Be careful mapping. It's easy

to map ItemNumber to
ItemQuantity !
Click Ok to close the Predicate Editor window.
Notice that the indexed Item structure for output now

appears below Item:
We need to do the same thing on the output (left

side) in order to get an indexed data structure for the
inputs we are mapping.
- 49 of 99 -
So, just like you did above, add a predicate to Item Click on Item to display its
(under sPOIn / Items) on the left side. blue mapping lane. Then
right-click on Item and select
Add Predicate.
In the Predicate Editor, perform the same
ForEach1Counter --> Predicate mapping:
Click Ok to close the the Predicate Editor window.
Now, back in the original Mapper, perform the

following mappings:
Be careful. Make sure you

are mapping under the Item
Save All your work. with the index reference.
Also, not that ItemNumber is
first in the output side but
second in the input side.
- 50 of 99 -
Exploring Click on the Source control and scroll down to see
the ForEach the BPEL statements that were created as you built
Loop BPEL the ForEach loop using the graphical editor. You'll
Syntax see that we have the intended side effect of indexed
references to the repeating group of Item data:
Notice that the $ForEach1Counter variable is the The indexing syntax looks a
index on the copy statements. bit like that for processing
Java arrays: Item[index]
- 51 of 99 -
Validate the XML to make sure it is correct. Validate XML:
Save All your work.

You may need to widen the
Let's check the Supplier BPEL module for errors and BPEL Editor panel to find this
package the module for deployment by right-clicking icon on the right-side of the
on Supplier and selecting Build. panel.
Watch for the “BUILD SUCCESSFUL” message

appear in the Output panel.
Here is the completed BPEL Supplier Process:
We are ready for testing. However, before we can

do that, we need to assemble our module into a
composite application and deploy it.
- 52 of 99 -
Creating the To deploy any JBI module, you have to include it in Troubleshooting Tip:
Supplier a composite application. So, create a new Something odd happened to
me that you might encounter
Composite composite application by selecting File / New Project sometime. I tried to select
Application / SOA / Composite Application Build, but it was grayed out. I
was puzzled. I looked in the
The wizard appears. Click Next. bottom right of the NetBeans
window and saw a red icon. I
clicked on it and learned that
For Project Name, enter: SupplierCA there had been error
somewhere inside the IDE. I
Click Finish. The CASA Editor canvas appears and exited NetBeans and
you see that your SupplierCA has been added to restarted it. Then, the Build
the Projects panel. option was available.
This naming convention of

Drag the Supplier BPEL module project into the JBI appending “CA” to the end of
Modules section of the open CASA Editor canvas. the module name makes the
projects sort together in the
Click on the Build Project tool at the top of the CASA Projects panel. It helps to
make it easier to find the
Editor canvas to assemble the composite modules brought together
application. into the composite
application.
The module is analyzed and the CASA Editor
displays the appropriate WSDL Ports connected to Build Project tool:
the module:
If you double-click on
supplier node inside the
BPEL module (see above),
the BPEL modeling canvas
will appear so it's easy to
interrogate the contents of a
JBI module.
You can also access

properties for each WSDL
port to find out what JBI
component (SE or BC) will be
hosting the module.
- 53 of 99 -
Save All your work.
The CASA Editor allows us to reconfigure the

concrete bindings to “wire up” our modules to
different data sources. We are happy with the
decisions we made when we created our WSDL
documents, so let's just deploy the service
assembly.
Deploying Click on the Deploy Project tool at the top of the

the Supplier CASA Editor panel to deploy the service assembly
Composite to the GlassFish server.
Application
As always, watch the Output panel for the “BUILD If your GlassFish application
SUCCESSFUL” messaging indicating that a server instance isn't up and
running, it will be started for
celebration is in order. you when you click the
Deploy Project tool. Watch
Let's take a quick peek at the status of the runtime the Output panel for play-by-
environment. In the Services panel, expand the play.
hierarchies as shown below
You can verify that the sun-
See that our SupplierCA was deployed as a JBI bpel-engine will host the
service assembly that is made up of three service SupplierCA-Supplier service
units. Two of the service units are associated with unit by right-clicking on the
BCs installed in the JBI environment. The other service unit and selecting
service unit, SupplierCA-Supplier will execute in the Properties. Look for the
Target Name property:
BPEL SE.
- 54 of 99 -
Creating a The soapUI web service testing tool is a very
Web Service valuable addition to your NetBeans environment. If
Testing you aren't sure you have installed it, go to the We can't use the built-in web
Project Project 0 section and follow the steps there. We'll service tester in NetBeans as
our input is a rich XML data
use it now to exercise the bpSupplier BPEL process structure. The soapUI plug-
we just built. in makes it easy to test with
rich structures like a
In the Projects panel, create a new testing project by repeating group of items.
using the File / New Project / Java EE / Web Service
Testing Project sequence. Click Next to advance
the New Project wizard.
“WSTP” stands for “web
For Project Name, enter: SupplierWSTP service testing project.”
For Initial WSDL (URL/file), browse to and select The initial WSDL defines the
C:\MyBPELTutorial\CommonComponents\src\java\C structure of the message that
ommon_POIn_SOAP.wsdl, select it and click Open. will be sent to the Web
service endpoint you will
specify to soapUI a bit later.
Click Finish to end the New Project wizard. The
Import WSDL window appears announcing that the
wizard has “Successfully imported 1 Interfaces from
WSDL.” Click OK.
The new project is added to the Projects panel.

Expand the SupplierWSTP hierarchy.
Let's add a new request we'll submit as input in our

test. Completely expand the hierarchy and right-
click on the Common_POIn_SOAPOperation node
and select the New request option.
For name, take the default (Request 1) and select

OK. If prompted to create optional elements, select
Yes. The hierarchy is updated to show Request 1:
Request 1 displays in the XML editor.
- 55 of 99 -
Testing the We need to edit Request 1 so it contains some data
Supplier that tests the supplier web service's ability to accept
Application a PO and generate a DN.
Edit Request 1 so it appears like this:.
For copy and paste convenience, here are the XML

statements. Just replace all existing XML statement
with these:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:po="http://MCZ01:14000//PO">
<soapenv:Header/>
<soapenv:Body>
<po:PO>
<po:PONumber>1001</po:PONumber>
<po:PODate>2008-10-10T12:12:13.123456</po:PODate>
<po:Items>

<po:Item>
<po:ItemNumber>101</po:ItemNumber>
<po:ItemQuantity>11</po:ItemQuantity>
</po:Item>
<po:Item>
</po:Item>
<po:Item>
</po:Item>
</po:Items>
</po:PO>
</soapenv:Body>
</soapenv:Envelope>
- 56 of 99 -
Before we send this XML to the supplier's web
service endpoint, we need to address the default
contents of the target URL field:
See that ${HttpDefaultPort}

placeholder?
NetBeans uses variables like ${HttpDefaultPort}
Finding the
which are resolved at runtime, but the soapUI plug-
HTTP BC
in doesn't understand these variables. It needs an
Port
explicit port number. You might be tempted to just
insert port number where the GlassFish HTTP
listener is watching for requests. However, we are
running in a JBI framework and HTTP requests for
our Supplier application are processed by the HTTP
BC. It “listens” on its own port. To find out which
port:
1. Access Services panel
2. Expand the GlassFish V2 hierarchy as shown
below to view the Binding Components
3. Right-click on sun-http-binding and select
Properties
4. Look for the Default HTTP Port Number:
The default port is 9080.
- 57 of 99 -
Expand the drop-down list at the top of the soapUI
testing window and select the Edit Current option:
A pop-up window displays. Replace $

{HttpDefaultPort} by inserting your HTTP port
number:
Click OK.
Now we can submit our XML request to the Supplier

web service endpoint. Click on the Submit request
tool to send the request:
You see at the bottom of the soapUI panel that the

response time was something like 981ms, but no
bytes were returned:
Hummm ... why no output? That's OK! March on, it

will become crystal clear.
- 58 of 99 -
Click in the right-side, response panel and see that it
is empty. Click on the Raw tab in the response
panel and see that the request was received
successfully:
“Content-Length:0” indicates that there was no

response body. The HTTP 202 status code
(“Accepted”) isn't an error. What happened? Well,
remember that this is a one-way service invocation.
The supplier application is to respond by placing a
file on the file system. There is no SOAP response
expected! Reviewing the assembly in CASA Editor
might be valuable:
We just exercised the SOAP WSDL port. Let's see if

the supplier BPEL process utilized the FILE WSDL
port as we anticipated.
- 59 of 99 -
In Supplier_DNOut_FileEncoded.wsdl in the
common project, you specified the file name and the
directory where the File BC should write:
So, use Windows Explorer to look inside your

C:\MyBPELTutorial directory. You should find a file
with a name that matches the “DNFromSupplier_
%d.txt” pattern. Open it and look inside:
We see that the web service endpoint received the

PO data, transformed it into a flat file DN record and
wrote it to the file system. That's just what we
expected. Congratulations!
- 60 of 99 -
Moving the Before we declare victory on the Supplier side of our
DN Internet store front application, let's tweak where the
Destination “DNFromSupplier_%d.txt” file is to be written.
Directory
for Testing Why? Here is the situation. When we create the
purchasing application, it will send the web service
request (that we just sent using soapUI) and, then, it
will constantly watch the file system directory to look
for delivery notices.
We want some control in our testing of how the

purchasing side and supplier side work together. If
we have the supplier write DNs to the directory
where the purchaser is looking, the file would be
picked up immediately and we wouldn't get to step
through the interaction of the two systems manually.
So, we'll “tell” the supplier system's File BC to write Of course, before going “into
the DN into a staging directory. Then, during production,” we'd undo the
change so that the interaction
testing, we will manually move it to between purchaser and
C:\MyBPELTutorial to let the purchaser find it. That supplier happens
way we have control over testing. instantaneously.
Find Supplier_DNOut_FileEncoded.wsdl under

Don't worry that the
Supplier / Process Files. Double-click on it to fromSupplier directory
display it in the WSDL Editor. doesn't exist yet. It will be
created at runtime as
Change the file:address property value to needed.
C:\MyBPELTutorial\fromSupplier as shown below:
Save All your work.
- 61 of 99 -
Redeploy your SupplierCA application by right- Notice that we didn't first
clicking on it and selecting Deploy. Build the Supplier and then
Build SupplierCA before
selecting Deploy. The Ant
Return to the Web Service Testing panel and scripts that drive deployment
resubmit your Request1. Check in the comprehend the
C:\MyBPELTutorial\fromSupplier directory to see dependencies between
that a DNFromSupplier_0.txt file has been created deploy and build. If modules
need to be built before the
there. composite application is
deployed, the Ant scripts take
We now have the File BC writing to a directory that care of this automatically.
our purchaser application won't be able to “see.” So,
that way we can manually move the file and watch
the purchasing application process it.
The Supplier Process is all finished. Now, let's turn

our attention to the Purchaser Process side of our
business scenario.
- 62 of 99 -
Project 3: Developing the Purchaser Application
In the last project, we completed the Supplier Process. It performs two chores. First, it accepts
POs as incoming SOAP payloads. Second, it creates a DN as a delimited flat file record and
writes it to the file system. The illustration below should help remind you where we've been and
where we're going.
In Project 3, we'll focus our attention on the Purchaser Process that will do four chores. First, the
it accepts SOAP requests from the Internet Shop Front and produces a PO. Second, it sends
the PO to the Supplier Process as SOAP over HTTP. Third, it looks in the file system for the DN
record from the Supplier Process. This DN acts as an acknowledgement of PO receipt and
processing. Fourth, the Purchaser Process sends notification to Finance via a JMS message.
As with the Supplier Process, the Purchaser Process will be orchestrated by a BPEL process.
This BPEL process will be more sophisticated and interesting than the last one we built. The
most interesting parts are: asynchronous events and correlation. When the Purchaser Process
is first invoked for a sale made at the Internet Shop Front, it instantiates the business process for
the PO data being received. That business process instance sends the PO to Supplier Process.
Then, it just sits there. This isn't a blocking call to the Supplier Process as the purchaser process
instance can continue processing. In other workds, it is an asynchronous call, not a synchronous
one.
While that purchaser process instance is just sitting there waiting, a bunch of new POs can be
delivered from the Internet Shop Front each instantiating its own business process instance.
Then, when the Supplier Process finally gets around to delivering the DN back to the Purchaser
Process for a particular PO, the Purchaser Process needs to determine to which business
process instance that particular DN applies. This is called “correlation.” The combination of
asynchronous processing and correlation shows off one of the most important features of a
BPEL engine – support for long-lived business transactions.
- 63 of 99 -
Let's tidy things up a bit. Close down all open To quickly close down all the
tabbed windows and collapse all projects in the tabbed windows, just click on
one of the tabs and select the
Projects panel. Close All Documents option.
Creating the Use the File / New Project / SOA / BPEL Module
Purchaser sequence to create a new BPEL project with Project
BPEL Name: Purchaser
Project
Click Finish to add the skeleton project to the
Projects panel.
Adding As we did in the last project, we want to add Note: These steps to add
References references to the two XSDs we created in our references work well for
to a Project “common” project so we can build WSDLs in our Windows. However, we have
new project that reference them. We also want to noticed that on other
platforms, like OpenSolaris,
add a reference to the WSDL file as we'll will need it you need to copy all the
in our BPEL process. So, right-click on the referenced items from
Referenced Resources node under the new CommonComponents
Purchaser node and select Add / Project Resource. hierarchy and paste them
into the Purchaser hierarchy.
Just highlight the nodes to
In the pop-up window, browse to copy in the Projects panel,
CommonComponents / src / java / DN and click to copy them to the system
select DN.xsd. Then, click Open to add a buffer, click on the
reference to the XSD to your project. Purchaser project and paste.
Perform the same steps to add a reference to the

PO.xsd file from the PO package. Then, perform
similar steps again to add a reference to the
Common_POIn_SOAP.wsdl file.
Expand the References Resources node to see that

the three references have been added.
Construct- Let's use that PO.xsd reference we just added as we

ing WSDL to create the interface definition that our Purchaser
Accept POs Process will use to receive POs from the Internet
with Store Store Front via SOAP over HTTP.
Front
Right-click on Purchaser and use the New / WSDL
Document sequence to create a new WSDL with a
File Name of: Purchaser_POIn_SOAP
Click on the Concrete WSDL Document radio button

for WSDL Type.
- 64 of 99 -
For Binding, select SOAP (the default) so we will
use the HTTP BC to process the data.
For Type, select Document Literal and click Next to

advance the wizard.
For Operation Type, select One-Way Operation to

specify the message exchange pattern (MEP).
For Input Message Part Name, change “part1” to

sPOIn To access the Select
Element Or Type window,
click on the ... icon in the
For Element Type, select PO from the PO.xsd: Element Or Type column
Click OK and then, click Next to continue with the

wizard.
Click Finish to accept the defaults for Concrete

Configuration. The WSDL is created, appears in the
Projects panel and is opened in the WSDL Editor.
Save All your work.
Our WSDL is complete. It defines how to accept If the Save All tool at the top
of the window is grayed out,
POs via SOAP over HTTP. there is nothing that needs to
be saved right now.
- 65 of 99 -
Construct- Let's turn our attention to the WSDL that defines the
ing WSDL to interface to allow our Purchaser Process to receive
Accept DN DNs from the Supplier Process via the file system.
from
Supplier Right-click on Purchaser and use the New / WSDL
File Name of: Purchaser_DNIn_FileEncoded
Click on the Concrete WSDL Document radio

For Binding, select FILE so we will use the File BC

to process the data.
For Type, select the Poll (Default) option.

“Poll” means that will will
want the File binding
Click Next. component to continuous
interrogate the files system
For File Name, enter: DNFromSupplier_%d.txt for the presence of our file.
For Polling Directory, enter: C:\MyBPELTutorial “%” indicates that the file
name is a pattern and that, in
place of the “%”, we expect
For Message Type, select encoded data from the to see a number. So,
drop-down menu to indicate that the DN data DNFromSupplier_1.txt might
coming in is from a flat file delimited record. be a file that we'll pickup.
You could enter

At the XSD Element/Type, click on the ... icon and /MyBPELTutorial if C were
browse to DN in the DN.xsd and select it: your default drive. Of course,
Windows likes backward-
leaning slashes and other
platforms like Solaris and
Linux favor forward-leaning
slashes. You can use either
in the tooling and the runtime
does the right thing based
upon what operation system
it is using.
To start browsing to select

your DN.xsd, click on this
control next to the encoded
data field:
Click OK.
- 66 of 99 -
In the Encoded type field, enter: customencoder-1.0
Click Finish.
This completes the WSDL definition that describes Much of the data in legacy
systems are in encoded
how to get flat file delimited DN records from the file format. So, the main role of
system and convert them to XML documents. encoders is to bridge the gulf
between legacy and modern
systems.
To learn more about

encoders, see:
http://wiki.open-
esb.java.net/Wiki.jsp?
page=Encoders.
- 67 of 99 -
After the Purchasing Process has “matched up” a
PO from the Internet Shop Front (store front) with a
DN from the Supplier Process, it needs to send a
confirmation to Finance. Now, let's create WSDL
that defines this interface between the Purchasing
Process and Finance.
Construct- Right-click on Purchaser and use the New / WSDL

ing WSDL to Document sequence to create a new WSDL with a
Send File Name of: Purchaser_FinanceOut_JMS
Confirm-
ations to Click on the Concrete WSDL Document radio
Finance button for WSDL Type.
For Binding, select JMS so we will use the JMS BC

to process the data.
“Send” indicates that this will
For Type, select Send. be an outbound interaction
from the perspective of the
Click Next so, in the next wizard step, we can BPEL process we will build.
specify the details for the JMS connection and
payload.
admin/admin are the default
For User Name, enter: admin credentials for a client to
access the JMS broker. We'll
For Password: enter: admin use that.
There are several types of

For Payload Processing, make sure that text JMS messages. We'll just
(default) is selected from the drop-down list. plop a text message on the
queue.
Click Next to move on to specify the name of the
queue where the text messages are to be sent. This is the queue that
Finance will check to learn
what work the Purchaser
For Destination, enter: qFinanceOut and make sure Process has forwarded
that the Destination Type is set to Queue. along.
Toggle on the Non-Persistence radio button. Toggling on Non-Persistence

is an awkward way of saying
that you don't want a
Click Finish. persistent JMS queue. This
means that your JMS
We now have a finished WSDL interface that defines messages aren't persisted to
the outbound contract between the Purchaser a database. So, as you stop
and restart GlassFish, your
Process and a JMS queue named qFinanceOut. JMS queues and topic will be
This is where confirmation notices will be dropped cleared. The default JMS
for Finance to pick up. broker (Java MQ) runs in-
process with the application
server.
- 68 of 99 -
Construct- Things can conceivably go wrong and we have to be
ing WSDL to able to handle errors. In our scenario, if the
Record Purchaser Process has sent a PO to the Supplier
Processing Process and has not received a corresponding DN
Errors back within a reasonable time period, this is a
processing error. To record the error, we are to
write a message to an error queue that can be
investigated by purchasing staff. So, let's create the
WSDL that defines the interface between the
Purchasing Process and that error queue.
Right-click on Purchaser and use the New / WSDL

File Name of: Purchaser_ErrorOut_JMS
Click on the Concrete WSDL Document radio

For Binding, again select JMS so we will use the

JMS BC to process the data.
For Type, again select Send.
Click Next so, in the next wizard step, we need to

again specify the details for the JMS connection and
payload.
For User Name, enter: admin
For Password: enter: admin
For Payload Processing, make sure that text is

selected from the drop-down list.
Click Next to move on to specify the name of the

queue where the error messages are to be sent. This is the queue that
Finance will check to learn
what errors have occurred in
For Destination, enter: qErrorOut and make sure the passing data the Purchaser
Destination Type is set to Queue. Process to Finance.
Again, toggle on the Non-Persistence radio button

and click Finish.
Now we have created a WSDL that defines the

outbound interface between the Purchasing Process
and a JMS queue named qErrorOut.
- 69 of 99 -
These WSDL interface definitions are ready to be
the basis for partner links in our purchasing BPEL
process:
Building the See that the purchaser.bpel process was created

Purchaser when the BPEL module was created. Let's rename
BPEL it by right-clicking on purchaser.bpel and selecting
Process Rename.
For New Name, enter: bpPurchaser and click Finish.

Double-click on bpPurchaser.bpel and a skeleton
business process appears in the Design canvas.
Adding Let's add all our partner links to the process first so
Partner we have our “channels” in place to communicate
Links with the world outside the BPEL engine.
Establish the channel for the incoming purchase

orders by dragging Purchaser_POIn_SOAP.wsdl
onto the left side of the model.
- 70 of 99 -
A new partner link is added to the canvas. Rename
it by double-clicking on the default name
(PartnerLink1) and entering POIn
Establish the channel for the incoming delivery

notices by also dragging
Purchaser_DNIn_FileEncoded.wsdl onto the left
side of the model below POIn.
A new partner link is added to the canvas. Rename

this new partner link: DNIn
Let's focus on the outbound (right) side of the model

to establish the outbound channels. The first one
we'll establish is the channel to send POs out.
Drag the Common_POIn_SOAP.wsdl from the

Referenced Resources in your Purchaser project
and drop it on the right side of the model:
The Create New Partner Link window displays.

Rename the partner link (from PartnerLink1) to
POOut and click OK to dismiss the window.
Next, create the channel out to Finance by dragging

the Purchaser_FinanceOut_JMS.wsdl to the right
side of the model right under POOut.
Rename this new partner link to: FinanceOut
- 71 of 99 -
And finally, create the channel out for Errors by
dragging the Purchaser_ErrorOut_JMS.wsdl to the
right side of the model and dropping it under
FinanceOut.
Rename this new partnerLink to ErrorOut
Save All your work.
Your model looks like this:
Specifying All the partner links are in place. Now, let's add the
Logic for Receive node so PO information can come into our
the business process from the Internet Store Front.
Purchaser Drag and drop a Receive element from the palette
BPEL into the model. Receive1 is added to the canvas:
Process
- 72 of 99 -
Connect Receive1 to the POIn partner link by finding
the little gray envelope decoration on Receive1,
clicking on it and dragging it to the envelope on
POIn:
Click on the pencil edit icon above Receive1 to

specify an input variable that will pass in PO data to
Receive1:
In “real life,” you

would rename
“Receive1” to
something more
meaningful like
“ReceivePO”.
Admittedly, we
are being a bit
lazy here by just
staying with the
default element
names.
As shown above, use the Create button to create the

input variable called: vPOIn
Click OK to dismiss the New Input Variable window

and then, click OK again to dismiss the Property
Editor window.
- 73 of 99 -
Drag in an Invoke element from the palette and drop
it below Receive1.
Click on Invoke1 to find the
As you connected an element to a partner link little gray envelope icon.
above, now connect Invoke1 to POOut so the PO is Drag this little envelope and
sent along to the Supplier. drop it onto the big envelope
of the POOut partner link.
And as before, click on the pencil icon, this time for
Invoke1 and specify an input variable named:
vPOOut
We need to map PO data that came into our model

via POIn for the Internet Storefront. That data needs
to be mapped to the Invoke1 that is sending data out
to the Supplier process via POOut.
So, drag an Assign element from the palette onto

the canvas right before Invoke1:
- 74 of 99 -
Double-click on Assign1 to display the Mapper.
Map outputs (on the left) to inputs (on the right):

Notice that we mapped the
non-leaf nodes of the two
structures (vPOIn/sPOIn to
vPOOut/sPOIn). We could
have mapped the individually
items like PONumber, but
since the structures are the
same and because we
wanted to copy all the data,
we mapped at the sPOIn
level.
Note in the screen shot that I

clicked the Output control on
the left and Input control on
the right to filter out
extraneous variables from
the list of possible mappings.
Save All your work. This makes it easier to find
the sources (on the right) and
targets (on the left) I'm
Click on the Design control to return to the Design looking to map.
mode where the graphical process model is
displayed.
The next part of the model will handle the

According to the online help,
asynchronous communication with the Supplier Pick blocks the process and
Process. Our Purchaser Process will send a PO to waits until one of the
the Supplier. Then, the Supplier will create a specified events occurs. After
corresponding DN for it. That could take 1 second the event occurs, the activity
associated with that event is
or 10 seconds or 10 days.
performed. Occurrence of
events is mutually exclusive.
Our Purchaser doesn't wait around and can continue So, if more than one of the
processing. However, when that DN does show up, events occurs, then the
the Purchaser needs to bring it in to the appropriate selection of the activity to
perform depends on which
business process instance (the one producing the
event occurred first.
initiating PO) and continue processing. We'll do this
asynchronous processing and correlation of the right Pick is used to allow one of a
instance via a BPEL Pick element. set of alternative events to
take place. This might
include a receive of a
correlated message or a time
out in the case of our
process. Correlation can be
configured on any "receive"
or "invoke" activity. In our
case, it is configured on the
On Message "receive"
activity.
- 75 of 99 -
Adding Drag a Pick element from the palette and drop it
Support for onto the canvas and drop it right after Invoke1:
Asynchro-
nous
Processing
Notice that my screen shot

shows the palette as a
separate window instead of a
docked panel. To undock a
window, right-click on its top
border and select the
Undock Window option:
Our Pick shouldn't wait forever for a matching DN to

be sent from the Supplier Process, so we'll add an
alternative branch as a time out path.
To redock windows, use the
Window / Reset Windows
main menu bar option.
Click on the Add on Alarm control to add the timeout
path inside Pick1:
- 76 of 99 -
The OnMessage path has a receive activity that can
bring data in via a partner link channel. We need to
connect it to the DNIn partner link so that the
delivery notices can come into our process
asynchronously.
As before, click on the receive and find the little gray

decoration:
Drag from there and drop on the DNIn partner link to

establish the “channel:”
The “receive” element (labeled “Message”) for the

Pick needs to have it's input variable created.
- 77 of 99 -
Double-click on the Message receive element and Message receive element:
create an Input Variable named: vDNIn
Along the OnMessage path, we need an Assign and

Invoke sequence. The invoke will send out a
confirmation to Finance via the FinanceOut partner
link. The assign will map in the data that the invoke
needs to communicate with Finance.
So, drag and drop an Assign and an Invoke below

the Message element along the OnMessage path:
- 78 of 99 -
Connect Invoke2 to FinanceOut: You know the drill. Find the
little gray envelope icon on
the Invoke, drag it and drop it
on the big envelope on the
partner link.
As before, we need a variable to carry the data that

is being passed to Finance. So click the pencil edit
icon on Invoke2 and create the Input Variable called
vFinanceOut
Click Ok to dismiss the New Input Variable window

and then, click Ok again to dismiss the Property
Editor window.
- 79 of 99 -
To finish the OnMessage path, we need to map
inputs into the Invoke2. So, double-click on Assign2
to display the Mapper.
We want to pass both the PO and the DN to

Finance, so we will concatenate and bind them to
the vFinanceOut variable we created above. Before
we can perform the string concatenation, we need to
marshal the XML data into string form.
So, expand vFinanceOut on the right (input side) to

see the part1 element. This is our mapping
destination. Click on it to turn on a blue mapping
lane. We will insert our operators (Do Marshal and
Concat) into this mapping lane.
From the BPEL menu, select Do Marshal to add a

Do Marshal element to the mapping lane. Do it
again so that you have two of them, one each for the
PO and the DN data:
From the String menu, add a Concat element to the

same blue mapping lane.
Add some descriptive text to the first element of the

Concat by double clicking in the slot and typing:
Finance, please process this order: (add a trailing
space after the colon, then press Enter):
- 80 of 99 -
Now, “wire up” the PO and DN inputs to the two Do
Marshal elements and wire up the Do Marshals to
the Concat as shown below.
Finally, connect the Concat to vFinanceOut / part1:
Select the Source control in the upper-left corner of

the BPEL Editor to view the generated BPEL syntax
for this Assign element:
Using the Mapper was sure easier than coding the Notice in this screen shot that
BPEL syntax! The Source and Design views are the BPEL Editor is enlarged
to provide maximum “real
kept in-synch so, you can make edits in either place. estate” for editing. It's easy
For example, if you forgot to include the space after to maximize and minimize a
the colon (in “... process this order: “), it might be tabbed window in NetBeans.
quicker to make the edit in Source mode. Just double-click on its tab.
- 81 of 99 -
Save All your work.
Click the Design control to return to the Design

canvas.
Let's focus on the OnAlarm path portion of the Pick.

The OnAlarm path allows us to tell the receive not to
wait forever for an incoming DN to match a PO.
Double-click on the Timer (Alarm Handler) element
to configure the wait duration:
ISO 8601 is an international

The Mapper displays and shows us an ISO 8601 standard for representing
duration literal: date and time data. Its data
and time formats order
values from most to least
significant which means from
year to seconds. Durations
are also defined by the
The tooling shields us from understanding ISO 8601 specification. They are
deeply. Just double-click on the duration literal to governed by the following
format:
see the Duration window. Use it set duration to 30 P[n]Y[n]M[n]DT[n]H[n]M[n]S
seconds: or P[n]W where:
– P is for “period” and
always begins a duration
– Y is year
– M is month
– W is week of the year
– D is day of the year
– T is the time designator
constant that precedes
all time data
– H is the hour of the day
Click OK to see the duration element in the mapper – M is the minute
change: – S is the seconds
Elements can be omitted if
they are zero. So,
"P3Y6M4DT10H30M7S" ,
"P21DT14H" and "P5Y" are
Save All your work. all valid durations. To learn
more, see Wikipedia's ISO
8601 entry.
Click the Design control to leave the Mapper mode
and return to the Design canvas.
- 82 of 99 -
To finish up the OnAlarm path, we need an Assign
and Invoke pair to establish data and interface with
the Error Queue via the ErrorOut partner link.
So, add an Assign and then an Invoke below the

Timer element.
Connect the Invoke3 element to ErrorOut:
Again, I am showing an
undocked window. To
undock a window, right-click
on its top border and select
the Undock Window option:
To redock windows, use the

Window / Reset Windows
main menu bar option.
- 83 of 99 -
To complete the linkage between Invoke3 and
ErrorOut, we need to specify an input variable. So,
double-click on Invoke3. For Partner Link, make
sure that ErrorOut is selected from the drop-down
list. Establish an Input Variable called: vErrorOut
Click OK twice. Once to close the New Input

Variable window and again to close the Property Do Marshal is under the
Editor. BPEL menu and Concat is
under the String menu.
Double-click on Assign3 to display the Mapper so
For convenient copy and
we can assign some data to be passed to the error paste, here is the text for the
queue via the vErrorOut variable. first slot of the Concat: “Error
/ Timeout waiting for DN: ”
As shown below, open up a blue mapping lane for
vErrorOut / part1 and use a Do Marshal and then a Don't enter the quotes, but do
copy the trailing space after
Concat to combine an error message with the string the colon.
version of the PO that was passed in:
- 84 of 99 -
Save All your work.
Click the Design control to leave the Mapper mode

and return to the Design canvas.
You may be anticipating that we have completed

with this Purchaser Process now. It looks good:
However, the little, yellow, triangular warning icon in

the middle hints that we have something left
unfinished. Let's Validate XML and watch the Validate All is on the far right
Output panel for messages: side of the top of the BPEL
Editor. You may have to
enlarge the panel to find it.
You see: “WARNING:

Activity does not have
correlations defined on it.”
isn't a fatal error, but without
correlation, our
asynchronous receipt of
delivery notes can't be
This is a nice lead-in to our next topic. We need to
matched up with the right
define correlation. BPEL process instance.
- 85 of 99 -
Defining a Correlation is a powerful feature of a BPEL engine.
Correlation It allows it to tie together a process instance created
earlier with a new incoming message that should be
processed by that instance. Correlation is
fundamental to support for long-lived transactions.
The original process instance might be created
today and a new message for it might arrive a week
from now. The engine associates the message with
the appropriate instance that initiated the original
external interaction that resulted in the inbound
message.
The message is:
Let's ponder the warning message we just saw. The “WARNING: Activity does not
have correlations defined on
tooling sees that we have two receives in our model: it.”
So, there are multiple entry points for messages

and, since we have an OnMessage handler, it
assumes that we will be receiving asynchronous
message data that needs to be matched up with the
message data that came through the Receive1 that
instantiated the business process instance initially.
The BPEL process correlates the incoming message

based upon one or more shared message elements.
In our scenario, PO Number is in both the PO and
DN messages. So, let's establish a correlation
based upon PO Number.
Right-click on the Message element in the

OnMessage path and select Define Correlation. The
Define Correlation window displays.
The Initiating Message Activity drop-down list shows

all the receives that can be used to start correlation.
Since the original PO message came in at the top of
our model at Receive1, select Receive1 from the list:
- 86 of 99 -
Click Next to move the wizard forward to the Define
Correlation step. A Mapper appears.
Show that you want the BPEL process to match an

incoming DN with the PO that initiated the process
instance based upon the value of the PONumber.
Perform the mapping:
Click Finish to close the wizard window. Now, the BPEL engine will
match messages coming into
the OnMessage with the right
Now, Validate XML again and watch in the Output existing business process
Panel to see that no errors are left to correct. The instance based upon
earlier warning we saw about missing correlation matching values of the
has disappeared. PONumber fields in the PO
and DN messages.
Let's get ready to test the Purchaser Process. First,

we need to build the Purchaser module and then
we'll assemble it into a composite application for
deployment.
Check your Purchaser module for errors and

assemble it by right-clicking on Purchaser in the
Projects panel and selecting Build.
Look in the Output Panel for the “BUILD

SUCCESSFUL” message.
Our next step is to create a composite application

that we can deploy.
- 87 of 99 -
Create a new composite application by selecting the
File / New Project / SOA / Composite Application
sequence.
Click Next to advance the wizard.
For Project Name, enter: PurchaserCA and then,

click Finish. The CASA Editor canvas appears.
See that PurchaserCA has been added to the

Projects panel.
Drag the Purchaser node from the Projects panel This is how you tell the CASA
into the JBI Modules section of the open CASA Editor what service units you
want added to the service
Editor canvas. assembly.
Click on the Build Project tool at the top of the CASA

Editor canvas to assemble the composite
application.
The module is analyzed and the CASA Editor

displays the appropriate WSDL Ports connected to
the Purchaser module. You might want to rearrange
the elements on the canvas to improve readability:
We see that our BPEL

process consumes two
interactions and initiated
three. Since we thoughtfully
labeled the names Input and
Output Variables the
interactions are clearer:
– A purchase order comes
into the Purchaser via a
SOAP message through
POIn
– The Purchaser sends out
the purchase order via
SOAP through POOut
– A delivery notice
becomes available in a
file and is brought in via
DNIn
– Our process
communicates with
finance and records
errors via JMS using
FinanceOut and ErrorOut
variables respectively
- 88 of 99 -
Save All your work.
Click on the Deploy Project tool and watch the

Ouput panel for any errors. As always, the “BUILD
SUCCESSFUL” message is a very good sign.
Testing the Let's test the completed Purchaser Process. Recall

Purchaser that it is initiated when a PO message is sent from
Application the Internet Shop Front. The PO message comes in
as a SOAP over HTTP transmission through the
HTTP binding component. See the highlighted path
below:
The NetBeans tooling makes it easy to send SOAP

messages into a composite application. A testing
facility is provided via the Test node at the bottom of
a composite application's hierarchy. Find the Test
node under Purchaser, right-click on it and select
New Test Case:
- 89 of 99 -
The test case wizard starts.
“TC” for “Test Case” and
For Test Case Name, enter: TC2001 “2001” as that is the PO
Number we'll supply in the
Click Next to move on to pick the WSDL interface test case.
through which we want to pass a SOAP test
message.
Select the Purchaser_POIn_SOAP.wsdl:
Click Next to select an operation in that WSDL.
There is only one operation in the WSDL, so click on I have noticed that the test
case may not appear under
it (Purchaser_POIn_SOAPOperation) and select the Test node so it looks your
Finish. The new test case appears under Test in the test case wasn't created. If
Projects panel. you see that, just create
another test case with a
A skeleton message request has been created by different name. Then, you'll
see two test cases appear
reading the WSDL: including your original
TC2001 case. Then, just
delete the second one you
created. Looks like a bug.
Hope this workaround works
for you.
This is a similar test facility to

the soapUI tool we used
earlier.
- 90 of 99 -
Replace the skeleton test case with the following
XML statements:
<soapenv:Envelope
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Body>
<po:PO>
<po:Items>
<po:Item>
</po:Item>
<po:Item>
</po:Item>
<po:Item>
</po:Item>
</po:Items>
</po:PO>
</soapenv:Body>
</soapenv:Envelope>
Notice that we have created a PO message that Use Alt-Shift-F to reformat

contains three items with ItemNumbers of 201, 202 the XML statements after the
copy and paste.
and 203. This will give our BPEL ForEach loop
several Items to process.
Save All your work.
Let's create a second test case with a PO Number of

3001. Again, right-click on Test in the PurchaserCA
hierarchy and select New Test Case.
For Test Case Name, enter: TC3001 and click Next.
As before, select the Purchaser_POIn_SOAP.wsdl

WSDL and then the Purchaser_POIn_SOAPOperation
operation. Click Finish to complete the wizard.
- 91 of 99 -
When the test case appears, edit it so it contains
these XML statements:
<soapenv:Envelope
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
<soapenv:Body>
<po:PO>
<po:Items>
<po:Item>
</po:Item>
<po:Item>
</po:Item>
</po:Items>
</po:PO>
</soapenv:Body>
</soapenv:Envelope>
Save All your work. Remember that you can use

Alt-Shift-F to reformat the
XML statements after the
Now we are ready to test. First, let's talk through copy and paste.
what will happen. It will unfold like this:
1. Run both test cases to simulate the Internet

Shop Front sending two POs to the
Purchaser System
2. Purchase System instantiates two BPEL
process instances
3. Each process instance sends the PO off to
the Supplier System and waits for the
asynchronous callback.
4. As the Supplier BPEL process sees an
incoming PO, it immediately produces a DN
and makes it available to the Purchaser
System's BPEL engine via the file system
5. Thanks to correlation, the right Purchaser
BPEL process instance picks up the DN
processes it.
6. The Purchaser BPEL process interfaces with
Finance via a JMS queue.
- 92 of 99 -
Let's see if these steps ring true. In our testing, we
are “on the clock” since the OnAlarm branch waits
30 seconds for a matching DN. So, the clock is
ticking as we perform the following test steps. Make
sure you do all these steps within 30 seconds. Start
two Windows Explorers so you can easily view the
contents of the C:\MyBPELTutorial\fromSupplier and
C:\MyBPELTutorial directories. Now, in 30 seconds
to do the following:
1. Click on the TC2001 node under Test in the

Projects panel and select the Run option. You won't get any SOAP
2. In Windows Explorer, look in the output in the testing
framework for these test case
C:\MyBPELTutorial\fromSupplier directory for runs because the POIn
the DN record that was just generated by the partner link is based upon a
Supplier Process for the PO just sent in. one-way message exchange
3. In Windows Explorer, move the generated DN pattern. It's in only.
file by dragging it to C:\MyBPELTutorial.
The file has been archived
4. Watch C:\MyBPELTutorial to see that the file into this directory:
you just moved has disappeared indicating C:\MyBPELTutorial\Purchase
that it was found by the File BC and was rCA_FileInboundService_Pur
delivered to the Purchaser Process. chaser_DNIn_Fil84581805\fil
ebc-in-processing directory
If you made it through the steps in 30 seconds, we If you don't see the the file
should see an entry in the qFinanceOut queue when disappear from
we check in a moment. C:\MyBPELTutorial and get
archived, rerun the test case.
Rest a moment and ponder.
We can be leisurely now.
Next, to test exceeding the 30-second threshold, We aren't “on the clock” here.
we'll use the TC3001 test case to send in another For TC3001, we want to
request to the Purchaser Process. We won't move exceed the threshold.
the generated DN to C:\MyBPELTutorial. That way,
the Purchaser Process will never see it, the
OnAlarm branch will timeout and we'll get an entry in
the qErrorOut queue.
So, click on the TC3001 node under Test in the

We won't move the
Projects panel and select the Run option. generated DN for this test
case so we can let the
Open up the generated DN file in the OnAlarm timer time out.
C:\MyBPELTutorial\fromSupplier directory and see
that the Supplier Process has generated the DN as
a delimited record:
3001|31^301~32^302|2008-11-05T00:22:28.59-06:00
- 93 of 99 -
Before we check the contents of our two queues and We are stalling here for 30
declare victory, let's review the overall application seconds without sending
along this latest
architecture to remind ourselves what should have DNFromSupplier text file so
just happened: the Pick “times out” and we
get an entry sent to our error
In the illustration below, we see that when the DN is queue.
received from the Supplier Process, the Purchaser
Process adds a message to the queue that Finance
watches for completed orders. Remember that we
established a timeout value of 30 seconds. So, if a
corresponding DN is not received within that
threshold, an entry is written to the error queue.
We moved a DN from the fromSupplier directory to

C:\MyBPELTutorial, so we'd expect that the
qFinanceOut queue will contain an entry for that DN
and its matching PO.
We are letting the other DN sit in fromSupplier for

longer than 30 seconds, so the “timer” will have
expired in the Purchaser Process and we should see
one entry in qErrorOut for this unmatched PO/DN
combination.
Let's use HermesJMS to check for the messages in

our two queues.
- 94 of 99 -
Viewing Use the Windows Start / All Programs / HermesJMS If you don't have HermesJMS
Contents of / Hermes sequence to start HermesJMS. installed and configured in
your environment, go to
JMS Project 0 to learn how to
Queues Since we have already configured HermesJMS in download, install and
Project 0, we can expand the sessions / JavaMQ configure it.
hierarchy and see our two queues:
You can also start
HermesJMS by executing the
hermes.bat file in
C:\Program
Files\HermesJMS\bin.
Double-click on qFinanceOut to see what PO/DN

pairs Purchaser Process matched:
- 95 of 99 -
At the top of the message you can see the message
we included along with the PO and DN data:
Finance, please process this order:
Double-click on qErrorOut to see the POs for which

the Purchaser Process did not receive a matching
DN from the Supplier Process within 30 seconds:
You see the message we appended to the front of

the unmatched PO:
Error / Timeout waiting for DN:
So, we saw what we expected. One PO/DN pair

was matched and a message was sent to Finance
approving the PO for payment. The other PO was
not matched and an entry was recorded in an error
queue so a person can research the situation.
Congratulations! We are done. Refresh your

memory in the following Summary section, then take
a well-deserved break.
- 96 of 99 -
Summary
Let's revisit the work we did in this module by reviewing the two diagrams that framed the
projects we tackled. As you recall from the illustration below, we initially set the stage with a
business conversation involving an Internet Shop Portal that encouraged customers to make
online purchases. A Back Office operation interfaces with the Supplier for order fulfillment and
with Finance for customer invoicing. To keep the scope of the tutorial manageable, we focused
two BPEL processes
only on building the Back Office (Purchaser) and Supplier capabilities.
With the business context understood, we began implementing the Supplier Process illustrated
below. To keep our technical scenario well-bounded, we ignored interactions with the Shipper.
Our Supplier Process work involved receiving a purchase order (PO) message via SOAP over
HTTP and generating a delivery notice (DN) as a delimited record written to the file system. We
got some good experience with the custom encoder capability that facilitates transformation
between delimited and XML formats.
- 97 of 99 -
Once the Supplier Process was completed and unit tested, we turned our attention to the
Purchaser Process which used BPEL asynchronous processing features to match POs from the
Internet Shop Front with the matching DN from the Supplier Process. We got additional
exposure to the custom encoder to transform the delivery notice from delimited form to XML.
One of the most interesting features of the Purchaser Process is how correlation is used to
match up of the right business process instance with its corresponding delivery notice based on
PO Number. The Supplier Process finished the scenario by writing a message to JMS queues
to direct further processing by Finance who coordinates customer invoicing and investigating
unmatched purchase orders.
On the next page, you'll find pointers to some references that to help you continue to learn about
the OpenESB-based technology.
- 98 of 99 -
References
Here are some references that may help you learn more about the concepts and product features
you explored in this module.
BPEL SE - Component Page:

https://open-esb.dev.java.net/BPELSE.html
- Wiki:
http://wiki.open-esb.java.net/Wiki.jsp?page=BPELSE
- BPEL Service Engine User's Guide:
http://wiki.open-esb.java.net/Wiki.jsp?page=UsingBPELDesignerServiceEngine
- Java One 2008 BPEL Hands-On Lab:
http://developers.sun.com/learning/javaoneonline/j1lab.jsp?lab=LAB-5510&yr=2008&track=1
File BC - Component Page:

http://wiki.open-esb.java.net/Wiki.jsp?page=FileBC
- File BC User Guide:
http://wiki.open-esb.java.net/Wiki.jsp?page=UserGuide
- Tutorial:
http://wiki.open-esb.java.net/Wiki.jsp?page=WorkingWithFileBindingComponent
JMS BC - Component Page:

http://wiki.open-esb.java.net/Wiki.jsp?page=JMSBC
- JMS BC User Guide:
http://wiki.open-esb.java.net/Wiki.jsp?page=UsingJMSBindingComponent
- JMS BC Demonstration Screencast:
http://wiki.open-esb.java.net/Wiki.jsp?page=ProcessStockAlertWithJMSBindingComponent
CASA Editor - Quick Start Guide to the CASA Editor

http://www.netbeans.org/kb/60/soa/casa-quickstart.html
- Tutorial: Connecting Binding Components With the CASA Editor
http://www.netbeans.org/kb/60/soa/casa-bc-bc.html
Thank you for your interest in GlassFish ESB,

OpenESB and/or Java CAPS. I hope this tutorial
has helped you appreciate the power of BPEL to
orchestrate the integration of multiple systems.
I would appreciate your feedback on this tutorial:

Thomas.Barrett@sun.com
- 99 of 99 -

DiggingDeeperBPELGlassFishESB1 2

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DiggingDeeperBPELGlassFishESB1 2

Uploaded by

Copyright:

Available Formats

SUN MICROSYSTEMS

Digging Deeper into BPEL

Please send feedback to:

Tutorial Format ........................................................................................................................... 5

Project 0: Preparing the Environment

Project 1: Creating Shared Components

Project 2: Building the Supplier Application

Project 3: Developing the Purchaser Application

This tutorial documents an excellent GlassFish ESB demonstration delivered in the

This document is intended to be a stand-alone, hands-on experience. No additional exercise

Business We are running an Internet Shop portal where

As soon as the shopping portal receives an order, it

Once a supplier receives a purchase order (PO), it

In this demonstration lab, we will implement the

● Internet Shop Front submits a purchase order (PO) via SOAP

The BPEL processes run inside the BPEL service

Click on the Installed tab to see a list of plug-ins that

Click on the Category column heading to sort the list

Installing If you didn't see “soapUI Web Service Testing”

Click on the soapui-netbeans-plugin link and

Complete the wizard sequence and elect to restart

Click on the Installed tab and look for “soapUI Web

Click the Close button to close the Plugins window.

We now have the add-on plug-in we need for this

Download the Hermes installer to your desktop:

After, selecting the Download link, select the jar file

Installing When download is complete, open a command This is an all-Java tool, so

For cut and paste convenience, here is the

Right-click on sessions and select New / New

The Preferences window appears. Change the

Click on the Providers Tab at the bottom of the

Right-click in the Providers tab window and select

Right-click on the Library control and select Add

For me, that's

When Hermes is done scanning, it lists all the jar

Click Apply to record your library selections.

Expand the sessions hierarchy, right-click on

The Preferences window appears again.

In the Sessions tab (the default), select

Click the Apply button to record your changes.

Click OK to close the Preferences window.

Expand the JavaMQ node and see that

Perform the same steps to configure access to the

Now that the JavaMQ session is established and

Exit HermesJMS by using the File / Exit sequence.

Creating a You are likely to have many different NetBeans

First, in Windows Explorer, create a new directory

Next, use the File / Project Group / New Group

Exploring I didn't find the Project Group feature real intuitive at

First notice the label of the Projects panel:

This indicates that we are focusing on projects in

Create a project by using the File / New Project /

Click Finish to quickly create a dummy project. The

Repeat the sequence again to create another

Your project names will

Let's exercise our Project Group by first closing it.

Now, open all the projects in your group all at one

Clean up you project group by deleting both dummy

You usually want to “Also

Delete is destructive. If you

Make sure that the Project Location is set to:

Note that you can edit the

Click on the Validate XML control to make sure the