IBM Business Automation Workflow Simplifying Debugging

A few simple tips that can simplify your client side debugging to speed up UI development.

Authors: Leonard Blunt, Greg Ekaprana, Okka Sudaryanto, Diorella Mari Tom

Code Repository

Tips for BAW Toolkit Git Repository

Introduction

This article will give new developer tips on debugging IBM Business Automation Workflow. There are three ways to debug IBM Business Automation Workflow:

• Source URL Name
• console.log
• Java Logger Wrapper

Source URL Name

In Client-Side Human Service (CSHS), there can be instances that we include JavaScript within the Coach by creating a Custom HTML component and inside that HTML we insert an HTML script tag, see example in Figure 1.

Figure 1: Simplifying Debugging Example CSHS using Custom HTML component

If we want to debug the code, we usually add the debugger; statement (see line 7 in Figure 1), which invokes the debugger when the statement is encountered. When we run the Simplifying Debugger Example CSHS, the debugger is encountered but the source code of the function is not displayed, which is shown in Figure 2.

Figure 2: Debugging CSHS using “debugger;” statement

One way to debug this is by inserting a comment at the end of the source function that is of the form:

//# sourceURL=filename.js

Figure 3: generateID() function using sourceURL comment

Note: You can declare any name for "filename.js" as shown in generateID() function in Figure 3.

When you run again the CSHS example, it will now show the source code of the function as expected, see Figure 4. You can now have a full access to the client-side source function where you can step through the code and place breakpoints.

Figure 4: Debugging CSHS using sourceURL comment

console.log

Adding logs in the client side using the console log can be a quick way to explore errors and get further information on logging. It prints out the logged information to the ‘Console’ Tab of the browser.

Most people know the common string build approach which has it limited value and is demonstrated in this simple example

var date1 = new Date();
console.log("Test 01 " + date1);

This console log will show the string that you entered together with the variable of your choice. If the variable type is complex, it will show ‘[Object Object]’ rather than the inside of the object.

Perhaps less commonly known for beginners but very powerful when working with objects and JavaScript API’s from the various IBM UI toolkit or services is to use the ‘coma’ log notation which will log an object in detail. A very useful tip that helps you quickly understand the objects that you are working with.

var myObject = [];
myObject.name = "I'm one";
myObject.data = "For Check";
console.log("Test 01", myObject);

Example of the console.log result when using a complex object

console.log("The data 1 : " + res.result);
console.log("The Data 2 : ", res.results);

This console log will show the string that you entered together with the variable of your choice. If the variable type is complex, it will show the structure of the object. If the variable type is complex and a list it will help you to see the items lists and structure of contained items.

It is considered a good practice to disable or remove debug logging before promotion of code to test. The console.log does not really impact performance in a way that you will notice the effect but it’s rather because its easy for a layman to read your logs and there’s a risk of sharing some sensitive data about your application.

There is one tip for turn on and off the console log without commenting or deleting the entire console log in the code.

It is by instantiating a variable as a Boolean (i.e. variable name is ‘LogOn’), put as global variable and instantiate it before every console log. If the developer wants to check the console log, they could set the the variable true and if the testing is already finished set the variable false. Methodical coding of entry conditions for functions using this approach can help to save a lot of time in debugging.

var logOn = true;
//Change variable logOn to False if you don't need logging the information again
if(logOn){
    
     console.log("The Data 1 :", res.results);
    //Put other console.log under logOn
    ...
}

Java Logger Wrapper

When we are testing processes, human services and service flows, sometimes we want a lot of details regarding the issue or sometimes less information only. To capture the details needed, we can use the Java Logger Wrapper which is a combination of java.util.Logger and WebSphere Application Server (WAS) logging and tracing to configure log settings. When these logs are activated, it should be viewed from the server log.

Java Logger Wrapper consists of two methods: isLoggable and logp. These methods are use in the following service flows:

1. Java Logger isLoggable — checks if a message of a given level should be logged by this logger or not. This method accepts two input parameters: loggerName & loggerLevel, and returns isLoggable, see details in Figure 6.

Figure 5: Java Logger isLoggable Service Flow

Figure 6: Java Logger isLoggable Parameters

2. Java Logger logp — used to log a message which accepts six parameters: loggerName, loggerLevel, sourceLocation, sourceOperation, message and addProcessInfo, see details in Figure 8.

Figure 7: Java Logger logp Service Flow

Figure 8: Java Logger logp Parameters

Log Levels

We need to specify the desired level of logging every time we interact with the log system. Log levels controls the logging details and each level is associated with a numeric value, see details in Table 1.

Table 1: Log Levels

By using the logp and Log levels of java for your server side logging the logs created will follow the server standards and the logs can be analysed with log tools that read the IBM application Server Log format. This creates a consistency in the logging approach. 

Configuring the log settings in Admin Console

The log level is administered in the admin console. Before running your application with logging on, you need to set the log active at the right level. This is done using IBM BAW WebSphere Application Server administrative console, you can specify or change the level detail in a log, you can check the procedure in this link.

Figure 9: Change Log Detail Level in WAS Admin Console

There are two ways to view your logs: first, view the JVM logs from the administrative console and second, view the JVM logs from the machine where they are stored, you can check the procedure in this link. Here is an example view of message log:

Figure 10: SystemOut.log Message

Example

The following examples shows how to use the basic logging capabilities of Java Logger Wrapper. Please note that the log level is configure to FINE as shown in Figure 9.

1. Log message after an error — Using Java Logger logp service, we can log the error message after encountering it.

Figure 11: Example of Logging an Error

Notice in the data mapping, the log level is set to FINE (500), which means if error occurs the message will be logged as shown in log message in Figure 12.

Figure 12: Error Message Logged in SystemOut.log

2. Log message in general flows — Using Java Logger isLoggable service, we check first the log level setting before logging the message, otherwise no message will be logged.

Figure 13: Example of Logging Message in General Flows

The log message will look like this:

Figure 14: Sample Message Logged in SystemOut.log

In case you do not want to show the process task and/or user context information in the log message (information enclose in braces []), you can set the addProcessInfo parameter to ‘false’.

Figure 15: Setting up the addProcessInfo Parameter in Java Logger logp Service Flow

Figure 16: Log Message with no Process Task and/or User Context Information

Remember: If you are in a team with multiple developers working on the same application, you need to consider 3 main things in logging messages: 
1. Must be easily identified and distinguishable from other logs by other developers, or threads in the server (avoid the I'm Here paradigm), 
2. Should be meaningful and understandable by others.  
3. Should include data that makes it searchable