Using the BPEL Mapper

The section describes how to use the BPEL Mapper.

About the BPEL Mapper

Creating BPEL Mappings

Working with Predicates

XPath Function Reference

Mapping Examples

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 operators, necessary elements, and XPath functions you use to create BPEL mappings. You can also enhance or extend BPEL mappings by incorporating predicates that consist of XPath functions.

  On the right side of the menu bar, you can use the following buttons to work with function boxes, or functoids:

  • Expand Mapped Nodes: Expands all mapped nodes.

  • Collapse All: Collapses all function boxes. This command is useful when you work with numerous function boxes in the mapping pane.

  • All: Displays all nodes.

  • Output: Displays only connected nodes.

• Source tree pane: The source tree pane is placed on the left and contains a tree component that provides access to a business process's data variables and partner links.

• Mapping pane: The mapping pane contains a canvas for creating BPEL mappings. When you select a function from 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 business process elements:

  • Assign activity: Defines one or more copy assignments.

  • If activity: Defines the condition.

  • Else If element within an If activity: Defines the condition.

  • For Each activity: Defines the condition.

  • Repeat Until activity: Defines the condition.

  • While activity: Define the condition.

  • Wait activity: Specifies the deadline or duration.

  • onAlarm event: Specifies the deadline or duration.

• Destination tree pane — This pane is placed on the right. The component displayed in destination pane tree are associated with the business process element that you are mapping. The 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, Else If element, For Each activity, Repeat Until activity, and While activity:: The right pane contains a Result node.

  • For an Wait activity: The right pane contains a Deadline or Duration node.

To Open the BPEL Mapper Window

• Open the BPEL diagram and do one of the following:
  1. Double-click the element that requires BPEL Mapper. The Mapper tab opens.
  2. Select an element that requires the Mapper and on the Diagram toolbar and click the Mapper tab.

  If you want to see the Mapper and the diagram of the process at the same time, you can place the mapper into a separate window. For more information see Cloning Document Views.

Creating BPEL Mappings

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

• Partner link to partner link

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

1. In the source tree pane, expand the tree component until the node that you want to map from appears.
2. If the destination tree pane contains a tree component, then expand the tree component until the node that you want to map to appears.
3. 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

1. In the destination tree pane, expand the tree and select the node you want to map to. A blue area appears on the mapping pane. The functions you choose will appear here.
   
2. Click the drop-down menu that contains the function.
3. Click the function.

   A function box appears in the mapping pane.

4. 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.
5. 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

1. Select the link or function.
2. Press Delete.

Working with Predicates

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 number of products. If you want to select all products whose number is greater than 50, then you can use the greater than and number literal functions to define the condition.

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

1. In the source tree pane, right-click a node (schema element or attribute) and choose New Predicate.

   The Predicate Editor appears.

2. Use XPath functions to create the condition for the predicate. Map the result to the predicate node in the destination tree pane.
3. Click OK.

   The editor adds the predicate node immediately below the original node. The condition appears in brackets.

To Edit a Predicate

1. In the source tree pane, right-click the predicate node and choose Edit Predicate.
2. Modify the condition.
3. Click OK.

To Delete a Predicate

1. In the source tree pane, right-click the predicate node and choose Delete Predicate.
2. Click Yes.

XPath Function Reference

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: Operator, Boolean, String, Nodes, Number, Date & Time, and BPEL.

Operator

The Operator menu contains the following functions:

• Greater: Greater than.

• Greater or Equal: Greater than or equal to.

• Less: Less than.

• Less or Equal: Less than or equal to.

• Addition: Specifies an addition operation.

• Subtraction: Specifies a subtraction operation.

• Multiplication: Specifies a multiplication operation.

• Division: The operator returns the quotient for a given dividend and divisor.

• Remainder: The operator returns the remainder for a given dividend and divisor # Negative

• Negative

• Not Equal

• Equal

Boolean

The Boolean menu contains the following functions:

• Logical And: If both arguments are true, then the function returns true. If either argument is false, then the function returns false.

• Logical Or: If either argument is true, then the function returns true. If both arguments are false, then the function returns false.

• Logical Not: If the argument is false, then the function returns true. If the argument is true, then the function returns false.

• Language: 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.

• Logical False: Returns false.

• Logical True: Returns true.

• 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:

• 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.

• Last: Returns the context size.

• 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: Specifies 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.

Date & Time

The Date & Time menu contains the following functions:

• Current Date: Provides the current date.

• Current Time: Provides the current time.

• Current Date and Time: Provides the current date and time.

• Duration Literal: Specifies a duration literal. Use the format specified in the XML Schema specification.

• <Date/Time Less Than: Determines whether one specified DateTime is less than another specified DateTime.

• <Time Less Than: Determines whether one specified Time is less than another specified Time.

• <Date Less Than: Determines whether one specified Date is less than another specified Date.

BPEL

The BPEL menu contains the following functions:

• Do XSL Transform: This is an XPath extension function defined in WS-BPEL specification. It can be used in a BPEL Assign activity to call an XSLT transformation.

• Get Variable Property: Provides the property of the variable.

• Wrap with Service Reference: This is a special case of Do XSL Transform function used to transform data into Service

• Do Marshal: Performs serialization of an object.

• Do UnMarshal : Performs deserialization of an object.

• GUID: Provides the GUID Name.

• Get BP ID: Gets the Business Process Identification.

• XML Literal: Specifies an XML literal.

• Java: Specifies a Java method. The Java option allows you to call the classes and methods of your project JAR files and those of the projects Referenced Resources. When you select the Java option, the Choose Method dialog box appears listing the methods that you can call from BPEL.

Mapping Examples

These examples illustrate several mapping scenarios:

• Assign Activity Scenario

• If Activity Scenario

• Predicate Scenario

Assign Activity Scenario

Assume that you want a BPEL process to copy data received from a partner. Do the following tasks:

1. Add an Assign activity after the Receive activity.

2. Use the BPEL Mapper to define one or more copy assignments. To open the BPEL Mapper, double-click the Assign activity on the diagram or select the Mapper tab on the toolbar.

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.

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.

If Activity Scenario

Assume that you want to execute a series of steps only if a certain condition is true. Do the following tasks:

1. Add an If activity to the BPEL process.

2. Use the BPEL Mapper to define the Boolean condition. To open the BPEL Mapper, double-click the If activity on the diagram or select the Mapper tab on the toolbar.

3. 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 node on 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.

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:

1. In the left pane of the BPEL Mapper window, right-click the repeating node that is marked with an asterisk (*) and choose New Predicate.

   The Predicate Editor window appears.

2. Add the Less XPath function to the middle pane.

3. Add the number literal XPath function to the middle pane. Set the value to 3.

4. Map the variable node to the first argument of the Less XPath function.

5. Map the result of the number literal XPath function to the second argument of the Less XPath function.

6. Map the result of the Less Than XPath function to the Result node in the right pane.

7. 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.

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>

Using Type Cast and Pseudo-Components

Type Cast and Pseudo-components are provided to support type inheritance, help build message structure, and prevent validation errors. Type Casting addresses a problem in which a base complex type does not contain the same elements as the derived type.

For example, a variable may have a base type, containing two attributes and two elements, and a derived type inherited from the base type, containing an additional attribute and element.

When the message is declared in a WSDL for use in BPEL, the base type is used to declare the message. So, in this example, from the Mapper view of the XML structures we see the variable's base type that does not contain the additional element and attribute.

Since the Mapper is designed to allow you to graphically link elements and attributes, these structures need to be available in the mapper view. To allow mapping of derived type attributes and elements, which are implied by the base type, the Mapper enables you to cast an object to another type - in this example, to the derived type.

To cast an object to another type:

1. From the Mapper view of the project's BPEL file, right-click the variable that has the base type and click Cast To in the context menu. The Subtype Chooser appears displaying a tree with the original type as the root and subtypes under the root. If there are no subtypes, only the original type will appear in the box.

   

2. To cast the original variable to the derived type, select derivedType in the Subtype Chooser and click OK. The derivedType variable appears in the Mapper.

3. Expand the derivedType variable in the Mapper and note that the additional attribute and element are now available to use for mapping.

Type Cast

The Type Cast option allows you to explicitly cast an object to another type. This only works for objects that have a schema type.

In the BPEL Mapper the following object can be cast:

• Schema Element

• Schema Attribute

• Variable (except variables of the WSDL Message type)

• Message Part

Pseudo-Component

The Pseudo-component feature is similar to Type Cast. The XML Schema introduces xsd:any. It declares that an element can be located in the XML document and have any name and type. The BPEL mapper allows you to add to the tree elements, which correspond to xsd:any. Such elements don't appear in the schema, but they look similar to other elements. That is why they are called pseudo-elements. The user can map from and to a pseudo-element the same way as for an ordinary element. This also applies to the xsd:anyAttribute. The user can create pseudo-attributes to use for mapping and design purposes.

In the Mapper's Input and Output trees, xsd:any appears as an element node with the name "Any Element" and xsd:anyAttribute as an attribute with the name "Any Attribute". Both have the context menu item "Cast To...", which calls the special dialog box used to specify a name, namespace and type for the new pseudo-component. For xsd:any any global type can be chosen. For xsd:anyAttribute only the global simple types are suggested. In both cases the settings allow you to choose global types from several different sources. The completed pseudo-components appear in the tree with the name pattern (castToElementName)Any Element or (castToAttributeName)Any Attribute.

Type Cast and Validation

Validation is passive in regard to type casts and pseudo-components, meaning that validation does not object to an unknown component if it is a qualified type cast or it is declared as a pseudo-component.

Type Cast and Pseudo Component Limitations

The type cast is used to avoid runtime errors, but there are several reasonable limitations:

• An object of a specific schema type can be cast only to a subtype. This applies to elements, attributes, variables and message parts. The XML Schema has two derivations, extension and restriction, both of which are supported by type cast.

• xsd:any contains additional attributes which might restrict the possible element type.

• Only global types can be used when you declare a pseudo-component. Global attributes or elements cannot be used. The target of the type must be referenceable, and as such should be global.

• You cannot nest type casts, pseudo-components, and mixed declarations.

• You cannot add a new predicate to a cast component or its part.

• You cannot mix two or more type casts or pseudo components in an XPath expression. A type cast cannot be associated with a specific part of an expression, but only with the expression as a whole.