Using Rhino Debugger to troubleshoot Integration Agent scripts

Debugging Integration Agent Scripts

The Integration Agent has a built-in debugger with a graphical user interface that allows you to trace through Javascript code and watch variables. If you are familiar with the use of debuggers, you might find this to be a useful tool for developing and troubleshooting Integration Agent scripts.

  • The debugger is particularly well-suited to troubleshooting complex code such as that found in datasync integrations.
  • The debugger is not suitable for troubleshooting code that relies upon imported Java objects or methods.

Accessing the Debugger

To access the debugger, copy the batch script attached to this article into the Integration Agent's tools folder, and then invoke it from a command prompt. (The batch script is in Windows format, but if you are using another operating system, you should be able to easily port the commands to work with your OS shell.)

Using the Debugger

Once you have invoked the debugger, load the main integration script via the Run command in the File menu (or press Ctrl-N).

  • The "Go" button will execute all the code in the main script, as well as any other scripts that are invoked via "load" instructions in the main file.
  • To trace through a script, use the "Step Into" button instead of the "Go" button.
  • To monitor the value of a variable, type its name in the "expression" field of the "Watch" window.
    • This only works while you are stepping through code (ie, it doesn't work if you use the Go button.) It's best to wait until you've stepped through the "var" instruction that instantiates the variable before trying to access its value.
  • You can navigate from one script to another by using the "Window" menu, when more than one script has been loaded.

Limitations and Hints

Imported Java code

The Rhino debugger doesn't handle imported Java code well. The Import statements themselves won't cause trouble, but neither will they make Java objects and methods available in debugging sessions in the same way that they are available when the script is executed by the Integration Agent.

In particular, this will cause errors to be thrown when log instructions ("log.debug", "", "IALOG.debug", etc) are encountered, since these instructions invoke imported Java code. Once this happens, the best thing to do is to exit the debugger and start it again.

Binary code

Before loading the integration script, it's best to comment out any instructions that invoke binary code (such as the log instructions mentioned earlier.) This is easily done with a text editor's search-and-replace tool. Keep a copy of the original script so you can revert after the debugging session.

Step Over

Use the Step Over button to avoid tracing through code that you don't want to debug. For example, if you step over a "load" statement, the target script will not replace the one that you are debugging. The stepped-over code will still have been executed; you just avoid seeing the individual instructions.

Testing code

You can also use the debugger to test code on the fly. As soon as the debugger starts up, you will see a "Javascript Console" window. You can type Javascript code into this window and the results will appear when you click the "Go" or "Step Into" button. For example,

Rhino 1.7 release 4 2012 06 18
js> typeof {"name": "john"};
js> typeof "name";

Forcing methods to process data

Most Integration Agent scripts don't do anything until they receive input, typically from the apclient gateway or the service gateway (the "/http" interface.) These gateways are not available when you use the debugger, and so the scripts will not automatically produce any output after being loaded into the debugger. To test the script with production data, you can extract the data from the Integration Agent log and then add an instruction to the end of the script to send the data to the entry point.

For example, to force the script's apia_http() method to process data:

  1. If the data hasn't already been written to the Integration Agent log, add an instruction to the apia_http() function in the main integration script; e.g.:"Entering apia_http(); httpRequestProperties is: \n" + httpRequestProperties.toString() );
  1. Start the Integration Agent and send the data to it in the usual way (eg, from the management system).
  2. Stop the Integration Agent and extract the data from the Integration Agent log file.
  3. Add an instruction that includes the data to the very end of the main integration script file, similar to the following:
apia_http( "{Content-Type=... (actual data ommitted)..., Host=}", "" );

When sending data to the apia_http function, you need to wrap the data from the log file in double-quotes, and escape any double-quotes in the data with a backslash ('\'). Note the second empty parameter, since the apia_http function expects two parameters.

  1. Comment out any instructions that invoke Java code (such as log.debug, etc.) and save the file.
  2. Start the debugger and run the file as described above. 


xMatters reference: DTN-5414; information supplied by Jeremy Brown

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk