Using the BPEL Mapper to Edit BPEL Processes
Last Updated: 30 November 2006
Contributed by Victoria Zhukovskaya, maintained by Irina Filippova
This tutorial illustrates how to work with XPath expressions using the BPEL Mapper. The BPEL Mapper is a
component of the BPEL Designer feature of the NetBeans Enterprise
Pack. Using extensive BPEL Mapper capabilities, you can work with predicates, use XPath functions, and
copy variables within a business process.
The BPEL Mapper allows you to add and edit functions that are
specific for some business process elements, such as Assign , If,
ElseIf element of If,
ForEach, RepeatUntil, While, and Wait. Each of these elements can have
specific expressions types, such as copy assignments, condition
expresions, and time functions. For example, the If, ElseIf
element of If, and RepeatUntil activities can have condition
expressions, the Assign element includes copying expressions, the Wait
element can have duration expressions, and the ForEach activity can
have expressions with integer values. Using the BPEL Mapper's graphic
interface, you can also perform calculations by assigning XPath
operations and functions to variables and to XSD elements, attributes,
and parts.
Prerequisite
This tutorial assumes that you have some basic knowledge of, or
programming experience with, SOA technologies and the NetBeans IDE.
System Requirements
This tutorial assumes that your system meets the requirements specified in the System Requirements topic of the NetBeans Enterprise Pack 5.5 Release Notes.
Software Needed for the Tutorial
Before you begin, you must install the following software on your computer:
- NetBeans IDE 5.5 with NetBeans Enterprise Pack 5.5 (download)
Contents
top
Configuring the Tutorial Environment
Before you deploy your application, the Sun Java System Application
Server and JBI runtime must be configured correctly and running.
See the Configuring the Tutorial Environment section of the A Simple Synchronous BPEL Process tutorial to know how to start the Application Server.
top
Creating the SynchronousSample Project
For this tutorial, you will use the Synchronous BPEL Process sample project.
- From the IDE's main menu, choose File > New Project.
- In the Categories list, expand the Samples node and select the Service Oriented Architecture node.
- In the Projects list, select Synchronous BPEL Process.
- Click Next.
- Accept the defaults for the Project Name, SynchronousSample and Project Location or change the values to suit your preferences.
- Click Finish.
The Projects window now contains two project nodes: a BPEL Module project node labeled SynchronousSample, and a Composite Application project node labeled SynchronousSampleApplication.
top
Exploring the BPEL Mapper Window
- In the Projects window, expand the SynchronousSample project node and the ProcessFiles node.
- Double-click the SynchronousSample.bpel file.
The IDE opens the Design view for the BPEL file.
- On the diagram, select the Assign1 element.
The BPEL Mapper window for the Assign1 element opens in the bottom part of the IDE.
- Expand the inputVar node on the left side of the BPEL Mapper window and the outputVar node on the right side.
Notice that for the Assign1 element the value of the input parameter is copied to the output parameter.

Click to enlarge
Let's view the source code for the copying operation. To view the source code, right-click the Assign1 element on the diagram and select Go to Source from the pop-up menu.
In the Source view, you see the following code that copies the value of input paramA to the output paramA.
<copy>
<from>$inputVar.inputType/paramA</from><to>$outputVar.resultType/paramA</to>
</copy>
Delete this operation from this BPEL Mapper window by performing the following steps:
- Click the Design tab to open the Design view and select the Assign1 element on the diagram.
- In the BPEL Mapper window, click the line that connects the input and output parameters and press the Delete button.
In the Source view, you can check that the code does not contain the copying operation any more: <assign name="Assign1"></assign>
- Click Save.
top
Editing the Synchronous BPEL Project using the BPEL Mapper
The examples below show how to work with the current-date function and the following string functions: concat, substring, and string-length. You will also use the string and number literals and learn how to use node-set functions such as count and last. The examples show the usage of sum and equal operations.
Finally, you will also create two test cases to test the modified business process:
- For Test Case 0, the input parameters are any string and the test
number, and the output is a string containing the current date and time
zone.
- For Test Case 1, the input parameters are the test number and
a nodeset, and the output is a string containing the number of
elements, their sum, and the last element.
Adding a Variable
In this procedure, you add the todayIs variable of the string type to the business process. This variable is used to store the returned value of the current-date function.
- If the SynchronousSample.bpel file is not open in the IDE, open it now.
- In the Design view, right-click the SynchronousSample process element and select Add > Variable.
- In the Name field, enter todayIs.
- Expand the Built-in Types node and select the string type.
- Click OK.
Select the Assign1 element on the diagram. The todayIs variable is now shown in both tree panes of the BPEL Mapper window.
Modifying XML Schema
In this procedure, you modify the properties of an existing XML schema element and add a new nTest element. The nTest element is used to define which of the If branches will be executed. Later, you will use the nTest element in test cases.
- In the Projects window, expand the SynchronousSample project node and the ProcessFiles node.
- Double-click the SynchronousSample.xsd node.
The IDE opens the Schema view for the XML schema file.
- In the columns of the Schema view, select Complex Types > simpleProcess > sequence > paramA.
You can click the column button
to make sure you are in the column mode of the view.
- In the Properties window, set the Max Occurs parameter to unbounded to allow using the values that are greater or equal to 1.
If the Properties window is not open, select Window > Properties or press Ctrl-Shift-7.

Click to enlarge
- In the third column of the Schema view, right-click the sequence element and select Add > Element from the pop-up menu.
- In the Element dialog box, enter nTest in the Name field and select the Use Existing Type option.
- Expand the Built-in Types node and select the int type.
- Click OK.

Click to enlarge
- Choose File > Save All.
Editing the BPEL Process
In this procedure, you will add the If and Assign activities to the business process.
- If the SynchronousSample.bpel file is not open in the IDE, open it now.
- In
the Design view, select the If icon on the Palette, drag selection to
the design area, and drop it onto the diagram between the start and Assign1 element.
- Move the Assign1 element into the If1 element and drop it on the main branch (without a stroke).
- On the Palette, select the Assign icon and drop it onto the diagram after the Assign1 element inside the If element.
This element is labeled Assign2.
- Right-click the If element and choose Add Else If from the pop-up menu.
- On the Palette, select the Assign icon and drop it onto the diagram inside the ElseIf branch.
This element is labeled Assign3.
See the picture below to verify that your business process diagram looks like the one in the picture below.

Click to enlarge
Adding Conditions to the If Element
You can specify the conditions for executing the If activity by following the procedures below. The nTest parameter defines which of the If branches holds true. For the If branch, nTest is equal to 1 and for the ElseIf branch, nTest is equal to 2.
To specify conditions for the If1 element:
- Select the If1 element on the diagram.
- In the BPEL Mapper window, on the menu bar, select Number > Number Literal and Operator
> EQUAL.
Two function boxes appear on the mapping pane. For your convenience,
drag the function boxes to place the Number Literal box on the left and
the EQUAL function box on the right.
- In the left tree pane of the BPEL Mapper window, expand the inputVar and inputType nodes.
- Select the nTest node in the left tree pane and drag the pointer to the any1 parameter of the EQUAL function box.
- In the Number Literal function box, double-click the input field and enter 1.
- Select the Number Literal function box and drag the pointer to the any2 parameter of the EQUAL function box.
- In the EQUAL function box, select the return boolean parameter and drag the pointer to the Result node in the right tree pane of the BPEL Mapper window.
- Select File > Save.

Click to enlarge
To specify conditions for the ElseIf element:
- Select the ElseIf element on the diagram.
- Follow the steps as in the previous procedure for If, but enter 2 as the value of Number Literal.

Click to enlarge
Adding Expressions to the Assign Element
In this procedure, you will add expressions to the Assign1, Assign2, and Assign3
elements using the Source editor. After modifying the BPEL source code, you will use the BPEL Mapper to edit the expressions.
- Right-click the Assign1 element on the diagram and select Go to Source from the pop-up menu.
- Replace the <assign name="Assign1"></assign> string with the following:
<assign name="Assign1">
<copy>
<from>current-date()</from>
<to variable="todayIs"/>
</copy>
</assign>
- Right-click the Assign2 element on the diagram and select Go to Source from the pop-up menu.
- Replace the <assign
name="Assign2"/> string with the following:
<assign name="Assign2">
<copy>
<from>concat($inputVar.inputType/ns0:paramA, ' Today is ', substring($todayIs, 1, 10), '. Time zone is ', substring($todayIs, 11, string-length($todayIs)), '.')</from>
<to>$outputVar.resultType/ns0:paramA</to>
</copy>
</assign>
- Right-click the Assign3 element on the diagram and select Go to Source from the pop-up menu.
- Replace the <assign name="Assign3"/> string with the following:
<assign name="Assign3">
<copy>
<from>concat('There are/is ', count($inputVar.inputType/ns0:paramA), ' element(s) in nodeset.', 'Sum of element(s) is ', sum($inputVar.inputType/ns0:paramA), '. Last element is ', $inputVar.inputType/ns0:paramA[last()], '.')</from>
<to>$outputVar.resultType/ns0:paramA</to>
</copy>
</assign>
- Select File > Save.
- Click the Design button on the Editor toolbar to switch to the Design view and view the results in the BPEL Mapper window.
- Select the Assign1 element on the BPEL diagram.

Click to enlarge
Notice that for the Assign1 element, the Current Date function is called and the result is copied to the todayIs variable.
- Select the Assign2 element on the BPEL diagram.

Click to enlarge
The todayIs
variable contains the current date in the following format:
YYYY-MM-DDZZ:ZZ, where YYYY is the current year, MM is the month, DD is
the date, and Z is the time zone. The output is the following sample
string: Hello! Today is 2006-11-17. Time zone is 03:00.
- Select the Assign3 element on the BPEL diagram.

Click to enlarge
The expressions for the Assign3 element show the number of nodes copied to paramA, calculate the sum of all nodes, and provide the value of the last node. The output is the following sample string: There are/is 3 element(s) in nodeset. Sum of element(s) is 6. Last element is 3.
top
Deploying the Project to the Application Server
Before initiating tests of your business process, you need to add
the BPEL Module project as a JBI module and deploy it to the
Application Server.
To do so, follow the steps described in the Deploying the Project to the Application Server section of the A Simple Synchronous BPEL Process tutorial.
top
Creating Test Cases
To test the modified BPEL process, create test cases (TestCase0 and TestCase1) as described in the procedures below. For TestCase0,
the input parameters are a string and the number of the test, and the
output is a string containing the current date and time zone. For TestCase1,
the input parameters are the test number and a nodeset, and the output
is a string containing the number of elements, their sum, and the last
element.
To create TestCase0:
- In the Projects window, expand SynchronousSampleApplication, Test, and TestCase0 nodes.
The TestCase0 node contains two XML files: Input for input and Output for output.
- Double-click the Input file node and replace the default content with the following:
<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:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:syn="http://xml.netbeans.org/schema/SynchronousSample">
<soapenv:Body>
<syn:typeA>
<syn:paramA>Hello!</syn:paramA>
<syn:nTest>1</syn:nTest>
</syn:typeA>
</soapenv:Body>
</soapenv:Envelope>
In this test, the input parameters are the test number (1) and the string "Hello!"
- Double-click the Output file node under the TestCase0 node.
- Delete the default text from the Output file.
To create TestCase1:
- In the Projects window, expand the SynchronousSampleApplication project node, right-click the Test node, and choose New Test Case from the pop-up menu.
The New Test Case wizard opens.
- For Name, leave TestCase1 and click Next.
- Expand SynchronousSample - Process Files, select SynchronousSample.wsdl and click Next.
- Select operation1 and click Finish.
- Under the Test node, expand the TestCase1 node and double-click Input.
- Replace the default content with the following:
<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:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:syn="http://xml.netbeans.org/schema/SynchronousSample">
<soapenv:Body>
<syn:typeA>
<syn:paramA>1</syn:paramA>
<syn:paramA>2</syn:paramA>
<syn:paramA>3</syn:paramA>
<syn:nTest>2</syn:nTest>
</syn:typeA>
</soapenv:Body>
</soapenv:Envelope>
In this test, the input parameters are the three nodes: 1, 2, 3, and test number = 2.
- Double-click the Output file node under the TestCase1 node and delete the default text from this file.
- Save changes by choosing File > Save All.
top
Testing the Application
To run test cases:
- In the Projects window, right-click the SynchronousSampleApplication project node and choose Test Project from the pop-up menu.
- Because
for the first run the Output file is empty, agree to overwrite the
empty output by clicking Yes in the two dialog boxes.
- Notice the message that the tests failed. This is a special case because during the first run Output.xml is empty and the output is written to Output.
- Repeat step 1.
- See the message that the tests have successfully passed.
You can open the Output.xml files for each of the test cases and check test results.
For TestCase0, the Output.xml file contains a string displaying the current date and time zone, for example "Hello! Today is 2006-11-17. Time zone is 03:00."
For TestCase1, the Output.xml file has the contains the following string: "There
are/is 3 element(s) in nodeset. Sum of element(s) is 6. Last element
is 3."
top
Summary
In this tutorial, you explored the BPEL Mapper component of the BPEL
Designer in the NetBeans Enterprise Pack. You modified a sample
Synchronous Application project and used the BPEL Mapper functionality
to add expressions and functions to a business process. You also tested
the applications and verified that expressions return valid values.
top
Copyright and Trademark Notice