Debugging iWay Flows Using IIT's Step Debugger

[Artem]

iWay 9.1.0 introduces a set of tools enabling users to debug their Flows within the integrated environment of IIT in real time. Users are able to launch flows in debug mode, step from one object to another inspecting contents of the document, as well as the variables(sregs) currently in scope. A user can also set breakpoints, override variable values, change the current document, among other functions.

Debugging flows can also be performed in the context of an enclosing application. In this scenario a debug session is started for the whole application, and debugger reacts to breakpoints being hit on flows as a result of the flow being invoked from a channel, an API endpoint or a webservice call.

Debugging a Flow In Standalone Mode

Debugging a flow starts with creating a Debug Configuration. There are several ways to do this.

First, a configuration may be created by selecting Run → Debug Configurations... from the main menu, bringing up the Debug Configurations dialog, and from there creating a new Debug Flow configuration.

Alternatively, use the Debug As shortcut that may be reached by right clicking on a flow resource in the Application Explorer view and selecting Debug As → Flow (will launch the Debug Configurations dialog if no debug configurations yet exist for the flow or launch the previously configured debug configuration) or Debug As → Debug Configurations... to create a new debug configuration.

Finally, debug configurations may be managed/launched by using the context menu of the flow editor. Right click anywhere within the flow editor canvas and select Debug → New... or choose an existing debug configuration that has been previously configured for this flow.

Debug Configurations dialog that pops up lets the user create and manage their flow debug configurations.

Click the Browse... button next to the Flow: text field and select a flow you'd like to debug.

Input Document may be provided by loading a file from the workspace or the local file system (top text field). Alternatively, the document may be typed directly into the text area (bottom text field). The top text field takes priority if both are filled in.

Encoding must be specified when document is provided via a path and the file contains a document that is not binary and is not XML.

Content-Type field specifies the document format.

Select an iWay Runtime configuration to use for starting an embedded server.

When "Break at Start object" debug option is selected, debug session will start and execution will automatically pause(suspend) at the Start object. This is useful when the user would just like to "step" through the flow inspecting data at each point on the flow, without having to previously set any breakpoints.

 

 

 

Once Debug Configuration parameters have been set, the user can click the Debug button and a debug session will be started.

During the start of a debug session the process will check whether there is an embedded server that's currently up and running for the project enclosing the flow. If there's no currently running embedded server, one will be started using the runtime configuration parameter described in previous step. IIT will automatically switch to the Debug perspective, the flow being debugged will be opened in an editor if not already opened, and execution will pause at the Start object (assuming that "Break at Start object" option has been selected).

Debug Perspective consists of Debug view that shows the currently running processes and debug sessions (left hand side), the flow editor (center), and several views supporting debug operations, such as Variables, Document, Breakpoints and Expressions (right hand side).

Picture on the left shows the state of IIT after a debug session has been started and execution suspended at Start object. In the Debug view we can see the flow has a single thread W.debugger.1~flow1 that is currently running. In the editor we can see execution is paused at Start object. This is conveyed by a blue border around the object and  icon which appears at the top left corner of the object and signals that execution is paused and waiting just before the document enters the Start object. The Variables view displays the current special registers and their values.

 

 

 

 

 

The main window's toolbar has several actions that may be used to control flow execution:  Clicking Skip All Breakpoints will cause all breakpoints that has been set to be ignored during debug. Clicking Resume continues execution of the flow. Stop terminates the debug session. Step Over moves to the next spot on the flow where execution may suspend. In the example above, clicking Step Over once moves execution to the spot right after execution of the Start object completes and before the document flows down to the next object(s) on the flow. Mousing over the  icon shows events returned by the object (see below).

Clicking Step Over one more time splits execution into two branches and we can now see two threads currently active (see picture below).

Debug view now shows two running threads. Expanding the thread nodes shows the objects where execution is currently suspended. Select one of the threads or objects in Debug view or one of the highlighted objects on the canvas to control what is shown in the Variables, Document and Expressions views.

 

 

 

 

 

 

 

 

 

Variables View

The Variables View displays special registers currently available on the selected flow thread. The registers are grouped by category. Selecting a variable and then clicking into the value cell lets the user update the current value of the register. Typing into the text field above the table lets the user narrow down the variables list.

Document View

Document View shows the document coming into or leaving the object. The Save button  on the toolbar may be used to save the document into the workspace. The "Override document"   button may be used to override the contents of the document on the currently selected thread. 

Expressions View

Expressions View lets the user add iFL expressions to be evaluated at the spot where a flow's execution is currently suspended. To add a new expression click the "Add new expression" cell inside the table or click the  button from the toolbar. To edit an expression, select it first, then click into the expression cell. Alternatively, click the  button to bring up an edit dialog.

Click Resume  letting the flow run to completion.

Setting Breakpoints

Breakpoints may be set on flow objects at two locations - right before an object starts its execution ("In-edge Breakpoint") or right after an object has completed its execution ("Out-edge Breakpoint"). To set a breakpoint, right click on an object and select either "Toggle In-edge Breakpoint" or "Toggle Out-edge breakpoint". 

When an object has a breakpoint set, it is marked with the icon . It appears at the bottom left or bottom right of an object, depending on whether it is an "in" or "out" edge breakpoint.

Once you have a breakpoint set, reopen the debug configuration you've created in previous steps, and uncheck "Break at Start object" option. Press Debug, a debug session will start and flow execution will pause at the object that has the breakpoint set.

Breakpoint Configuration Options

Once you have some breakpoints set, make sure you're in the Debug perspective. Bring the Breakpoints view to front.

Breakpoints view displays all the breakpoints currently set across all the resources in the workspace.

Unchecking the checkbox next to a breakpoint disables the breakpoint (the breakpoint will be ignored during execution). Objects on the flow that have disabled breakpoints are marked with the icon .

Selecting a breakpoint in the Breakpoints view displays breakpoint details (see below).

Breakpoint details allow the user to control breakpoint execution.

• Hit Count - execution will only be suspended after the breakpoint is reached the specified number of times.
• If 'true' - execution will only be suspended if the provided iFL expression evaluates as 'true'.

 

 

 

 

 

Overriding Events

When execution is suspended on the out-edge of an object, it is possible to override events returned by the object. To do this, make sure flow execution is currently suspended on the out-edge of one of the objects. Right click on the object and choose Override Events... A dialog will appear showing a comma separated list of events that were returned by the object. Make the necessary changes and click OK. Continue debugging and observe the flow reacting to your changes.

             

Application Debug Mode

As already mentioned flows may be debugged in the context of applications. To do this, first make sure you have an application project with a channel or an API with some configured endpoints. Then open the Debug Configurations dialog and configure a new Debug Application configuration (see example below).

Click Debug. A new debug session starts up. Add some breakpoints to the flow(s) in the application project. Trigger those breakpoints by either invoking an API endpoint or submitting a document to the listener. When done, remember to stop the debug session. After making changes to any of the flows being debugged, make sure to restart the runtime configuration to make sure the flow sources in IIT are in sync with the flows deployed to the embedded iWay runtime.

Debugging Flows On Remote Server

It is also possible to debug against an external iWay server using "test servers". This is similar to test running flows against a remote server. To support this two additional debug configurations have been provided - Debug Application (Remote) and Debug Flow (Remote). Instead of specifying an iWay Runtime configuration, the user supplies connection information for an external iSM server. Application project gets built and deployed as a test server instance on the external iSM server, and debugging proceeds similarly to debugging against an embedded server.

 

Edited April 10 by Artem