3 December 2007
There are many ways to debug and test a process or orchestration that you create using the Adobe LiveCycle ES software. Some are obvious and others are not so obvious. This article discusses different techniques that can be used to debug and test your processes.
Often, when you are building up your process, you will add variables to be used at different stages throughout your process. It is helpful to know the state of these variables during your process. The LiveCycle ES software provides a service that will dump the contents of all variables for you to look at. The service is called the Variable Logger and is located under the Foundation category (see Figure 1 for a view of the properties to set up for variable logging).
The information about your variables can be written to the application server log or to a file on disk. I prefer the system log because I can use third-party tools to view the login real time (I use a shareware program called BareTail from BareMetalSoft.com). Note that I change the name of the service to "***** DEBUG1 *****" so that it is easier to spot in the log. Also, if your log viewer can highlight text, then setting it to highlight your ***** DEBUG1 ***** enables you to find it even easier.
The Variable Logger will write out simple types (
int, and so on) so you can see the content in real time, but it cannot write out complex types. For these complex types, the Variable Logger creates a temp file and a reference to the file. You cannot see the contents of your complex variables, but you will at least know that the variable is populated with data.
You can put multiple variable loggers into your process as required to see how the variables change in your process (see Figure 2 for a sample of different variables and how they would appear in the log).
One last technique I find useful is that you can change the start point of your process by right-clicking the service that you want to start and setting the Start action. You can break connections between services as well as have services log an in or out path to them to isolate testing areas.
Another service that is useful for debugging is the Execute Script service found in the Foundation category. This service enables you to execute a Java program (based on BeanShell) so you can write anything you want to the log. By making use of the Process Management APIs, you can get access to additional information that you may want to track (see figures 3 and 4 as an example of a script operation and its associated output).
If you are creating an orchestration (a process without user steps), then it is a bit of a nuisance to get your process started without creating additional collateral to start your process (an Enterprise JavaBean (EJB), a form, a watched folder end point or e-mail end point, to name a few). One technique I find useful is to make use of the web service end point that is created automatically for you whenever you activate your service.
There is a technique you can use to call the web service interface from inside of LiveCycle Workbench ES. Note that this method is unsupported in a production environment, but is perfectly fine for a developer to use to invoke the process in a test environment.
-Dcom.adobe.qpacadmin.unsupported.invoke.enable=false—it is at the beginning of the second paragraph (see Figure 5). Change
com.adobe.idp.workflow.dsc.service.workflowDSC. Locate this heading and expand it.
invoke) listed below it.
invokeoperation. A menu item "invoke operation" should appear. (If it does not, then you have not set up the INI file correctly.) Choose the invoke operation. Your process will now prepare to start. If you have any input variables, then a dialog box will appear allowing you to enter the inputs next to the variable names that you have defined. If there are document objects as inputs, three dots will appear allowing you to pick a file for the document; otherwise, you can type in simple values.
When you are building a long-lived process and the process halts for whatever reason, all trace and error information is written to the application sever log. The location and access to the log file is dependent on the installation as well as the particular application server that you are using.
If you do not have access to the log, a summary of the trace information can be found in the Administrative User interface (adminui). Assuming you have the appropriate rights, you can access it by going to http://hostname:port/adminui. Once you authenticate to the application, choose Services, then LiveCycle Process Management ES. From there you can view all of the stalled operation and branch errors. You can take corrective action (if required) or you can simply view the trace information to see what is causing the problem.