This section provides an introduction to using XML data in BPEL processes.
6.1.1 XML Data in BPEL
In a BPEL process service component, most pieces of data are in XML format. This includes the messages passed to and from the BPEL process service component, the messages exchanged with external services, and the local variables used by the process. You define the types for these messages and variables with the XML schema, usually in one of the following:
Web Services Description Language (WSDL) file for the flow
WSDL files for the services it invokes
XSD file referenced by those WSDL files
Therefore, most variables in BPEL are XML data, and any BPEL process service component uses much of its code to manipulate these XML variables. This typically includes performing data transformation between representations required for different services, and local manipulation of data (for example, to combine the results from several service invocations).
BPEL also supports service data object (SDO) variables, which are not in an XML format, but rather in a memory structure format.
6.1.2 Data Manipulation and XPath Standards
The starting point for data manipulation in BPEL is the assign activity, which builds on the XPath standard. XPath queries, expressions, and functions play a large part in this type of manipulation.
In addition, more advanced methods are available that involve using XQuery, XSLT, or Java, usually to do more complex data transformation or manipulation.
This section provides a general overview of how to manipulate XML data in BPEL. It summarizes the key building blocks used in various combinations and provides examples. The remaining sections in this chapter discuss and illustrate how to apply these building blocks to perform specific tasks.
You use the assign activity to copy data from one XML variable to another, or to calculate the value of an expression and store it in a variable. A copy element within the activity specifies the source and target of the assignment (what to copy from and to), which must be of compatible types.
Example 6-1 shows the formal syntax for BPEL version 1.1, as described in the Business Process Execution Language for Web Services Specification:
Example 6-1 Assign Activity for BPEL 1.1<assign standard-attributes> standard-elements <copy> from-spec to-spec </copy> </assign>
Example 6-2 shows the formal syntax for BPEL version 2.0, as described in the Web Services Business Process Execution Language Specification Version 2.0. The attribute specifies whether the element name of the destination (as selected by the ) is replaced by the element name of the source (as selected by the ) during the copy operation. When is set to (the default value), the name (that is, the namespace name and local name properties) of the original destination element is used as the name of the resulting element. When is set to , the source element name is used as the name of the resulting destination element.
Example 6-2 Assign Activity for BPEL 2.0<assign validate="yes|no"? standard-attributes> standard-elements ( <copy keepSrcElementName="yes|no"? ignoreMissingFromData="yes|no"?> from-spec to-spec </copy> . . . . . . </assign>
This syntax is described in detail in both specifications. The and typically specify a variable or variable part, as shown in Example 6-3:
Example 6-3 from-spec and to-spec Attributes<assign> <copy> <from variable="c1" part="address"/> <to variable="c3"/> </copy> </assign>
When you use Oracle JDeveloper, you supply assign activity details in a Copy Rules dialog that includes a From section and a To section. This reflects the preceding BPEL source code syntax.
XPath standards play a key role in the assign activity. Brief examples are shown here as an introduction; examples with more context and explanation are provided in the sections that follow.
An XPath query selects a field within a source or target variable part. The or clause can include a query attribute whose value is an XPath query string. Example 6-4 provides an example:
Example 6-4 query Attribute<from variable="input" part="payload" query="/p:CreditFlowRequest/p:ssn"/>
The value of the query attribute must be a location path that selects exactly one node. You can find further details about the attribute and XPath standards syntax in the Business Process Execution Language for Web Services Specification (section 14.3) or Web Services Business Process Execution Language Specification Version 2.0 (section 8.4), and the XML Path Language (XPath) Specification, respectively.
You use an XPath expression (specified in an attribute in the clause) to indicate a value to be stored in a variable. For example:<from expression="100"/>
The expression can be any general expression (that is, an XPath expression that evaluates to any XPath value type). Similarly, the value of an expression attribute must return exactly one node or one object only when it is used in the clause within a copy operation. For more information about XPath expressions, see section 9.1.4 of the XML Path Language (XPath) Specification.
Within XPath expressions, you can call the following types of functions:
Core XPath functions
XPath supports a large number of built-in functions, including functions for string manipulation (such as ), numeric functions (like ), and others.<from expression="concat('string one', 'string two')"/>
For a complete list of the functions built into XPath standards, see section 4 of the XML Path Language (XPath) Specification.
BPEL XPath extension functions
BPEL adds several extension functions to the core XPath core functions, enabling XPath expressions to access information from a process.
For BPEL 1.1, the extensions are defined in the standard BPEL namespace and indicated by the prefix :<from expression= "bpws:getVariableData('input', 'payload', '/p:value') + 1"/>
For more information, see sections 9.1 and 14.1 of the Business Process Execution Language for Web Services Specification. For more information about , see Section B.2.60.2, "getVariableData."
For BPEL 2.0, the extensions are also defined in the standard BPEL namespace . However, the prefix is :<from>bpel:getVariableProperty('input', 'propertyName')</from>
For more information, see section 8.3 of the Web Services Business Process Execution Language Specification Version 2.0. For more information about , see Section B.2.60.4, "getVariableProperty (For BPEL 2.0)."
Oracle BPEL XPath extension functions
Oracle provides some additional XPath functions that use the capabilities built into BPEL and XPath standards for adding new functions.
These functions are defined in the namespace and indicated by the prefix .
Oracle BPEL Process Manager functions are defined in the and placed inside the file. For more information, see Section B.7, "Creating User-Defined XPath Extension Functions" and Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite.
Sophisticated data manipulation can be difficult to perform with the BPEL assign activity and the core XPath functions. However, you can perform complex data manipulation and transformation by using XSLT, Java, or a operation under an assign activity (See Section 6.14, "Manipulating XML Data with bpelx Extensions") or as a web service. For XSLT, Oracle BPEL Process Manager includes XPath functions that execute these transformations.
For more information about XPath and XQuery transformation code examples, see Chapter 37, "Creating Transformations with the XSLT Mapper."
Note:Passing large schemas through an assign activity can cause Oracle JDeveloper to freeze up and run low on memory if you right-click the target or source payload node in the Edit Assign dialog and select Expand All Child Nodes. As a workaround, manually expand the payload elements.
These faults are defined within the WS-BPEL specification. All standard fault names are qualified with the standard WS-BPEL namespace.
|This fault is thrown||When...|
|ambiguousReceive||A business process instance simultaneously enables two or more inbound message activities (IMAs) for the same partnerLink, portType, and operation but different correlation sets, and the correlations of multiple of these activities match an incoming request message.|
|completionConditionFailure||A directly enclosed Scope activity within a forEach activity completes and it is determined that the completion condition can never be true.|
|conflictingReceive||More than one inbound message activity (IMA) is enabled simultaneously for the same partner link, port type, operation and correlation sets.|
|conflictingRequest||More than one inbound message activity (IMA) is open for the same partner link, operation and message exchange.|
|correlationViolation||The messages contents processed in an Invoke, Receive, Reply, onMessage, or onEvent don't match the specified correlation information.|
|invalidBranchCondition||The integer value used in the Branches completion condition of a forEach is larger than the number of directly enclosed Scope activities.|
|invalidExpressionValue||An expression used within a WS-BPEL construct (except an Assign) returns an invalid value with respect to the expected XML Schema type.|
|invalidVariables||An XML Schema validation (implicit or explicit) of a variable value fails.|
|joinFailure||The join condition of an activity evaluates to false and the value of the suppresJoinFailure attribute is yes.|
|mismatchedAssignmentFailure||Incompatible types or incompatible XML infoset structure are encountered in an Assign activity.|
|missingReply||An IMA is executed and the Process or Scope instance reaches the end of its execution without a corresponding Reply activity executing.|
|missingRequest||A Reply activity cannot be associated with an open inbound message activity by matching the partner link, operation and message exchange tuple.|
|scopeInitializationFailure||There is any problem creating any of the objects defined as part of Scope initialization. This fault is always caught by the parent Scope of the faulted Scope.|
|selectionFailure||A selection operation performed either in a function such as bpel:getVariableProperty, or in an assignment, encounters an error.|
|subLanguageExecutionFault||The execution of an expression results in an unhandled fault in an expression language or query language.|
|uninitializedPartnerRole||An Invoke or Assign activity references a partner link whose partnerRole endpoint reference is not initialized.|
|uninitializedVariable||There is an attempt to access the value of an uninitialized variable, or in the case of a message type variable, one of its uninitialized parts.|
|unsupportedReference||A WS-BPEL implementation fails to interpret the combination of the reference-scheme attribute and the content element OR just the content element alone.|
|xsltInvalidSource||The transformation source provided in a bpel:doXslTransform function call is not legal.|
|xsltStylesheetNotFound||The named style sheet in a bpel:doXslTransform function call is not found.|