Developer Guide to BPEL Designer: The WSDL Editor

Last Updated: 23 October 2006
Contributed and maintained by Jeff Stein

Contents

Developer Guide to BPEL Designer


About the WSDL Editor

The WSDL Editor enables you to edit Web Services Description Language (WSDL) files. WSDL is an XML-based language for describing web services. A WSDL file contains information about the functionality of the web service, as well as information about how to access the web service. The editor supports version 1.1 of the WSDL specification.

In a BPEL Module project, you use WSDL files to define the interfaces for business processes and their partner services.

You can create a WSDL file from scratch, or based on an existing WSDL file.

The WSDL Editor provides a Source view and a WSDL view.

A WSDL file has the following major elements: data types, messages, port types, bindings, and services.

major elements

You can add the following BPEL extensibility elements to a WSDL file: partner link types, properties, and property aliases.

extensibility elements

The WSDL Editor includes a validation tool. The validation tool reviews the WSDL file for problems with syntax and semantics. The Output window displays any errors or warnings.

top


Creating a WSDL File

When you create a WSDL file, you must choose one of the following approaches:

The output from the wizard is a well-formed, valid WSDL file that contains an interrelated set of elements, including the necessary messages, one port type (with its corresponding partner link type), one binding, and one service. You can modify the file afterward by using the WSDL Editor.

To create a WSDL file from scratch:

  1. In the Projects window, right-click the Process Files folder and choose New > WSDL Document.
  2. In the Name and Location wizard page, do the following:
    1. Supply a name for the file. You cannot enter a name that already exists in the project.
    2. (Optional) Change the default folder by clicking Browse and selecting the new folder.
    3. Enter the target namespace for the WSDL file. The target namespace will appear in the root element.
    4. Specify any XML Schema files that you want to import.
    5. Click Next.
  3. In the Abstract Configuration wizard page, do the following:
    1. Supply a name for the port type.
    2. Supply a name for the operation.
    3. Select the category of operation.
    4. Depending on the category of operation, you supply message information for the input, the output, or both the input and output. Each message contains one or more logical parts. The Add and Remove buttons enable you to add and remove message parts.
    5. (Optional) If the category of operation is Request-Response or Solicit-Response, then you can supply message information for a fault.
    6. Click Next.
  4. In the Concrete Configuration wizard page, do the following:
    1. Supply a name for the binding.
    2. The binding subtype options indicate how to translate the binding to a SOAP message. If your settings for message parts and the binding subtype do not conform to the WS-I Basic Profile, an error message appears at the bottom of the wizard page.
    3. Supply a name for the service.
    4. Supply a name for the port.
    5. Click Finish.
    The WSDL file is created. The WSDL Editor appears in WSDL view.

To create a WSDL file based on an existing WSDL file:

  1. In the Projects window, right-click the Process Files folder and choose New > File/Folder.
  2. In the Choose File Type wizard page, do the following:
    1. In the Categories list, select the XML node.
    2. In the File Types list, select the External WSDL Document(s) node.
    3. Click Next.
  3. In the Specify Resource Location wizard page, do one of the following:
  4. The WSDL file is created. The WSDL Editor appears in WSDL view.

top


Views in the WSDL Editor

The WSDL Editor provides a Source view and a WSDL view. The WSDL Editor toolbar has two buttons that you can use to access the different views.

Source View

In the Source view, the underlying XML source code appears. You can directly edit the XML.

The top of the Source Editor has a tab for each open document. Each tab shows the name of the document. If the document has been modified and has not been saved, then an asterisk (*) appears after the name. You can access various commands by right-clicking a tab.

A toolbar is located at the top of the Source Editor window.

Source code displayed in the Source Editor is syntactically colored.

The Source Editor status line is located beneath the horizontal scroll bar. To toggle between insert mode and overwrite mode, use the Insert key.

WSDL View

In the WSDL view, you use GUI components to configure the elements and attributes of the WSDL file.

The WSDL view has two subviews: tree view and column view. To switch between the subviews, use the buttons in the WSDL Editor toolbar.

switching
from tree view to column view

Some component nodes allow you to add extension attributes. In the Add Extension Attribute dialog box, you can specify the name and namespace. Once you add the attribute, you can specify the value from the Properties window. These component nodes also allow you to remove extension attributes.

If you right-click a component node and choose Go To Source, then the Source view appears with the cursor positioned at the beginning of the component's block.

You can perform refactoring:

You can also rename a component by changing the value of the Name property. The WSDL Editor renames all occurrences in the same file, but not in other files.

top


Configuring WSDL File Components

This section describes how to configure the root element of the WSDL file, how to add documentation to any element, and how to import XML schemas and WSDL files.

Configuring the Root Element

The root element contains properties for the name of the WSDL file, the target namespace, the default namespace, and namespace prefixes.

To configure the root element:

  1. In the WSDL view, select the root node.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Edit the name, target namespace, and default namespace as necessary.
  4. Edit the values of the namespace prefixes as necessary.

Adding Documentation

You can add documentation to any element in the WSDL file.

To add documentation:

  1. In the WSDL view, right-click an element and choose Add > Documentation.
    A documentation node appears.
  2. Select the documentation node.
  3. If the Properties window is not visible, choose Window > Properties.
  4. Enter the documentation text.

Importing XML Schemas and WSDL Files

You can use the WSDL Editor to import an XML schema file or another WSDL file that is part of your project.

To import an XML schema:

  1. In the WSDL view, right-click the root node and choose Add > Import Schema.
    The Import Customizer dialog box opens.
  2. In the Location list, expand the By File or By Namespace nodes to navigate to and select the XML schema file.
    The Namespace field below the Location list is filled in by the IDE.
  3. (Optional) In the New Prefix field, type the prefix that you want to use.
  4. Click OK.

To import another WSDL file:

  1. In the WSDL view, right-click the root node and choose Add > Import WSDL.
    The Import Customizer dialog box opens.
  2. In the Location list, expand the By File or By Namespace nodes to navigate to and select the WSDL file.
    The Namespace field below the Location list is filled in by the IDE.
  3. (Optional) In the New Prefix field, type the prefix that you want to use.
  4. Click OK.

top


Configuring WSDL Data Types

The WSDL Editor provides support for the built-in simple types in W3C XML Schema. The built-in simple types include such types as string, date, and integer.

You can define your own data types by adding an inline schema. The WSDL Editor allows you to configure one or more global properties and to define the structure.

To add an inline schema:

To configure the global properties of the inline schema:

  1. If the Properties window is not visible, choose Window > Properties.
  2. Select the inline schema node.
  3. You can perform one or more of the following optional tasks:

To define the structure of the inline schema:

top


Configuring WSDL Messages

You can use the WSDL Editor to create messages.

In a WSDL file, a port type contains one or more related operations that the web service can perform. An operation receives a message, sends a message, or does both.

Each message must contain one or more logical parts. For each part, you must specify the name and the type of content.

If you change the name of a message or part, then the WSDL Editor renames all occurrences in the same file. To rename all occurrences in associated XSD, WSDL, and BPEL files as well, right-click the component node and choose Refactor > Rename.

To create a message:

To change the name of a message:

  1. If the Properties window is not visible, choose Window > Properties.
  2. Select the message node.
  3. Set the Name property to the new name.

To change the properties of a part:

  1. If the Properties window is not visible, choose Window > Properties.
  2. Select the part node.
  3. Set the Name property to the new name. Be sure to enter a descriptive name, such as searchInput or resultOutput.
  4. The Element or Type property specifies the type of content. To set the value, click the ellipsis (...) button. The Element or Type dialog box enables you to select any of the built-in types in W3C XML Schema. If you added an inline schema or imported a schema, then you can select a type from the schema.

To add a part to an existing message:

To remove a message or part:

top


Configuring WSDL Port Types

You can use the WSDL Editor to create port types. In addition, you can use the WSDL Editor to add operations to an existing port type.

In a WSDL file, a port type contains one or more related operations that the web service can perform. An example of an operation is GetQuote.

The WSDL 1.1 specification defines the following categories of operations:

Each message contains one or more logical parts. For each part, you must specify the name and the type of content.

If you change the name of a port type or operation, then the WSDL Editor renames all occurrences in the same file. To rename all occurrences in associated XSD, WSDL, and BPEL files as well, right-click the component node and choose Refactor > Rename.

To create a port type:

  1. In the WSDL view, right-click the Port Types node and choose Add Port Type.
    The Create New Port Type dialog box appears.
  2. Supply a name for the port type.
  3. Supply a name for the operation.
  4. Select the category of operation.
  5. Depending on the category of operation, you supply message information for the input, the output, or both the input and output. You can create a message from scratch by entering a new message name, or you can select an existing message. For a new message, the Add and Remove buttons enable you to add and remove message parts.
  6. (Optional) If the category of operation is Request-Response or Solicit-Response, then you can supply message information for a fault.
  7. Click OK.
    A port type node appears. The port type node contains an operation node. If you created one or more messages, then the message nodes appear. In addition, a partner link type is automatically generated.

To add an operation to an existing port type:

  1. In the WSDL view, right-click the port type node and choose Add Operation.
    The Create New Operation dialog box appears.
  2. Supply a name for the operation.
  3. Select the category of operation.
  4. Depending on the category of operation, you supply message information for the input, the output, or both the input and output. You can create a message from scratch by entering a new message name, or you can select an existing message. For a new message, the Add and Remove buttons enable you to add and remove message parts.
  5. (Optional) If the category of operation is Request-Response or Solicit-Response, then you can supply message information for a fault.
  6. Click OK.
    An operation node appears. If you created one or more messages, then the message nodes appear.

To change the name of a port type:

  1. If the Properties window is not visible, choose Window > Properties.
  2. Select the port type node.
  3. Set the Name property to the new name.

To change the properties of an operation:

  1. If the Properties window is not visible, choose Window > Properties.
  2. Select the operation node.
  3. Set the Name property to the new name.
  4. If you want to specify the parameter order of an operation, set the Parameter Order property accordingly.

To remove a port type or operation:

top


Configuring WSDL Bindings

You can use the WSDL Editor to create bindings. In addition, you can modify bindings that were generated by the New WSDL Document wizard.

In a WSDL file, a binding defines message format and protocol details for a port type.

You can bind the binding to the SOAP 1.1 protocol. The binding contains a SOAP binding node and one or more operations. Each operation can contain the following elements:

If you change the name of a binding, then the WSDL Editor renames all occurrences in the same file. To rename all occurrences in associated XSD, WSDL, and BPEL files as well, right-click the binding node and choose Refactor > Rename.

Creating a Binding and Service From a Port Type

You can quickly create a binding and a service from an existing port type. If you want to modify the binding afterward, then see the appropriate steps in Creating a Binding.

To create a binding and service from a port type:

  1. In the WSDL view, right-click the port type node choose Add > Binding and Service Port.
    The Generate Binding and Service Port dialog box appears.
  2. Supply a name for the binding.
  3. The only supported binding type in this release is the SOAP protocol.
  4. The binding subtype options indicate how to translate the binding to a SOAP message. If your settings for message parts and the binding subtype do not conform to the WS-I Basic Profile, an error message appears.
  5. Supply a name for the service.
  6. Supply a name for the port.
  7. Click OK.
    A binding node and a service node appear. The binding node contains a SOAP binding node and one or more operations. The service node contains a port node.

Creating a Binding

Instead of quickly creating a binding and service from an existing port type, you can create the binding, service, and their subnodes individually. This section describes how to create the binding, and then how to configure the SOAP information.

To create a binding:

  1. In the WSDL view, right-click the Bindings node and choose Add Binding.
    A binding node appears.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the binding node.
  4. (Optional) Set the Name property to the new name.
  5. Set the Type property to the port type that the binding will reference.
  6. Right-click the binding node and choose Add > Binding Operation.
  7. If the binding's port type has more than one operation, then the Select Operation dialog box appears. Choose one or more operations, and click OK.
    One or more operation nodes appear.

To add a SOAP binding node:

  1. In the WSDL view, right-click the binding node and choose Add > SOAP Binding.
    A SOAP binding node appears.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the SOAP binding node.
  4. The style property indicates how to translate the binding to a SOAP message. Set the value to document or RPC.

To configure the SOAP elements for an operation:

  1. In the WSDL view, right-click the operation node and choose Add > SOAP Operation.
    A SOAP operation node appears. This node contains information for the operation as a whole.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the SOAP operation node.
  4. The soapAction property specifies the value of the SOAPAction header for the operation.
  5. The style property indicates how to translate the binding to a SOAP message. Set the value to document or RPC.
  6. Depending on your scenario, add elements to Input, Output, and Fault nodes.
  7. To add a soap:headerfault element, right-click the soap:header node and choose Add headerfault.
  8. If you added a soap:body element, then you can set the following properties.
  9. If you added a soap:header element, then you can set the following properties. The Message and Part properties are required.
  10. If you added a soap:headerfault element, then you can set the following properties. The Message and Part properties are required.
  11. If you added a soap:fault element, then you can set the following properties.

Removing Bindings

You can remove a binding from the WSDL file.

To remove a binding:

top


Configuring WSDL Services

You can use the WSDL Editor to create services. In addition, you can modify services that were generated by the New WSDL Document wizard.

In a WSDL file, a service indicates which binding to use and where clients can access the web service.

Creating a Binding and Service From a Port Type

You can quickly create a binding and a service from an existing port type. If you want to modify the service afterward, then see the appropriate steps in Creating a Service.

To create a binding and service from a port type:

  1. In the WSDL view, right-click the port type node choose Add > Binding and Service Port.
    The Generate Binding and Service Port dialog box appears.
  2. Supply a name for the binding.
  3. The only supported binding type in this release is the SOAP protocol.
  4. The binding subtype options indicate how to translate the binding to a SOAP message. If your settings for message parts and the binding subtype do not conform to the WS-I Basic Profile, an error message appears.
  5. Supply a name for the service.
  6. Supply a name for the port.
  7. Click OK.
    A binding node and a service node appear. The binding node contains a SOAP binding node and one or more operations. The service node contains a port node.

Creating a Service

Instead of quickly creating a binding and service from an existing port type, you can create the binding, service, and their subnodes individually. This section describes how to create the service, and then how to configure the SOAP information.

Before you can configure the service's port, you must create the binding.

To create a service:

  1. In the WSDL view, right-click the Services node and choose Add Service.
    A service node appears.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the service node.
  4. (Optional) Set the Name property to the new name.
  5. Right-click the service node and choose Add > Service Port.
    A port node appears.
  6. Select the port node.
  7. (Optional) Set the Name property to the new name.
  8. Set the Binding property to the desired binding.

To add a SOAP address node:

  1. Right-click the port node and choose Add > SOAP Address.
    A SOAP address node appears.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the SOAP address node.
  4. Set the Location property to the base URI for the port.

Removing Services and Ports

You can remove a service or port from the WSDL file.

To remove a service or port:

top


Adding BPEL Extensibility Elements

You can add the following BPEL extensibility elements to the WSDL file:

Adding a Partner Link Type

Before you can add a partner link to a BPEL process, you must add a partner link type to the WSDL file.

In a BPEL process, a partner link represents the interaction between the BPEL process and a partner service. Each partner link is associated with a partner link type.

A partner link type characterizes the conversational relationship between two services. The partner link type can have one or two roles. A role describes the function that a service has in the relationship. Examples of roles are loanRequestor and loanProcessor. Each role must specify the port type that the service will use to receive messages.

To add a partner link type automatically

  1. When you do either of the following tasks, a partner link type is automatically generated. The partner link type has a default role.
  2. (Optional) To add a second role, do the following:
    1. Right-click the partner link type node and choose Add > role.
    2. If the Properties window is not visible, choose Window > Properties.
    3. Select the role.
    4. (Optional) Change the default name.
    5. Specify the port type.

To add a partner link type manually:

  1. In the WSDL view, right-click the root node and choose Add > PartnerLinkType.
    A partner link type node appears under the Extensibility Elements node. The partner link type has a default role.
  2. (Optional) To add a second role, right-click the partner link type node and choose Add > role.
  3. If the Properties window is not visible, choose Window > Properties.
  4. For each role, do the following:
    1. Select the role.
    2. (Optional) Change the default name.
    3. Specify the port type.

Defining Properties and Property Aliases

The BPEL Service Engine runtime uses a mechanism called correlation to track the multiple, stateful, long-running exchanges of messages that typically take place between a BPEL process and its partner services.

The procedure for enabling correlation in a BPEL process includes the following initial steps, which must be performed in the WSDL file:

Once you perform these steps in the WSDL file, you can define a correlation set in the BPEL process. The correlation set references one or more properties. The correlation set can then be used by message activities (Invoke, Reply, and Receive) and by the onMessage branches of Pick elements.

To define a property:

  1. In the WSDL view, right-click the root node and choose Add > Property.
    A property node appears under the Extensibility Elements node.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the property node.
  4. (Optional) Change the default name.
  5. You can set the Element or Type property to a built-in simple type, such as string or date.

To define a property alias:

  1. In the WSDL view, right-click the root node and choose Add > Property Alias.
    A property alias node appears under the Extensibility Elements node.
  2. If the Properties window is not visible, choose Window > Properties.
  3. Select the property alias node.
  4. Specify values for the Property Name and Message Type properties. These properties enable you to map data from a message into a property value.
  5. You can specify a value for the following optional property: Part.
  6. To add a query, right-click the property alias node and choose Add query.
    A query node appears. The query node enables you to set the following optional attribute: queryLanguage.

top


Finding Usages of WSDL Components

You can quickly determine where a WSDL component is used in the WSDL file.

To find usages of a WSDL component:

  1. In the WSDL view, right-click the component and choose Find Usages.
    The XML Usages window opens in the lower part of the IDE. The window has three parts:
  2. To zoom out, right-click the graphic and drag up. To zoom in, right-click the graphic and drag down.
  3. To pan, click and drag in any direction.
  4. To drag a node, click and drag the node.

top


Copyright and Trademark Notice