Using the BPEL Designer and Service Engine

Testing and Debugging BPEL Processes

The section describes how to test and debug BPEL processes.

Testing a BPEL Process

Testing a deployed business process application involves using test cases that act as remote partner services. These test cases send SOAP messages to the BPEL Service Engine.

In simple words, the interaction process is as follows:

The BPEL Service Engine receives the SOAP message, creates an instance of the BPEL process, and starts executing the instance. A BPEL process can have many running instances.
The BPEL Service Engine receives a message and, using correlation, routes it to the appropriate instance of the process. If an instance does not yet exist, a new instance is created.

To test-run a deployed business process application, you need to configure test cases to act as remote partner services sending SOAP messages to the BPEL Service Engine.

Creating and Running a Test Case

In order to obtain test results you must do the following:

All steps in this section assume the following:

You have already created a new BPEL Module Project containing a WSDL file that defines an operation you want to test.
You have successfully completed a build of the BPEL Module Project.
You have added your BPEL Module project to a Composite Application project as a JBI Module.

Adding a Test Case to your BPEL Project

To add a test case and bind it to a BPEL operation

In the NetBeans IDE Projects window, expand your Composite Application project to expose the Test folder.

Right-click Test, and choose New Test Case from the pop-up menu. This launches the New Test Case wizard.

This launches the New Test Case wizard.

In the Enter the Test Case Name step, enter a name for the test case and click Next.

In the Select the WSDL Document step, open the BPEL Module project,select the WSDL file containing the operation you want to test, and click Next.

In the Select the Operation to Test step, select the operation you want to test, and click Finish.

In the Projects tree, a new folder is created under the Test node, containing two files: Input.xml and Output.xml.

Note –
If you view the test case in the Files window, you see Concurrent.properties as a third file.

Setting the Test Properties

To set the test properties

In the Projects window, under the Composite Application > Test node, right-click the node for the test case and choose Properties from the pop-up menu.

Set the properties of the test case as follows:
- Description — string
- Destination — URL (from the .wsdl file's <soap:address location="THIS"> tag)
  
  Identifies the location of the web service to be tested.
- SoapAction — (default: blank)
- Input File — (read-only; generated by system)
  
  Name of the input file. This file contains the input data for the test case.
- Output File — (read-only; generated by system)
  
  Name of the output file. This file contains the output data for the test case.
- Concurrent Threads — integer; default = 1
  
  Each thread can invoke the test case multiple times (see the following property). Thus, if conc=2 and inv=3, the test case will be run 6 times (two threads, each run thrice).
- Invokes Per Thread — integer; default = 1
  
  Number of times each thread invokes the test case.
- Test Timeout (sec) — integer; default = 30
  
  How long each thread has to finish. If it does not finish in the allotted time, then an exception is thrown.
- Calculate Throughput — boolean
- Comparison Type — drop-down list with the following options:
  - identical — Considers the output and actual output as a stream of characters.
  - binary — Considers the output and actual output as a stream of bytes.
  - equals — Considers the output and actual output as a XML documents.
- Feature Status — drop-down list with the following options:
  - progress — Marks test completion as "success", regardless of actual outcome.
  - done — Records actual outcome of test.

Customizing Test Input

To customize test input

In the Projects window, expand the Test node and the node for a specific test case.

Right-click Input and click Edit.

Modify the contents as needed. For example, wherever you see <value>?string?</value> click within ?string? and replace it with a string of any length. However, within such strings, do not include the characters “<” (less-than sign) or “&” (ampersand) unless you use them with XML semantics.

When you are satisfied, click Save.

Right-click Output.xml and choose Edit to examine the contents:
- If it is empty, this is a special state that triggers a special operation when the test is run.
- Each time the test is run, the current output is compared to the contents of Output.xml. If any differences are detected, they will be stored in the Actual_yymmddhhmmss .xml file under the test case folder. However, in the special case where Output.xml starts null, then the output is written to Output.xml.
- In each run after the first, assuming Output.xml is no longer null, its contents are preserved. In other words, a previous output is never overwritten by new results.

Running Test Cases

To run a single test case

To run a single test case, right-click the node for your specific test case, and choose Run. Check the Output window for the results.

To run all test cases in a project

To run all test cases in a project, right-click your Composite Application project and choose Test (Alt+F6) from the pop-up menu. Check the Output window for the results.

Looking at Test Case Results

The first time you run your test, the results correctly report that it has failed. This happens because the output produced does not match the (empty) Output.xml file, and the file?s null content is replaced with the output of the first run. If you run the test again without changing the input, the second and subsequent runs report success, since the output matches the contents of Output.xml.

Test results are displayed in the Output window. Detailed results are also displayed in the JUnit Test Results window, which opens automatically when you run a test case. If you change the value in the Input.xml and re-run the test:

If the feature-status property is set to progress, then the test indicates success even though a mismatch occurred.
If the feature-status property is set to done, then the test indicates failure.

If you right-click the test case node and click Diff in the pop-up menu, the window displays the difference between the latest output and the contents of Output.xml.

Debugging BPEL Processes

Debugging a BPEL process follows the same general principles as debugging a Java application. Debugging a BPEL process involves setting breakpoints in the source code and executing the process step-by-step within a debugging session. The BPEL Debugger provides a visual representation of the BPEL process execution. This enables you to view and change variables, monitor the results of executing expressions, and use fault breakpoints to monitor the state of variables before a fault is thrown.

Steps in Debugging BPEL Processes

The main steps in debugging BPEL processes are:

Confirm that the GlassFish application server has started.
Create test cases.

For sample processes, test cases are automatically created; for new projects, you need to create at least one test case.
Open the BPEL process file either in the Source view or Design view.
Set breakpoints in the code or on the diagram. Optionally, add watches for XPath expressions in your process or add fault breakpoints.
Start a debugging session. Watch the BPEL Debugger Console window for confirmation that the debugging session has started.
Within the debugging session, run one or several test cases.
View execution of BPEL processes on the diagram in the Design view or in the BPEL Process Execution window and view running instances of BPEL processes in the BPEL Process Instances window.
When an instance stops at a breakpoint, step through the code or the diagram, examine the values of variables in the BPEL Variables window, or observe the values of XPath expressions in the Watches window.
Finish the debugging session.

Starting and Finishing a BPEL Debugging Session

A debugging session begins when you connect the BPEL Debugger to the BPEL Service Engine. Only one debugging session can be running with the BPEL Service Engine at a given time.

After a BPEL debugging session starts, you can execute process instances step-by-step, inspecting the values of BPEL variables and XPath expressions in the Local Variables and Watches windows. You can monitor the execution of a BPEL process within a debugger session on the diagram in the Design view: the activities that are being executed are highlighted on the diagram as the current execution position advances. The BPEL Process Execution window also shows the execution of the BPEL process.

To prepare the debugging environment

In the Services window, make sure that the GlassFish V2 Application Server is running. The Application Server is running if it has subnodes and is marked with a green triangle.

If the server is not started, right-click it and choose Start from the pop-up menu.

In the IDE, open the BPEL process in either the Source or Design view.

Set breakpoints in the BPEL process.

To set breakpoints in the Source view, click next to the line where you want to set the breakpoint.

To set breakpoints on the diagram, switch to the Design view, right-click the element and choose Toggle Breakpoint from the pop-up menu. A red square appears at the top of the element with a breakpoint.

The Toggle Breakpoint pop-up menu command is also available for the elements in the Navigator BPEL Logical View. For the elements with breakpoints, the Navigator shows a small red box (ReceiveItinerary).

Optionally, you can add watches to monitor XPath expressions. To add a watch, copy the XPath expression you want to monitor, choose Run -> Add Watch from the main menu, and paste the expression into the Watch Expression field. Click OK.

Note –
You can also add XPath expressions that are not present in the code, but that would be valuable from the debugging point of view.

To start and finish a debugging session on the BPEL Engine

In the Projects window, right-click the Composite Applications project you want to debug and choose Debug (BPEL) from the pop-up menu.

A debug session is established on the BPEL Service Engine.

11:35:17 Connecting to localhost:3343
- Enables debugging with the BPEL Service Engine (sets the DebugEnabled property of the BPEL Service Engine to true)
- Builds the Composite Application project and all JBI Modules added to this project
- Deploys the Composite Application project to the BPEL Service Engine
- Starts the debugging session by connecting the BPEL Debugger to the BPEL Service Engine
Therefore, whenever you start a debugging session you can be sure that the latest version of the BPEL process is deployed on the BPEL Service Engine.

Now you can run a test case and monitor the execution of the BPEL process until it stops or reaches a breakpoint. As the process advances, the current context is displayed on the diagram and in the BPEL Process Execution window.

If you have several debugging sessions (you may have a Java debugging session running at the same time) and want to change the current session, double-click the name of this session in the Sessions window. Alternatively, right-click the session you want to make current and select Make Current. This session becomes current and the BPEL Process Instances, Watches and Local Variables Windows are updated to show the data related to the new current session.

When you want to finish a debugging session, open the pop-up menu for the session you want to stop and choose Finish in the Sessions window or select Finish Debugger Session on the toolbar. A message that the debugging session is finished is displayed in the BPEL Debugger Console.

To finish all debugging sessions, in the Sessions window, right-click any session and choose Finish All.

Watch the BPEL Debugger Console window for confirmation. The connection might take some time to complete. When it is successfully completed, you can see the new session in the Sessions window and the following messages in the BPEL Debugger Console:
- 11:35:17 Connecting to localhost:3343
- 11:36:19 Debug session started
  
  The Debug (BPEL) command performs the following actions:
  - Enables debugging with the BPEL Service Engine (sets the DebugEnabled property of the BPEL Service Engine to true)
  - Builds the Composite Application project and all JBI Modules added to this project
  - Deploys the Composite Application project to the BPEL Service Engine
  - Starts the debugging session by connecting the BPEL Debugger to the BPEL Service Engine Therefore, whenever you start a debugging session you can be sure that the latest version of the BPEL process is deployed on the BPEL Service Engine

Now, run a test case and monitor the execution of the BPEL process until it stops or reaches a breakpoint.

As the process advances, the current context is displayed on the diagram and in the BPEL Process Execution window.

If you have several debugging sessions (you may have a Java debugging session running at the same time) and want to change the current session, double-click the name of this session in the Sessions window. Alternatively, right-click the session you want to make current and select Make Current. This session becomes current and the BPEL Process Instances, Watches and Local Variables Windows are updated to show the data related to the new current session.

To finish a debugging session, open the pop-up menu for the session you want to stop and choose Finish in the Sessions window, or select Finish Debugger Session on the toolbar.

A message that the debugging session is finished is displayed in the BPEL Debugger Console.

To finish all debugging sessions, in the Sessions window, right-click any session and choose Finish All.

Using Breakpoints to Debug BPEL Processes

Breakpoints are used to instruct the BPEL Debugger to stop execution at the specified place of a BPEL process. When a BPEL process instance reaches a breakpoint, it becomes suspended and you can step into the code, change the current process instance in the BPEL Process Instances window, track the execution of the process instance in the BPEL Process Execution window and in the Design view, examine the values of variables in the Local Variables window, view the process partner links in the Partner Links window and view the values of XPath expressions in the Watches window.

You can also use fault breakpoints to check the values of variables before a fault is thrown.

To view and organize the breakpoints currently set in the IDE, open the Breakpoints window by choosing Windows -> Debugging -> Breakpoints (Alt-Shift-5). For each breakpoint, you can see the name of the file and the line where this breakpoint is located. In the Breakpoints window you can enable and disable breakpoints by checking or removing the checkbox in the Enabled column.

To set a breakpoint in a BPEL process

In the IDE, open the BPEL file in either the Source or Design view.

Do one of the following:
- In the Source view, click the left margin of the row where you want to place a breakpoint.
- In the Design view, right-click an element where you want to place a breakpoint and choose Toggle Breakpoint (Ctrl-F8).
  
  In the Design view, breakpoints are displayed as small red squares on top of specific elements. In the Source view, breakpoints are shown as red squares on the left margins of code lines.
  
  Alternatively, you can set and remove breakpoints in the BPEL Logical view of the Navigator window by choosing Toggle Breakpoint from the pop-up menu. In the Navigator window breakpoints are shown as small red squares attached to elements.
  
  Once the project has reached the breakpoint it is suspended. You can manage the subsequent execution using the commands available in the Run menu or as buttons on the toolbar.

Debugging Commands

The following commands are available from within the debugging session:

Pause. Once the user activates this action, the process will continue till it reaches the first element on which it can stop. If there is no current process instance, the debugger will wait for the first execution event from any process instance.
Continue (F5). Once the process has reached the breakpoint or is paused you can choose Continue. This action causes the current process instance to run until it encounters the next breakpoint or until the instance completes. The state of the instance changes to Running.
Step Into (F7). Steps to the next BPEL activity. As you step, the current line indicator advances, the current position is highlighted on the diagram, and the contents of the BPEL Debugger windows change accordingly. If the current activity has any enclosed elements, the process will step to the first enclosed element. Sometimes it is not visible on the diagram but is reflected in the BPEL Process Execution window. For example, if an Assign activity has <copy> element inside it, from the Assign the process will step to Copy.
Step Over (F8). Steps to the next BPEL activity of the same level as the current activity. If the current activity has any enclosed elements, they all are executed without suspension.
Step Out (Ctrl-F7). Steps to the next higher level activity of the process. For example, an Assign activity has several Copy elements inside. If one of the Copy elements is the current activity, performing Step Out will move you to the next activity of the Assign level and you will not have to step through all the Copy elements.
Run to Cursor (F4). Runs the BPEL process to the position selected in the Navigator window (BPEL Logical View), on the diagram (in the Design view) or to the cursor location in the Source view. When the location of the cursor is reached, the process instance becomes suspended.

To remove a breakpoint from the BPEL process

In the Source view, On the diagram, click the left margin of the line that contains the breakpoint.

In the Breakpoints window, right-click the breakpoint you want to remove and choose Delete. Choosing Delete All from the pop-up menu removes all breakpoints currently set in the NetBeans IDE.

3. In the Design view, right-click the element that has a red breakpoint mark and choose Toggle Breakpoint.

To disable a breakpoint

To disable a breakpoint do one of the following:

On the diagram, click on the small red square indicating the breakpoint. This disables the breakpoint but does not remove it completely.
In the Breakpoints window, clear the Enabled checkbox for the breakpoint you want to disable.

Group operations over breakpoints

The toolbar contains three buttons for group operations over the process breakpoints.

Enable Breakpoints for Selected Element. Enables all the breakpoints for the selected element and it's enclosed elements.
Disable Breakpoints for Selected Element. Disables all the breakpoints for the selected element and it's enclosed elements.
Delete Breakpoints for Selected Element. Deletes all the breakpoints for the selected element and it's enclosed elements. If no element is selected on the diagram, the Process element is considered selected for the operations.

Monitoring Execution of BPEL Processes

When a running process reaches a breakpoint, the Design view highlights the current position of the debugger and uses colors to differentiate between the states of BPEL activities. As the process advances, the colors and icons for the activities on the diagram are updated to reflect the execution progress.

On the diagram, the following notation is used:

Green color (glowing). The breakpoint set for the activity is reached.
Gray color (grayed-out effect). The activity has not been executed yet.
Green triangle. The activity is now being executed.
Blue triangle. The activity has been successfully completed.

Image shows the icon in the BPEL mapper that indicates
monitoring debugging on the diagram

You can also monitor the execution of current BPEL process instances in the BPEL Process Execution window (see below).

BPEL Debugger Windows

When a debugging session starts, debugger windows are displayed below the editing area. The Sessions, BPEL Process Instances, BPEL Variables, and BPEL Process Execution windows contain information related to BPEL processes running within the current debugging section.

If a debugger window is not displayed, choose Window > Debugging > window-name (for example, Window > Debugging > BPEL Process Instances).

The Breakpoints and Watches are standard IDE debugger windows. They display all breakpoints and watches set in the IDE.

Sessions Window

The Sessions window lists all open debugging sessions, including Java and BPEL debugging sessions. For the BPEL Service Engine, only one session can be started. However, the Sessions window also displays other open debugging sessions, such as Java sessions. Only one of the open debugging sessions can be current, and it is shown in bold. Other debugger windows, such as BPEL Process Instances, BPEL Process Execution, and BPEL Variables, display data related only to the current debugging session.

The information provided for each session includes:

Name. The name of the session.
State. The current state of the session. Sessions can be starting or running.
Language. The language of the application debugged in this session.

You can perform the following actions on sessions available in the pop-up menu:

Make current. Makes the selected session current.
Finish. Finishes the selected session.
Finish all. Finishes all debugging sessions.

Image shows the BPEL debugger sessions window as described
in context

BPEL Process Instances Window

The BPEL Process Instances window lists all BPEL process instances deployed to the BPEL Service Engine and their currently running instances. For each process instance correlation sets and Faults are listed as subnodes.

If the current session is not a BPEL Debugger session, this window is empty. The BPEL Process Instances window is populated when a debugging session starts on the BPEL Service Engine, or when the current session is a BPEL Debugger session.

The information displayed for each process instance includes the instance name, unique instance ID, and its state.

Process instances can exist in one of the following states:

Running. The instance is currently being executed on the BPEL Service Engine.
Suspended. The instance has been suspended for some reason. For example, the process instance has reached a breakpoint.
Unknown. The status of the instance is unknown.

A process instance that is current is shown in bold. A process instance becomes current when it reaches a breakpoint or when you manually make it current.

Image shows the BPEL Process Instances window

To make a process instance current, do one of the following:

Double-click the process instance.
Right-click the process instance and choose Make Current from the pop-up menu.

To terminate a process instance:

Right-click the process instance and select Terminate from the pop-up menu. The process instance is terminated and removed from the list.

Correlation Sets and Faults information

For the Correlation Sets node the information comes out during the process execution.

For each process instance correlation set, a list of properties it includes is shown. For the properties, type and value information is displayed. Find more information on Correlation sets, properties, and property aliases here: Using Correlation.

Local Variables Window

The Local Variables window shows the structure of local variables and their values for the current process instance and current position. The current position is the place where the current process instance became suspended. When you change the current process instance, the records in the Local Variables window are updated to reflect the variables for the new current process instance and the new current position.

The structure of local variables is shown as a tree. The information provided for each variable includes the variable name and value.

In the Local Variables window you can do the following:

View the variable structure. To do this, expand the variable node in the tree.
View and edit the values of variables. To edit the value of a variable, click the ellipsis (...) button and enter the new value in the editor window.
The structure of local variables is shown as a tree. The information provided for each variable includes the variable name and value.

Watches Window

The Watches window shows the list of XPath expressions that you want to monitor. You add watches explicitly before or during the debugging session. The Watches window shows the expression and its value. The value of the expression may change as the process advances depending on the logic of your process.

To set watches in the BPEL process:

(Optional) Be sure that the Watches window is visible or choose Window -> Debugging -> Watches (Alt-Shift-2) to view it.

If you want to enter an XPath expression from your BPEL process, copy it using one of the following methods:
- In the Source view, copy the XPath expression you want to watch. The XPath expressions can be found inside the <condition> tag.
- In the Design view, select an element that has an expression and copy the expression from the Condition row in the Properties window.

Right-click inside the Watches window and choose New Watch.

In the Watch Expression field of the New Watch dialog box, do one of the following:
- Paste the XPath expression you have copied.
- Enter any valid expression that is compliant with XPath 1.1.

(Optional) If needed, add more watches.

Ensure that a debugging session is running and perform a test run.

As the process instance reaches a breakpoint and becomes suspended, examine the values of the expressions being watched in the Value column of the Watches window.

BPEL Process Execution Window

The BPEL Process Execution window graphically represents the progress of executing the current BPEL process instance in the BPEL Debugger. When you change the current process instance, the process tree in the BPEL Process Execution window is updated to reflect the state of the new current process instance and the new current position.

In the BPEL Process Execution window, the following colors are used to display the state of BPEL activities:

Green — The activity is being executed at the moment.
Gray — The activity has not been executed yet.
Black — The activity has been executed.

BPEL Process Execution Window displays the following information:

Name — The name of the activity.
Thread — The thread in which the activity is/was executed. For the nodes that have not yet been executed no thread information is provided.
Line — Contains the path to the file and the line number for the activity in the file.
XPath — Shows XPath expression pointing to the activity.

Note –

In the BPEL Process Execution window, you can only view the progress of executing BPEL processes. You cannot perform any actions in this window.

BPEL Partner Links Window

The Partner Links window lists the all the partner links defined in the BPEL Process.

The information provided for the partner links includes:

My Role
Partner Role — for two-way operations only
Endpoint — The endpoint information is available for dynamically defined partner links only. For more information see Dynamic Addressing

Image shows the BPEL Partner Links window.

BPEL Debugger Console Messages

You can see the following messages in the BPEL Debugger Console:

Connecting to <host>:<port>

The Debugger is attempting to connect to the BPEL service engine.

Debug session started

The Debugger has successfully connected to the BPEL service engine and the debug session has started.

Unable to start a debug session : Unable to connect to <host>:<port> : Connection timed out: connect

If you see this message, verify the following:

The GlassFish V2 Application Server is running.
The BPEL service engine is started.
The DebugEnabled property of the BPEL service engine is set to true.
The host name is the host name of the machine that runs the GlassFish V2 Application Server you are connecting to ( localhost by default).
The port value is the same as the DebugPort property of the BPEL service engine you are connecting to (3343 by default).

Unable to start a debug session : Already connected to <host>:<port>

You already have a running debug session attached to this particular service engine.

Debug session terminated : Target disconnected

The Debugger lost connection to the server. Check that the server is running and the network is up.

Stop connecting

You explicitly terminated the debug session when it was connecting.

Debug session finished

You explicitly terminated the debug session when it was running.