Debugging your AssemblyLine

One of the most powerful features of IBM® Security Verify Directory Integrator is its built-in AssemblyLine Debugger that allows you to walk through the execution of your AL, viewing and even modifying data in-flight.

Let's step through your first AssemblyLine by clicking the Start Debug session button.

Figure 1. Debugging your AssemblyLine

Instead of the standard Run Console window, you will find yourself in the Debugger.

Figure 2. The AssemblyLine Data Stepper

The AssemblyLine Debugger offers two modes: the Data Stepper, which provides simple, straightforward testing features, and the advanced AL Debugger where you can dig deeper – like stepping through scripts, interactively working with Java™ libraries and modifying data on-the-file.

The Data Stepper is a useful tool for stepping through the execution of your AssemblyLine Connectors and viewing the data read, written and transformed. This screen is divided into three main areas:

• The AssemblyLine Outline shows your AL, highlighting where execution is paused;
• The AssemblyLine Work Bucket which displays all Attributes mapped into the Work Entry – that is, those found in Input Maps or Attribute Map components.
• AssemblyLine Components, Attributes and Values where you have a button row for controlling your debug session and a set of data display grids for all Connectors in the AL.

Along the bottom you can see a Console output window that shows the same information that you got when you ran your AssemblyLine using the Run button.

At this point your AssemblyLine has been dispatched to the test Server and is ready to start running at your command. Press the Next button to begin stepping.

Figure 3. Stepping into the AL run

Notice how three things happen onscreen: the AssemblyLine Outline shows that the "Read_CSV_File" Connector is currently active; the AssemblyLine Work Bucket displays the Attributes just read by this Connector; and the data display grid for this Connector is also populated with these Attributes. Each time you press the Next button execution continues to the step and the information displays are refreshed.

You can also use the Run To Here button at the top of the data grid for a Connector to jump to this point. Do this now for the "Write_XML_File" Connector.

Figure 4. Stepping to the Write_XML_File Connector

This data grid then displays the Attributes in the Output Map of this Connector along with their values – including the computed value for "FullName".

Now let's look at the Data Stepper toolbar buttons to see what options you have:

• Next > moves processing to the next component and updates all data display areas;
• Continue will cause your AL to continue execution until it is finished;
• Stop terminates the run immediately;
• Show/Hide lets you decide which Connector data grids are displayed;
• Debugger switches you to Full Debugger mode where you can step through script code, set breakpoints, view and modify any Attributes and script variables, and interactively execute JavaScript commands in the context of your running AssemblyLine.

Although the Data Stepper provides a wealth of information about how your AssemblyLine will perform, sometimes you need the added power of the advanced Debugger. Note that you can switch between Stepper and Advanced modes as often as you want during a debugging session. Try it now by pressing the Debugger button located at the far right of the Data Stepper button row.

Figure 5. Advanced Debugger mode

When you switch modes the screen is redrawn to provide new controls for the AssemblyLine Outline and the AssemblyLine Work Bucket is replaced with the Watch List on the right side of the window. The Watch List shows the standard Attribute buckets: work and conn. There is also a folder called "Global variables" that if opened displays all variables defined for your AssemblyLine: both the built-in ones like

work and

system, plus any that you define in your script code. The last Watch folder is for your own use and you can add variables or entire JavaScript expressions that you want to watch by using the Edit Watch List button at the top of this panel.

Turning our attention to the AssemblyLine Outline, the boxes next to components in this tree-view are called Breakpoints and you can tell IBM® Security Verify Directory Integrator to pause at any component during execution by clicking on one of these. You can also right-click on any node in and select Run and break here to bring AL execution to this point. The toolbar above the outline gives you some of the same controls that you had in the Data Stepper, plus a couple of new ones:

Figure 6. Debugger buttons

Starting from the left these buttons are:

• Step Into which allows you to step into Attribute Maps, scripts and even into the underlying workflows of the AssemblyLine and its components. These waypoints in the built-in flows are called "Hooks" are covered in a later exercise;
• Step Over is the same as the Next > button you saw in the Data Stepper. In the Debugger it also lets you stop over script function calls instead of into them;
• Continue causes the AL to run until completion (just like in the Data Stepper) or until a Breakpoint is reached;
• Stop halts your AssemblyLine, as it does in the Data Stepper;
• Clear All Breakpoints removes any Breakpoints that you have set for your AL.

To get a feel for how Breakpoints work try setting one for the "Write to log" script by clicking in the box next to this component.

Figure 7. Setting a breakpoint

Now press the Continue button and your AL will run until the IF-Branch is true and you find control at the "Write to log" Script. IBM® Security Verify Directory Integrator also opens up a Script area allowing you to step through the code here. You can even set Breakpoints at any script line by double-clicking in the margin to the left of that line.

Figure 8. Setting a Breakpoint in script

Furthermore, you can double-click on any node in the component list to view the Debug display. As you can see in the figure above, there is a button titled Breakpoint Condition. You can use this to set a JavaScript expression that must evaluate to either true or false and which will determine if a Breakpoint is active or not. For example, the Breakpoint shown above could be set to be true if:

 work.First.startsWith("R")

or

 mycounter > 1000

This is very handy for debugging issues that only occur deep in some input data set.

And if for some reason you need to go back to a previous step then simply stop and restart your debug session. You can also switch back to the Data Stepper by pressing the Data Stepper button.

But before you leave the advanced Debugger there is one more feature worth noting: the JavaScript Evaluation commandline.

Figure 9. JavaScript Evaluation commandline

This innocent looking input field above the log output area allows you to execute any snippet of script in the context of your running AssemblyLine. Try it now by typing this command and pressing Enter:

    task.dumpEntry(work)

This will display the contents of the Work Entry in the log output window. Now try this:

   i = 42

You will see the following message appear in the log: i=42 >> 42.0

This tells you that you have defined a new variable ('i') with the value of 42. The expression itself evaluates (as all script statements do) to the value of the assignment. You can also change the values of variable and Attributes already defined in your AL, for example:

    work.First="Rudy"

After executing this line then the value of the "First" Attribute will be "Rudy". The ability to modify data in-flight means that you can make sure your AssemblyLine steps into all branch logic, allowing you to thoroughly test your solution.

It is highly recommended that you spend some time to familiarize yourself with the AssemblyLine Data Stepper and Debugger. Not only does it provide unique insight into how your AL operates, including all the built-in workflows provided by the IBM® Security Verify Directory Integrator Server kernel, but it will also help you validate your own implementation and assumptions about your data.