BPEL Import and Export User Guide

Using the BPEL Import Tool

This section describes how to use the BPEL Import tool in WebLogic Workshop^® to import a BPEL file.

Topics Included in This Section

Introduction to BPEL

Provides a brief background on BPEL and how it evolved.

BPEL Import Tool

Provides an overview on how the BPEL Import tool works.

Importing a BPEL File

Describes how to import a BPEL file using WebLogic Workshop.

Known Limitations and Issues

Provides information on the import tool that will enable you to use is more effectively and efficiently.

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:

http://dev2dev.bea.com/webservices/BPEL4WS.csp

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

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbpel

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

BPEL Import Tool

You can use the BPEL Import tool to import a BPEL file into a JPD file, where it can be used in the WebLogic Workshop design environment. While the main orchestration logic of the BPEL file is imported into a JPD file, it is not expected that the imported JPD file will be immediately executable in WebLogic Workshop. You will need to manipulate the JPD file in WebLogic Workshop to get the imported process to run.

In certain cases, runtime semantics are not guaranteed, due to the functional mismatches between the JPD and BPEL languages, or between various expression languages including differences between XQuery, Xpath, and XSLT. Runtime semantics are also not guaranteed when they involve vendor extensions, external artifacts, or environment settings. For the above reasons, the imported JPD file should be reviewed and tested with any required changes that were made to ensure that it runs properly.

In general, the BPEL Import tool expects complete BPEL and WSDL artifacts as input. To some extent, the tool also handles incomplete BPEL and WSDL artifacts, so that in-progress BPEL files can be imported as JPD, and then completed in the WebLogic Integration environment. Incomplete cases are numerous and may include missing WSDL files, missing type definitions, missing port type definitions, or incomplete constructs of <while>, <switch>, <invoke>, <receive>, <reply>, <onMessage>, <onAlarm>, <throw>, as well as other cases. If the BPEL Import is not able to import the input artifacts into a JPD file, error messages appear that enable you to correct the input artifacts for future imports.

Importing a BPEL File

To Import a BPEL File to a JPD File

In WebLogic Workshop, create or open a Workshop application.

Open the folder under the project root to which you want to import the BPEL file. For example, processes in the following figure.

Figure 1-1 Location for Imported File

Location for Imported File

Note: The BPEL Import tool does not support importing to Schemas/Project root directories. If you try to import into a root directory, you get the following error message.

Figure 1-2 Error Message

Error Message

Select Tools—>WebLogic Integration—>Import BPEL from the WebLogic Workshop menu.

Figure 1-3 Import BPEL Option

Import BPEL Option

The Select BPEL Source window appears. Figure 1-4 Select BPEL Source Window

Locate the BPEL file that you want to import.

Figure 1-5 File To Import

File To Import

Highlight the required BPEL file and click Open.

The next step is specifying the location of the folder containing the Web Services Description Language (WSDL) files. Figure 1-6 WSDL Location

Select the required folder and click Open. The BPEL Import tool will pick up all WSDL and XSD files in the selected folder.

The import begins and the progress of the import is shown in the BPEL Import pane below the Design pane, as shown in the following figure.

Figure 1-7 BPEL Import Pane - Conversion Successful
If the conversion is not successful, the conversion is aborted and error messages are displayed in the BPEL Import pane, as shown in the following figure.

Figure 1-8 BPEL Import Pane - Conversion Failed
In the BPEL Import pane:

All warning messages are shown in green.
If the import is successful, the following message appears in black: BPEL Import SUCCESSFUL.
If the import fails, the following warning message appears in red: BPEL Import Failed.

Note: The Build pane below the Design pane displays diagnostic messages about the schema import process as shown in the following figure.

Figure 1-9 Build Pane - Schema Diagnostic Messages

Build Pane - Schema Diagnostic Messages

Note: A log file for the import process, named BpelImport.log, is stored in %BEA_HOME%\weblogic81\workshop where %BEA_HOME% is the directory in which you installed WebLogic Workshop. This log file provides information about the import process.

The new JPD file appears in the folder specified in step 2 and the WSDL files are copied and placed in the Schemas folder, as shown in the following figure. Figure 1-10 New JPD and WSDL Files

This completes the import process and your new JPD file is located in the folder specified in step 2.

Known Limitations and Issues

This section details some known limitations and issues of the BPEL Import tool. The majority of these issues exist because of the inherent differences between the JPD and BPEL languages.

It is very important that you confirm that the generated JPD file corresponds semantically with the input BPEL file.

Conversion of Compensation Handlers is not supported. If you try to convert a BPEL file that contains Compensation Handlers, a warning appears stating that Compensation Handlers are not supported and are ignored in the generated JPD file. The conversion process will continue after this warning is displayed.
Global eventHandler is not supported. If it is included in the BPEL file, it is ignored during the conversion process and the following message appears: Global EventHandlers are not supported, hence ignored.
Conversion of wait and onAlarm for which the duration is specified using the until attribute is not supported. If the until attribute is contained in the BPEL file, a warning appears stating that it is not supported and is ignored in the generated JPD file. The conversion process will continue after this warning is displayed.

Note: Both attributes (for and until) cannot be specified in a valid BPEL file.

A BPEL file that starts with a flow is not supported. You cannot convert a BPEL file that has a flow construct as a first logical child. In this instance, logical activity refers to any activity other than sequence and scope.
Conversion of links from activity flow is not supported. If links are present in the BPEL file that you want to convert, a warning appears stating that the generated JPD file may be erroneous as it contains links, source, target. The conversion process will continue and will ignore these unsupported activities.
Conversion of a BPEL file in which more than one reply activity is used to return normal output/outcome is not supported. In order to qualify for conversion, a BPEL file must only contain one reply activity to return a normal outcome. This is due to the fact that in a JPD file, there can only be one returnMethod for any synchronous clientReceive. However, in a BPEL file, there can be several reply activities for a single receive. There is no direct way to map one receive and several reply nodes to a single clientRequestWithReturn.
A pick activity with more than one OnAlarm activity is not supported for conversion. This is due to the fact that pick gets converted to eventChoice. Each eventChoice can have at most one timeoutEvent node, which is generated for an onAlarm activity.
Specifying the for attribute of onAlarm activity using bpws:getVariableData(..) is not supported. When a for attribute is specified using bpws:getVariableData(..), the imported code produces a syntax error.
If the import fails with the following message: WARNING: Failed to parse input XSD & WSDL files. Please see logs for detail, and the log file contains the following error message: Duplicate global type, you should specify that multiple definitions of the namespace are ignored.

The log file for the import process, named BpelImport.log, is stored in %BEA_HOME%\\weblogic81\workshop where %BEA_HOME% is the directory where you installed WebLogic Workshop. This log file provides information about the import process.
To specify that multiple definitions of the namespace are ignored, select Schema Project—> Properties—>Build and list the namespaces to be ignored in the ignore multiple definitions in following namespaces field.

Limited query parsing is performed when assign activities are imported. Therefore, the generated XQuery expressions might not always be syntactically correct. Make sure that you check to verify the correctness of any generated XQuery expressions.
Any reference to soapencoding types in your BPEL file will result in import failure. If you want to import a BPEL file that contains soapencoding types, you must place the SOAP Encoding xsd file in the WSDL directory when importing through WebLogic Workshop.
When assign is converted to a variable, the resultant XQuery file may contain the following "PARSE ERROR" in the Design view: The main XML element does not match the root node of the target schema. However, you can ignore this message as the correct value is generated in runtime. This error is due to the fact that the Design view of XML Mapper has limitations and might not always be able to parse even correct XQuery expressions.
After you import a BPEL file that contains scope level eventHandlers in the onMessage branch, a dummy Timer method may be generated for the eventHandler onMessage path. JPD specification mandates that onMessage and onTimeout paths can only be associated with process nodes (or block of nodes) that do not run automatically. To handle this constraint, a dummy Timer node with a 1 second timeout is created if an eventHandler is associated with a scope that does not contain any receive, onMessage, flow, or wait activity.
When a BPEL file is imported, queries are not parsed, they are imported `as is'. You must properly qualify the query string or the generated XQueries will fail at runtime, by setting the attributeFormDefault="qualified" and elementFormDefault="qualified" and then using the qualified query string.
A BPEL file may have reply activities on multiple partner links. This is not supported in a JPD file. Only one such partnerlink will be converted as clientRequestWithReturn that matches the reply semantics. reply activities on other partnerlinks will be converted into an asynchronous interface.
BPEL Event Handlers are translated to JPD onMessage paths which have slightly different semantics. In the imported JPD file, once the event is received and the onMessage path is executing, the block (corresponding to the BPEL scope) does not continue executing until the onMessage path completes. This also means that only one instance of an Event Handler can be active at any one time.
In the imported JPD file, Event Handlers will not be triggered while waiting for the response of a synchronous Web service.
The BPEL Import tool converts BPEL invoke activities to Web Service controlSend calls. It generates a Web Service control for the specified partner service and the JPD file invokes the corresponding method on the control. This release has some limitations in its capability to generate a Web Service control (a JCX file) in certain situations. You should carefully examine the contents of the generated JCX file to ensure that you can compile it.
If the input WSDL file does not have any bindings and service information for any portTypes, the BPEL Import tool tries to generate a method for each portType with some default values for the binding and service information. You should review these default values carefully. You should provide valid binding and service information after the import.
The JPD file generated from BPEL processes that contain <reply> in Switch, Case, o Otherwise nodes may not be logically correct. This is because the matching receive and reply of the synchronous operation are not present at the same level.
BPEL allows event handlers to be associated with any arbitrary activities. However, a JPD file does not support cases where event handlers are associated with any node inside a <receive> - <reply> block. In such a scenario, the generated JPD may not compile.