How to debug and test your LiveCycle ES processes

Additional Requirements

LiveCycle ES

• Try
• Buy

LiveCycle Workbench ES

• Try
• Learn more

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.

Debugging your process using Variable Logger

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 (string, xml, 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.

Debugging your process using the Execute Script service

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).

Invoking your service from LiveCycle Workbench ES

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.

1. To be able to invoke from LiveCycle Workbench ES, you must modify a Workbench INI file. Locate the file called workbench.ini in the root folder where you installed LiveCycle Workbench ES (the default location is: C:\Program Files\Adobe\LiveCycle ES\Workbench ES\Workbench). Open this file using Notepad.
2. Locate the line -Dcom.adobe.qpacadmin.unsupported.invoke.enable=false —it is at the beginning of the second paragraph (see Figure 5). Change enable=false to enable=true.
3. Save your file.

4. Start LiveCycle Workbench ES. (This setting is only read when LiveCycle Workbench ES starts, so restart LiveCycle Workbench if it is already running.)
5. Open the process map that you want to test.
6. Make sure that the Components view is available to you. (You may have to activate the Components view from the Window/Show Views file menu in LiveCycle Workbench ES.) The Components view will show you all of the components that are running in your system.
7. Expand the Components tree. All services that you create will also be under the same heading: com.adobe.idp.workflow.dsc.service.workflowDSC. Locate this heading and expand it.
8. Expand the Active Services branch.
9. Locate the service you want to test. If you do not see your service, make sure that you have activated it. Once you locate your service's entry, expand it. There should be a single operation (invoke) listed below it.
10. Select and then right-click the invoke operation. 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.
11. Click OK to run your process. Any output variables will be written back to the screen (see Figure 6 for a sample).

Stalled items

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.