Developer Guide to the BPEL Designer: The BPEL Design and Source View

Design View

The Design view is a business processes designer where you can author a diagram of your business process. In the Design view, you add, edit, and delete diagram elements. The diagram constructed in the Design view is automatically generated into BPEL source code compliant with the WS-BPEL 2.0 specification with the exceptions listed in the BPEL 2.0 Language Constructs section of the BPEL Service Engine User's Guide.

The Design view opens by default when you double-click a BPEL source file from a BPEL Module project in the Projects window. To switch to the corresponding place in the Source view, right-click an element in the Design view and select Go to Source (Alt-O).

Source View

The Source view shows the underlying code for a business process diagram. The Source view is based on the IDE's XML Source view and provides access to conveniences such as code folding, XML syntax highlighting, and code completion.

You can perform source level editing as well as visual designing. The BPEL Designer will perform round-trip two-way engineering to ensure that the Design view and Source view remain synchronized with each other. The IDE will automatically re-parse the BPEL source file and rebuild the diagram every time you perform manual edits of the source file.

To switch to the corresponding place in the Design view, place a cursor at the line in the Source view, right-click and choose Go to Design (Alt-I).

XML View

The XML View is identical to the Navigator view that is available for all XML documents opened in the IDE. The XML View is a companion to the BPEL Source view. Double-click any Navigator node and the Source view adjusts the current line of code to show the selected element.

Logical View

The Navigator also provides the BPEL Logical View of BPEL processes. When you select BPEL constructs in the Design view, the BPEL Logical View shows the same element selected. Alternatively, when you select a node in the BPEL Logical View's tree, the corresponding element is selected on the diagram.

Right-clicking the nodes in the BPEL Logical View invokes pop-up menus with actions relevant to the particular node. For example, for the Assign element, the actions are Go to Source, Go to Design, Wrap With, Move Up and Move Down, Toggle Breakpoint, Delete, Show BPEL Mapper, and Properties. The Go to Source and Go to Design actions, available for most of the nodes, have associated keyboard shortcuts: Alt-O for Go to Source and Alt-D for Go to Design.

In general, the nodes in the Navigator window correspond to the elements on the diagram. In addition, there are nodes, such as Variables and Correlation Sets, that are related to functionality not directly accessible from the diagram. To view the variables used in the business process, expand the Variables node in the BPEL Logical View of the Navigator window. For variables, the following commands are available in the pop-up menu:

• Go To Source. Opens the source of the BPEL file and places the cursor at the place where the variable is mentioned for the first time.
• Go To Type Source. Opens the source file that contains a definition of the variable type. This can be, for example, a WSDL file.
• Find Usages. Shows usages of variables in the BPEL file. This command is also available from the pop-up menu for correlation sets and Partner Link elements.

Of particular relevance is the Imports node, which lists XSD and WSDL files referenced with the help of the Import element in your BPEL file. Using the pop-up menu for the Imports node, you can add reference to an XSD or WSDL file. Note that only files located in the project folder may be referenced.

To add a resource file (.wsdl or .xsd) as an import:

1. In the BPEL Logical View of the Navigator window, right-click the Imports node and choose one of the following, depending on the format of the imported file: Add WSDL Import or Add Schema Import.
2. In the Create New Import dialog box, select the file in your project structure to add it as import.
   Note: You first need to add the files stored in your project directory to the project structure. Then you can add them as imports. The files that are already referenced are displayed in the strikethrough style.
3. View the values in the read-only Namespace and Type fields and click OK.
   The resource file you have just added appears under the Imports node in the Navigator window.

You can add properties and property aliases to the WSDL files referenced in the BPEL document.

To add a property to a WSDL file:

1. In the BPEL Logical View of the Navigator window, right-click a WSDL file under the Imports node and choose Add Property from the pop-up menu.
2. In the Create New Correlation Property dialog box, specify the property name.
3. Select the property type and click OK.

To add a property alias to a WSDL file:

1. In the BPEL Logical View of the Navigator window, right-click a WSDL file under the Imports node and select Add Property Alias from the pop-up menu.
2. In the Create New Property Alias dialog box, click Browse next to the Property field to specify the property.
3. In the Property Chooser dialog box, select the property for which you are creating the alias and click OK. The Property Type field in the Create New Property Alias dialog box is populated with the type.
4. In the Map Property To tree, expand the WSDL file node and select the message or message part.
5. To add a query, enter the query string in the Query text field.
   If the Synchronous with Tree checkbox is selected, the Query field is updated each time you change the selection in the Map Property To tree.
6. Click OK.

For more information on defining properties and property aliases with the WSDL Editor, refer to the Developer Guide to the WSDL Editor.

Navigation Features in the Design View

When working with large-scale diagrams, you can use the navigation features provided in the Design view.

• Using the Navigation mode to scroll through the diagram. You can use the Navigation Mode to scroll through your diagram in any direction. This feature lets you navigate around large-size diagrams. Clicking the Navigation Mode icon on the Editor toolbar enables the Navigation Mode. To return to editing your diagram, click the Editing Mode icon .
  When you are in editing mode, you can press and hold the space bar on your keyboard to enable navigation mode.
• Zooming in and out of the diagram. The zoom feature allows you to reduce or enlarge the size of your diagram to get a closer view or to see more of the diagram at a reduced size. You can change the zoom value using the Zoom Value drop-down list on the Editor toolbar. To scale the diagram to fit the window, click Fit Diagram. To scale the diagram width to fit the window width, click the Fit Width button.
  Note that the minimum scale size is 33% and some large diagrams might not fit entirely the window.
• Using the Thumbnail view. The Thumbnail view helps you clickly navigate to another portion of your business diagram. This view provides a minuature representation of your entire diagram. To activate the Thumbnail view, click the Thumbnail view icon in the right lower corner of the Design view. The current display area is shown with a shaded rectangle. Drag the shaded rectangle to the portion of the diagram that you need.
• Scrolling through the diagram while editing. You can scroll through the diagram or step through elements by using the following:
  • Turning the mouse wheel
  • Using the horizontal and vertical scroll bars
  • Pressing the Tab key or Shift-arrow to move through elements
• Using error stripes. You can also click the error stripe near the right-hand scroll bar to quickly jump to the specific places on your diagram. These error stripes denote warnings, validation errors, breakpoints, validity status, and the current selection.

Operations with Elements in the Design View

In the Design view, you can perform the following operations on elements:

• Create elements by dragging elements from the Palette to the diagram. The Design view supports the notion of "drop points", which means that you must align elements with these drop points when you drag them. Not all elements are created via drag-and-drop from the Palette. These other elements are created using pop-up menus which are invoked when you right-click an existing diagram element.
• Select elements on a diagram. A single click on an element selects it. Selection is a necessary step in performing several other operations, such as deleting, moving, or editing an element.
• Invoke pop-up menu actions for diagram elements. Each BPEL element has a pop-up menu. This pop-up menu can be invoked by right-clicking the element. The pop-up menu will offer a set of actions which are relevant to the selected element.
• Move diagram elements. You can move diagram elements by selecting the element and then dragging it to a new location. If you move a container element, all its children move along with the container.
• Edit element names in the Design view directly. Double-click the element name on the diagram to edit it.
• Invoke XML Validation. You can invoke XML validation by clicking the Validate XML button on the Design view editor toolbar. For more information, see the Validating BPEL section.
• Apply filters to diagram elements. The Editor toolbar contains the Show Partner Links and Show Sequences toggle buttons. Both Partner Link elements and Sequence elements are shown by default. Clicking the Show Partner Links button hides the Partner Link elements on the diagram. Clicking the Show Sequences button hides the Sequence containers on the diagram. Clicking either button a second time will again reveal the Partner Link elements, or the Sequence elements on the diagram, respectively.
  Note: You cannot add new Partner Link or Sequence elements to the diagram if you chose not to show them.
• Finding elements on the diagram. You can find BPEL elements in the Design view by their names or types. You can use either the Find bar (Edit > Find or Ctrl-F) or the Advanced Search feature (Edit > Advanced Search or Alt-Shift-F). In the Find bar, select the type of search you want to perform, type in the search query and click Find. In the Advanced Search dialog box, you can refine your search query and search BPEL elements by their name and/or type.
• Collapsing or expanding elements on the diagram. When a large diagram is open in the Design view, you can collapse or expand container elements, such as Sequence or Scope, using the quick action buttons that appear near the selected elements. By default, when you open a diagram in the Design view, you can see all container elements expanded. To expand all elements on the diagram, click the Expand All icon on the Editor toolbar. You can use the following combinations of keys: Enter to expand the selected element, Shift-Enter to collapse the selected element, and Alt-Enter to expand all elements on the diagram.
• Wrapping activities with container elements. You can wrap elements with container activities in a single click. The wrap feature is useful, for example when you want to quickly place an activity inside another activity. In the Design view, right-click the activity you want to wrap, point to the Wrap With option, and select the wrapper BPEL activity.

Configuring Element Properties in the Design View

After you add BPEL activities to a diagram, you need to configure them. You can do this using either the Property Editor dialog boxes or the IDE's Properties window. Note that Property Editor dialog boxes are available only for some elements.

To open the Property Editor for an element, do one of the following:

• Right-click the element and choose Edit.
• Double-click the element.

To open the Properties window for an element, right-click the element and choose Properties. The properties for this element are displayed in the standard IDE's Properties window. If the IDE's Properties window is not open, choose Window > Properties from the main menu (Ctrl-Shift-7).

Saving Your Changes

The BPEL Designer synchronizes the Design and Source views as follows:

• Changes you make in a diagram are reflected immediately in the corresponding source code.
• Changes you make in the source code are reflected on the diagram when you switch to the Design view.

To save changes in the Design or Source view, choose File > Save or press Ctrl-S.

Printing the Source or Diagrams

You can print BPEL diagrams and source files and customize printing settings, including border, headers, footers, colors, line numbers, and zooming, to suit your preferences.

To preview and print a BPEL diagram:

1. Open a BPEL file in the Design view.
2. Choose File from the main menu and select one of the following commands:
   • Print. Print out the BPEL diagram.
   • Print Preview. Preview the print layout or customize print options.

To print a BPEL source file:

1. Open a BPEL file in the Source View.
2. Choose File from the main menu and select one of the following commands:
   • Print. Print out the file.
   • Print Preview. Preview the print layout or configure print settings.
   • Print to HTML. Print the .bpel file as an HTML file.

To customize print options:

1. In the IDE, select an object you want to print.
2. Choose File > Print Preview.
3. In the Print Preview window, click Options.
   The Print Options dialog box opens.
4. Change the print settings to suit your preferences:
   • Print Border. Adds a border to the printed page. Click the Color icon to change the border color.
   • Page Setup. Specifies paper orientation, margin sizes, and the printer. You can also invoke the Page Setup dialog box by choosing File > Page Setup.
   • Print Header and Print Footer. Specifies the text, alignment, color, and font of the header and footer. To hide the header or footer, clear the Print Header or Print Footer checkboxes, respectively. To specify the header or footer pattern text, click in the field corresponding to the alignment (Left, Center, or Right) and select one of the buttons below.
     For example, to add a page number at the bottom left corner, select the Print Footer checkbox, click into the Left field, and click the "Page number" icon. Click the Choose Footer Color and Choose Footer Font icons to modify the color and the font for the page header and footer.
   • Line Numbers. Specifies whether to print line numbers for source files.
   • Wrap Lines. Wraps the lines to fit them on the page.
   • Text Color and Text Background. Specifies the color and backround of the text when you are printing, for example, source files.
   • Zoom. Specifies the scale for the printed text or diagram on the page. You can select to fit width or height or choose a specific zoom scale.
5. Click OK.

Reverse Engineering

You can use the BPEL Designer to edit the source file directly and to have those changes reflected in the Design view.

You might need to edit the source in the following cases:

1. If you want to use a vendor-specific BPEL extension which is not part of the standard BPEL element set, you must use the Source view.
2. If you need to add a BPEL construct for which the Design view does not provide a code generation opportunity. There are a few edge case BPEL constructs, like assignment of static XML to a variable, which are not displayed in the current Property Editor dialog boxes.
3. If, while using the Source view, you modify and save BPEL source that is not well formed, then the Design view will not be able to render a diagram for this "broken" BPEL. The Design view will display a page that says "Unable to show diagram". Return to the Source view to correct the error and, after correction, run the XML validator in the Source view to validate your changes. Once you have restored the BPEL source to a valid state, the Design view will once again be able to render the diagram.

Configuring Message Flows

Activities are diagram elements that represent BPEL activities involved in a message flow.

A message flow is the dashed line that connects a web service activity (Invoke, Receive, Reply) to its corresponding activity in a partner link. This relationship is called a message flow as it designates the flow of information to and from the process.

If you completely configure the Web Service activity by its Properties window, the IDE will render a message flow connector between an activity and a partner activity.

However, you can also directly draw a message flow. To do this:

1. Select a web service activity. A small envelope appears on the left side of the activity icon.
2. Start dragging the envelope. The IDE displays a dashed line that links the source activity to the envelope you are dragging.
3. Move your mouse to the target activity. If the target activity is a match for the source, the mouse cursor indicates this, and you can release the mouse. The connection snaps into place between the activities.

Note that you cannot directly delete a message flow. You can indirectly delete a message flow by unsetting some of the properties in the the web service activity. Usually, however, you will change a message flow to create a different relationship.

Note also that the drawing tool works only in one direction: from a web service activity within the BPEL process to its corresponding activity in a partner link.

Changing Message Flow

If you want to change an existing message flow connection and establish a new connection with a different target activity, proceed as if you are making the connection for the first time with the preferred pairing. Once you create the new pairing, the IDE automatically removes the old connection.

Palette Elements

The following table lists the basic elements that appear on the Palette. Not all BPEL elements are on the Palette; some are created when you right-click the diagram and choose appropriate actions from the pop-up menus.

You can use the Palette Manager to enable, disable, and rearrange the Palette elements. To open the Palette Manager, right-click inside the Palette and choose Palette Manager.

Elements are of the following types:

• Web Service. Elements used for exchanging messages in a conversational manner with a partner web service.
• Basic Activities. Activities that perform a certain task.
• Structured Activities. Elements used to precisely order sets of activities. Structured Activities can contain other activities.

Icon	Element	Definition
Web Service
	Invoke	Enables the business process to invoke a one-way or request-response operation on a portType offered by a partner; enables this process to send messages to partners. The operation is defined in the partner's WSDL.
	Receive	Allows the business process to perform a blocking wait for a particular message to arrive.
	Partner Link	Identifies those web services that will exchange messages with our business process. Each partner link will contain child elements that correspond to the available web service activities supported by that partner link's interface. Note: You do not directly add elements to a partner link container. The Design view will introspect the partner's WSDL and automatically populate the partner link container with the appropriate child elements. If you need to modify a partner link, edit the partner WSDL files which will allow the Design view to re-render the partner link and thereby reflect the modified interface.
	Reply	Enables the business process to send a message in reply to a message that was received through a Receive.
Basic Activities
	Empty	An activity that does nothing, useful when you need to catch and suppress a fault.
	Wait	Waits until a given point in time or for a specified duration.
	Throw	Generates a fault from inside the business process.
	Assign	Updates the values of variables with new data.
	Exit	Immediately terminates the execution of the business process instance.
Structured Activities
	Flow	Specifies one or more activities to be performed concurrently.
	Sequence	Defines a collection of activities to be performed sequentially, in lexical order.
	If	Selects one branch of activity from a set of choices.
	Pick	Blocks and waits for a suitable message to arrive, or for a time-out to expire. When an event specified in the body of the Pick occurs, the Pick completes. Only one of the activities in the body of the Pick actually occurs.
	Scope	Defines a nested activity with its own associated local variables, event and fault handlers, and message exchange.
	While	Repeats an activity while a condition is true. The condition is checked before the execution of the activity.
	Repeat Until	Repeats an activity until a condition is true. It is different from While in that the condition is checked after the execution.
	For Each	Repeats an activity exactly N+1 times, where N equals the Final Counter Value minus the Start Counter Value.