Using the BPEL Export Tool

This section describes how to use the BPEL Export tool in BEA Workshop for WebLogic^®, to export BPEL 1.1 compliant code from a JPD file.

Topics Included in This Section

Introduction to BPEL

BPEL Export Tool

Exporting a BPEL File to JPD

Known Limitations and Issues

Introduction to BPEL

BPEL4WS (Business Process Execution Language for Web Services, commonly referred to as "BPEL") defines a language for the formal specification of automated business processes. Processes written in BPEL can orchestrate interactions between Web services using XML documents in a standardized manner. These processes can be executed on any platform or product that complies with the BPEL specification. BPEL therefore enables customers to protect their investment in process automation by allowing them to move these process definitions between a wide variety of authoring tools and execution platforms. While there have been previous attempts to standardize business process definitions, BPEL has attracted an unprecedented level of interest and is the first to gain critical mass among software vendors.

BPEL4WS 1.1 is the latest published specification from BEA, Microsoft^®, and IBM^®, but it does not reflect the upcoming BPEL standard, which is still under development by the OASIS standards organization. It is important to bear in mind that the final standard will be different from BPEL4WS 1.1, and therefore this tool is provided largely to enable design-time interoperability with other tools that support the 1.1 specification.

For more information on the BPEL language, refer to the BPEL4WS specification v1.1, published by BEA, IBM, and Microsoft and submitted to OASIS for standardization, which is available at:

and the official Home page for the BPEL standardization effort, hosted by OASIS at:

In BEA WebLogic Integration™, a business process is defined using BEA Process Definition for Java (JPD). The BPEL export tool is a design-time aid to help convert a JPD file into a BPEL file.

BPEL Export Tool

You can use the BPEL Export tool to export the semantics of a JPD file into BPEL where it can be used in a BPEL design environment. BPEL code that is exported using the BPEL Export tool is BPEL 1.1 compliant and can be used in design environments compliant with BPEL 1.1. While the main orchestration logic of the JPD is exported to BPEL, it is not expected that the exported BPEL will be immediately executable in the target environment. You will need to manipulate the BPEL in the target environment to get the exported process to run, or to get close to the run-time semantics.

This is due to the fact that some executable call-outs from the JPDs will be opaque to the exported BPEL code. These executable units generally include controls, code written in perform nodes, and XQuery transformations. The BPEL Export tool copies the Java code and the XQuery code as extension nodes in BPEL. As a result, you must re-implement the logic in the target BPEL environment, since JPD provides a superset of the functionality provided by BPEL.

One Web Service Definition Language (WSDL) file defines the WSDL interface of the business process and defines a partner-link type for the interface. The other file defines the WSDL interface and partner-link types of the partners. Partners are the artifacts interacting with the business process. These artifacts are either consumers or providers of services to the business process.

These WSDL files are not the same as the WSDL that BEA Workshop for WebLogic would generate for the corresponding JPD or JCX files. The differences are described in detail in Known Limitations and Issues on page 2-9.

The relevant XSD schema files (which must be located in a schema folder in the WebLogic Integration application) are needed in the target environment, along with the WSDL and BPEL files.

Exporting a BPEL File to JPD

In BEA Workshop for WebLogic, right click on a JPD file in the Package Explorer pane. For example, in Figure 2-1, right click on Process.java Export.

Figure 2-1 JPD Location

JPD Location

The Export pane appears. Select BPEL Process from JPD and click Next to proceed as shown in Figure 2-2.

Figure 2-2 BPEL Export Selection

BPEL Export Selection

Choose the destination directory where the BPEL Export tool will create BPEL and WSDL files as shown in Figure 2-3.

Figure 2-3 BPEL Export Pane

BPEL Export Pane

Select Finish to complete the export process. You can view the progress of the export as shown in Figure 2-4.

Figure 2-4 Progress of BPEL Export

Progress of BPEL Export

When the export is complete, the BPEL Export log displays the message Done! as shown in the lower right hand corner of Figure 2-5.

Figure 2-5 Generated Files

Generated Files

You can view the log containing the complete details of the export as shown in Figure 2-6. This log also tells you if the export was successful or not. The logs are located in %workspace%/.metadata where workspace refers to where the WebLogic Process application resides.

Figure 2-6 Export log

Export log

Known Limitations and Issues

This section provides some notes on the export process and details some known limitations of the BPEL Export tool.

Limitations While Importing WebLogic Integration 9.2 Generated BPEL Files Into AquaLogic Business Process Management

The default expression language for the exported BPEL is XQuery 2002. Specifically, the version of the XQuery specification described in Working Draft 16 from August 2002 which is available at:

http://www.w3.org/TR/2002/WD-xquery-20020816

While importing into AquaLogic Business Process Management, replace this with expressionLanguage which is available at:

http://www.w3.org/TR/1999/REC-xpath-19991116

XQuery expressions in the JPD file are copied `as is' into the expression attributes of the corresponding BPEL activity. XQuery code referenced in a Data Transformation control is copied into the JPD namespace xqueryCode element. The Java code is copied into the <jpd:javacode> node as a BPEL extension. AquaLogic Business Process Management does not validate these elements.

The activity names in generated BPEL may contain additional values such as., <receive name="Client-Request" jpd:name="Client Request" ... /> which fail to get validated in AquaLogic Business Process Management.
AquaLogic Business Process Management does not allow <scope/> to be the first activity in a BPEL process.
The input variable of a reply node is expected to be of XML type in AquaLogic Business Process Management .

Other Known Limitations

Process variables in a JPD file are converted to variables in the outermost scope of the BPEL file. int, short, long, byte, float, boolean, double, String, java.util.Date, and java.util.Calendar are converted to the corresponding schema built-in types. XMLBean types are converted to the corresponding XML Schema type. A wrapper element type is introduced for complex types, BPEL variables cannot have a complex type as their type. Any other types (including temporary transform variables) are converted to an element type with no type attribute.
Controls are exported as partner-links. The operations for this partner-link are derived from the methods in the control JCX file. Each method parameter is treated as a separate input message part; the name of the part is the same as the name of the parameter. The output message is determined from the return type of the control method. It has a single part called parameters, since a method has a single return type with no name.
XQuery expressions in the JPD file are copied `as is' into the expression attributes of the corresponding BPEL activity. XQuery code referenced in a Data Transformation control is copied into the JPD namespace xqueryCode element.
Before and after transformation, send or receive messages are exported to assign activities before or after the corresponding invoke, reply, or receive activities.

Table 2-1 details how various JPD file attributes, nodes, and so on are converted to a BPEL file.

Table 2-1 JPD File to BPEL File Conversion
In the JPD file	converted to in a BPEL file
`clientRequest` and `controlReceive` nodes	`receive` activity
`clientCallback` and `controlSend` nodes	`invoke` activity
synchronous `returnMethod` attribute	`reply` activity
`onMessage` paths	`onMessage` event handlers
`onTimeout` paths	`onAlarm` event handlers
`eventChoice` node	`pick` activity
`Parallel` node	`flow` activity
`onException` blocks	`faultHandlers`
`perform` node	`empty` activity with the java code from the `perform` method copied into the body of a JPD namespace javaCode element
control flow nodes: `decision` `switch` `forEach` `doWhile` `whileDo`	to the equivalent BPEL activities.

Any warning messages that are generated during the export process do not include an exact line number reference of the original JPD file.
Constants declared in a JPD file are captured in the BPEL file as jpd:initialValue.
When you export a JPD file that contains a Service Broker control, the shape of the process and control WSDLs are derived from the JPD file and are different from the JPD WSDL.
Any methods which are not directly associated with a JPD node are lost during the export.
If a converted control (service or process) produces a method with a void return, there are two possible causes:

the corresponding operation has no output message.
the operation has an output message with no parts.

The BPEL Export tool does not distinguish between the two cases and always assumes that the first case is true.

User schemas are referenced by a xsd:include element. If the types used are in a WSDL file, it is exported using wsdl:import.
If the schemas folder is created with the default name, all XSD files placed in the top level directory of this folder will be referenced by an absolute file URL. For all other XSD files, just the filename is referenced.
If a JPD file contains ArrayList or another Collection class's add() method, a non-standard JPD namespace attribute jpd:appendToCollection is generated with its value set to true.
If MFL types are used in the JPD file, they are converted to a dummy empty type. A warning to this effect is emitted. The warning message is: MFL types are not supported for export. Creating an empty element type for <type>.
Assign statements are generated to assign global variables to and from Web service messages. However, if the Web service message does not have any part defined, no assign statement is generated.
Service controls are treated as generic Java controls. The original WSDL file for the Service control is not used in the export.
afterExecute=resume is not supported for the following paths:

OnTimeout
OnException
OnMessage

freezeOnFailure=true, onSyncFailure, and persistent are not supported.
executeOnRollback is not supported for OnException path.
Transaction blocks are converted into a scope with BPEL extension jpd:transaction set to true.
XQuery transformations are copied into the <jpd:xquerycode> node as a BPEL extension.
During the export process, Java code is copied into the <jpd:javacode> node as a BPEL extension.
Message Broker subscriptions are exported as partner links. The message broker channel name and subscription filter are not included in the export.
Perform nodes are exported as an empty activity. Java code is included as a <jpd:javacode> extension.
Attribute information for controls in the JCX file or before the control declaration are lost. For example, for Message Broker controls, the channel name and subscription filters are not copied into the exported BPEL or WSDL files.
When process variable names, control file names (such as .dtf, .jcs), control method names, parameters used in control methods, variable names defined for controls, and .jpd file names that contain special character like $ are exported to.bpel files, these names are used as is in the "name" attribute of "variable" and "variable" attribute of "to". Since BPEL schema defines these attributes as NCName type, these special characters become invalid in the generated.bpel file. However, this limitation is no longer valid for the $ character. For any other special character (that is not valid NCName or QName type), althought the .bpel file is generated, schema validation of the file fails.

Workaround: The generated .bpel file needs to be manually modified by using valid characters.

BPEL Import and Export User Guide

Using the BPEL Export Tool

Topics Included in This Section

Introduction to BPEL

BPEL Export Tool

Exporting a BPEL File to JPD

Known Limitations and Issues

Introduction to BPEL

BPEL Export Tool

Exporting a BPEL File to JPD

Known Limitations and Issues

Limitations While Importing WebLogic Integration 9.2 Generated BPEL Files Into AquaLogic Business Process Management

Other Known Limitations