Script Debugging

WorkThru makes heavy use of Jython in scripts, needs, and rules. When the Jython fails it may throw some kind of exception that isn't informative. (Increasing the traceability of these errors is a current development task). In the meantime there are a couple of things that can be done to ameliorate the situation.

Incremental script development

The first approach is to work in a way that these errors don't get put into the scripts in the first place. Let's assume that you have a WipSpec generally defined but are now adding behavior to it. Create a new Wip for this WipSpec into the WipViewer (left-click on the WipSpec in Eclipse and select Create New Wip). Develop the script in the WipViewer's Script Viewer window ( View / ScriptView ) incrementally--maybe only a line or few lines at a time. Also have the WipSpec you're developing opened in the WipSpecViewer? in the plugin. As you get the lines to work in the script viewer window copy and paste them into the script window. After a WipSpecViewer? save, go back to the WipViewer and update the WipSpec with an Object / UpdateWipSpec?.

When the script is fully created you can test it from within the Script Viewer with a:

wip.action("MyScript?", <some args if needed>)

Debugging from inside the script

For a script that is misbehaving there is a relatively simple way to debug it. The WorkThru? / Jython integration provides a mechanism to transfer control from any point within the script to an external command line console in which the developer can type Jython statements to inspect or alter the values of the any of the objects that are executing.

The following describes this procedure:

  1. Make sure that your wipsite.xml is configured for Jython debugging. 
	<jython folder="/jython-2.1">
	    <debug enabled="true" host="localhost" port="15555" />
	</jython>

Notice that the enabled attribute within the debug tag is 'true'. The host and port parameters aim at a socket on which is running the Jython debugging console. The values presented above are the default values. The host parameter defaults to a local debugging console. This console is hard-coded to run on port 15555. If you choose to change this value remember to change it in the debugging console as well.

Caution: See ticket:74. The Jython configuration settings are currently read only once from the site configuration XML of the very first site that is loaded after the Java VM starts.

  1. Start the Jython debugging console. This console is written in Jython itself, is very short (about 20 lines of Jython), and is distributed in the WorkThru?/scripts directory. (This can be found either in the workthru.zip file or here). Start the debugging console window anytime before its used. I often leave mine running for long stretches. 

   C:\EclipseSVN\WorkThru>cd scripts

   C:\EclipseSVN\WorkThru\scripts>\jython-2.1\jython jsdebug.py

   waiting for client...
  1. Whereever you want the remote console to stop insert a line that looks like 'script.debug("any-label-you-want")'. The 'any-label-you-want' string will be displayed in the debugger window when control is transferred to the window. For example, consider how a script called populateFieldGroup has been instrumented. 
    rootFg = wip.getRootFieldGroup()
script.debug("0")
if thisfieldgroup == rootFg:
  script.debug("1")
  wip.insertFieldGroup(rootFg, "Patient")
  wip.insertFieldGroup(rootFg, "LabResult")

4. When the script is executed it will stop wherever a debug method has been invoked. Type in any Jython. You can display variables, execute any WorkThru? or Java method (that you can get to), etc. When you're done testing at this point, simply enter a new command 'exit' and control will return to the script and it will continue executing. The following snippet is invoked by the script.debug("0")statement from the code snippet above: 

C:\EclipseSVN\WorkThru\scripts>\jython-2.1\jython jsdebug.py

waiting for client...

Got a connection from  ('localhost', 4870)
Debug @ 0
>>> rootFg
Lab(24)
>>> wip.getAllFieldGroups()
[Lab(24)]
>>> exit

waiting for client...

Notice that we requested Jython to show us the value of the rootFg object. Then we asked the Wip for all its field groups (it only has one). Then we enter 'exit' and control leaves this window.