Developer Guide to BPEL Designer: The BPEL Mapper
Last Updated: 23 October 2006
Contributed and maintained by
Wallis Sholar
Contents
Developer Guide to BPEL Designer
About the BPEL Mapper
The BPEL Mapper provides a framework for processing and directing BPEL process data.
This framework consists of the following components:
- Menu Bar. The menu bar provides all BPEL Mapper XPath functions you use to create BPEL mappings.
You can also enhance or extend BPEL mappings by incorporating predicates that consist of XPath functions.
- Source tree pane. The source tree pane contains a tree component that provides access to a BPEL process's data variables.
- Mapping pane. The mapping pane contains a canvas for creating BPEL mappings.
When you select a function in the menu bar, a function box appears in the mapping pane.
If the function accepts any arguments, then the left side of the function box has one connector for each argument.
If an argument is optional, then a question mark appears after the argument name.
The right side of the function box has one connector for the result.
You can use the BPEL Mapper with the following BPEL process elements:
- Assign activity. You can define one or more copy assignments.
- If activity. You can define the condition.
- ElseIf element within an If activity. You can define the condition.
- ForEach activity. You can define the condition.
- RepeatUntil activity. You can define the condition.
- While activity. You can define the condition.
- Wait activity. You can specify the deadline or duration.
- Destination tree pane. The tree component of the destination tree pane depends on the BPEL process element that you are mapping.
The destination tree pane contains the following components:
- For an Assign activity, the right pane contains the same tree component as the left pane.
- For an If activity, ElseIf element, ForEach activity, RepeatUntil
activity, and While activity, the right pane contains a Result node.
- For the Wait activity, the right pane contains a Deadline or Duration node.
top
You can create a mapping from the source tree pane directly to the destination tree pane, without using any of the functions.
This type of mapping can be any of the following:
- Variable to variable
- Part to part
- XSD element to XSD element
- XSD attribute to XSD attribute
You can also create a mapping that uses one or more XPath functions from the BPEL Mapper's menu bar.
For example, if the BPEL process includes a Wait activity that waits for a period of time,
then you can use the Duration Literal function to specify the duration.
To create a mapping without using any functions:
- In the source tree pane, expand the tree component until the node that you want to map from appears.
- If the destination tree pane contains a tree component, then expand
the tree component until the node that you want to map to appears.
- Select the node in the source tree pane and drag the pointer to the node in the destination tree pane.
A link connects the nodes.
To use a function in a mapping:
- Click the drop-down menu that contains the function.
- Click the function.
A function box appears in the middle pane.
- Map any arguments into the appropriate connector on the left side
of the function box. The source can be a node in the source tree pane
or the output from another function box. If an argument is optional,
then a question mark appears after the argument name.
- Map the result from the right side of the function box. The
destination can be a node in the destination tree pane or the input
into another function box.
To delete a link or function in a mapping:
- Select the link or function.
- Press Delete.
top
The BPEL Mapper enables you to create a predicate that consists of XPath functions.
A predicate applies a condition to a node that can have multiple
values. The result is the subset of nodes that satisfy the condition.
For example, assume that a node represents the amount of a product.
If you want to select all products whose amount is greater than 50,
then you can use the greater than and number literal functions to define the condition.
Only certain types of nodes allow you to create predicates. The
contextual menu of these nodes contains the New Predicate option.
Once you create a predicate, you can use the predicate in an
assignment. For example, you can copy data from a predicate in the
source tree pane to a node in the destination tree pane.
You can edit or delete an existing predicate.
To create a predicate:
- In the source tree pane, right-click a node and choose New Predicate.
The Predicate Editor appears.
- Use XPath functions to create the condition for the predicate. Map
the result to the predicate node in the destination tree pane.
- Click OK.
The editor adds the predicate node immediately below the original node. The condition appears in brackets.
To edit a predicate:
- In the source tree pane, right-click the predicate node and choose Edit Predicate.
- Modify the condition.
- Click OK.
To delete a predicate:
- In the source tree pane, right-click the predicate node and choose Delete Predicate.
- Click Yes.
top
A collection of XPath functions are available in the BPEL Mapper's
menu bar. These functions are based on the XPath 1.0 specification.
Each function has zero or more arguments. Each function returns a single result.
The menu bar contains the following drop-down menus:
Datetime,
Operator,
Boolean,
String,
Nodes, and
Number.
Datetime
The Datetime menu contains the following functions:
- Duration Literal enables you to enter a duration literal. Use the format specified in the XML Schema specification.
- Current Time provides the current time.
- Current Date provides the current date.
- Current Date and Time provides the current date and time.
Operator
The Operator menu contains the following functions:
- Greater Than
- Greater or Equal
- Less Than
- Less or Equal
- Addition
- Subtraction
- Multiplication
- Div or division operator returns the quotient for a given dividend and divisor.
- Mod or modulus operator returns the remainder for a given dividend and divisor.
- Negative
- Not Equal
- EQUAL
Boolean
The Boolean menu contains the following functions:
- True returns true.
- False returns false.
- AND uses the following logic: If both arguments are
true, then the function returns true. If either argument is false, then
the function returns false.
- OR uses the following logic: If either argument is
true, then the function returns true. If both arguments are false, then
the function returns false.
- Not uses the following logic: If the argument is
false, then the function returns true. If the argument is true, then
the function returns false.
- Lang returns true or false depending on whether
the language of the context node is the same as or is a sublanguage of
the language specified in the argument.
- Boolean converts the argument to a boolean. For detailed information about the logic, see the XPath 1.0 specification.
String
The String menu contains the following functions:
- Contains uses the following logic: If the first
argument string contains the second argument string, then the function
returns true. Otherwise, the function returns false.
- Normalize Space returns the argument string with
whitespace normalized by stripping leading and trailing whitespace and
by replacing sequences of whitespace characters with a single space.
- String converts an object to a string.
- Starts With uses the following logic: If the first
argument string starts with the second argument string, then the
function returns true. Otherwise, the function returns false.
- String Length returns the number of characters in the string.
- Substring returns the substring of the first
argument starting at the position specified in the second argument with
the length specified in the third argument. The position of the first
character is 1, the position of the second character is 2, and so on.
The third argument is optional. If the third argument is not specified,
then the function returns the substring starting at the position
specified in the second argument and continuing to the end of the
string.
- Substring Before returns the substring of the
first argument string that precedes the first occurrence of the second
argument string in the first argument string. If the first argument
string does not contain the second argument string, then the function
returns an empty string.
- Substring After returns the substring of the first
argument string that follows the first occurrence of the second
argument string in the first argument string. If the first argument
string does not contain the second argument string, then the function
returns an empty string.
- Translate returns the first argument string with
occurrences of characters in the second argument string replaced by the
character at the corresponding position in the third argument string.
- Concat returns the concatenation of the arguments.
- String Literal enables you to enter a string literal.
Nodes
The Nodes menu contains the following functions:
- Last returns the context size.
- Local Name returns the local part of the expanded
name of the node in the argument node-set that is first in document
order. (An expanded name consists of a local part and a namespace URI.)
- Name returns the qualified name that represents
the expanded name of the node in the argument node-set that is first in
document order. (An expanded name consists of a local part and a
namespace URI.)
- Namespace URI returns the namespace URI of the
expanded name of the node in the argument node-set that is first in
document order. (An expanded name consists of a local part and a
namespace URI.)
- Position returns the context position.
- Count returns the number of nodes in the argument node-set.
Number
The Number menu contains the following functions:
- Number converts the argument to a number. For detailed information about the logic, see the XPath 1.0 specification.
- Number Literal enables you to enter a number literal.
- Round returns the number that is closest to the argument and that is an integer.
- Sum returns the sum, for each node in the argument node-set, of the result of converting the string values of the node to a number.
- Floor returns the largest number that is not greater than the argument and that is an integer.
- Ceiling returns the smallest number that is not less than the argument and that is an integer.
top
Mapping Examples
These examples illustrate a variety of mapping scenarios:
Assign Activity Scenario
Assume that you want a BPEL process to copy data received from a partner. Do the following tasks:
- Add an Assign activity after the Receive activity.
- Select the Assign activity and use the editor to define one or more copy assignments.
The following example shows a copy assignment that does not use any XPath functions.
The itinerary part of the ItineraryIn variable is copied to the itinerary part of the ItineraryOut variable.
Notice that the left pane and the right pane contain the same tree component.

Click to enlarge
The following example shows a copy assignment that uses the concat XPath function.
The input variable paramA is concatenated to the end of the string literal Parameter A: and copied to the output variable paramA.

Click to enlarge
If Activity Scenario
Assume that you want to execute a series of steps only if a certain condition is true. Do the following tasks:
- Add an If activity to the BPEL process.
- Select the If activity and use the editor to define the Boolean condition.
- Add the steps inside the If activity.
The following example shows a mapping for the condition.
The mapping uses the Not XPath function, which is available from the Boolean portion of the menu bar.
If the itinerary has an airline reservation, then the Not XPath function returns true.
The result is mapped to the Result node in the right pane.

Click to enlarge
Predicate Scenario
Assume that you want a BPEL process to copy itinerary data from itineraries of customers with no more than two in their party.
The input records include a variable that specifies the number of passengers in the customer's party. Do the following tasks:
- In the left pane of the editor, right-click the repeating node and choose New Predicate.
The Predicate window appears.
- Add the Less Than XPath function to the middle pane.
- Add the number literal XPath function to the middle pane. Set the value to 3.
- Map the variable node to the first argument of the Less Than XPath function.
- Map the result of the number literal XPath function to the second argument of the Less Than XPath function.
- Map the result of the Less Than XPath function to the Result node in the right pane.
- Click OK.
The following example shows how the mapping appears in the Predicate window.
Once you click OK, you can use the predicate node in a copy assignment.

Click to enlarge
If the BPEL process received the following XML, then the predicate would select the first Air tag.
<Air>
<NumberInParty>2</NumberInParty>
</Air>
<Air>
<NumberInParty>4</NumberInParty>
</Air>
<Air>
<NumberInParty>6</NumberInParty>
</Air>
top
Copyright and Trademark Notice