BPEL Import and Export User Guide

Using the BPEL Export Tool

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

Topics Included in This Section

Introduction to BPEL

Provides a brief background on BPEL and how it evolved.

BPEL Export Tool

Provides an overview on how the BPEL Export tool works.

Exporting a BPEL File to JPD

Describes how to export a BPEL file using WebLogic Workshop.

Known Limitations and Issues

Provides information on the export 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 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 exported using the BPEL Export 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 WebLogic Workshop would generate for the corresponding JPD or JCX files. The differences are described in detail in Known Limitations and Issues on page 2-5.

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

To Export a JPD

In WebLogic Workshop, right click on a JPD file in the Application pane. For example, in the following figure, right click on RequestQuote.jpd.

Figure 2-1 JPD Location

JPD Location

Select Export Bpel.

Figure 2-2 BPEL Export Selection

BPEL Export Selection

When you select Export Bpel, a BPEL Export pane appears below the Design View and displays diagnostic messages about the export process.

Figure 2-3 BPEL Export Pane

The BPEL Export tool will create files, RequestQuote.bpel and RequestQuote.wsdl, in the same directory as the RequestQuote.jpd. Another WSDL file RequestQuotel_ctrl.wsdl may also be created, as shown in the following figure.

Figure 2-4 Generated Files

Generated Files

Known Limitations and Issues

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

Notes

The section details information that you should remember when using the BPEL Export tool.

The default expression language for the exported BPEL is XQuery. 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
This is the same version of XQuery used by WebLogic Integration 8.1.

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.

The following table 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.

Known Limitations

This section details some of the known JPD export limitations.

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 (.dtf, .jcs and so on), 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.