Handling errors in the production environment

Execution errors
Implementation errors
Monitoring variables using the Variable Logger service
Handling errors using exception event catches
Handling situational errors using the Stall service

You can design processes so that they gracefully handle errors when they occur:

Use the Variable Logger service to monitor process data at run time.
Use event catches to handle execution errors.
Use the Stall service to suspend execution when undesirable situations occur.

Execution errors

An execution error causes a process instance to stall. A process instance fails to complete processing for one of these reasons:

Stalled operation errors

A stalled operation error occurs when an operation in your process version fails during execution. For example, the execute operation from the Set Value service tries to assign a string value to a process variable of the float data type. This value is not valid and causes the operation to stall.

Stalled branch errors

A stalled branch error occurs when a routing condition has an error. For example, you may have a condition on a route that uses a value from a form. The route condition is based on a numeric value, but the form value is inadvertently entered as a string value. This error causes the branch to stall.

You can view the list and details of stalled operation errors or stalled branch errors from within Administration Console. You will see the name of the operation or branch that is stalled, and you can view the details of the trace back that may provide useful information to identify the source of the problem.

Implementation errors

Implementation errors occur when a process version completes execution successfully, but it does not work as it was designed. For example, if you have a route condition to route all high-risk loan applications to the manager, and the manager never gets routed any of these loan applications, you have an error in your process version. The two types of implementation errors are computational and situational.

Computational errors

Computational errors occur when the execution of a command results in an error. For example, an error can occur in a routing condition when the function in an expression uses a parameter of the wrong data type. When the error occurs, the branch or action involved is stalled until the LiveCycle administrator intervenes. The type of branch that your process version uses can mitigate the effects of computational errors.

Situational errors

Situational errors occur when an issue that should not occur does occur during the execution of a process version, even though the process version behaved as designed. For example, a process version assigns a task to a random user in a specific user group. If that user does not complete the task by a certain time, it is incorrectly reassigned to the same user in the group again.

A situational error occurs if the task was reassigned to the same person. To avoid situational errors, you can cause the branch to stall before the situation occurs. The administrator can then intervene and attempt to correct the situation.

Monitoring variables using the Variable Logger service

Use the log operation that the Variable Logger service provides to monitor the values of process variables at run time in a production environment. The Log operation writes variable values to a file, to standard out, or to the LiveCycle Server log at a specific point in the process.

For information about viewing variable values during testing, see Recording and playing back process.

For example, the following process diagram includes a log operation after an Assign Task operation. After the log operation, an execute operation from the Set Value service manipulates the data that the Assign Task operation captures. The log operation saves variable data to a file. If the execute operation stalls at run time, the logged variable values can be used to troubleshoot the error.

View full size graphic

The log operation reports the following information for each variable in the process:

The name of the variable, as an XPath expression
The data type of the variable
The value of the variable
The process identification (PID) of the process instance in which the log operation executed.
The operation identification (ActionID) of the log operation.

The following text is an example log entry that a log operation named log3 provides. The log3 operation has an ActionID of 37, and was executed in a process instance with PID 13. The process includes the two variables named numberVar and listVar:

[PID:13] [ActionID:37] Action Name: "log3" Start... 
[PID:13] /process_data/@numberVar - java.lang.Float: 100000.0 
[PID:13] /process_data/@listVar: null 
[PID:13] [ActionID:37] End!

For more information about the log operation, see log operation.

Handling errors using exception event catches

Exception event catches enable processes to react to errors that occur when an operation executes. For example, when an exception event is caught, the process can write information to a log file, or send an email to the LiveCycle administrator. (See also Catching event throws.)

The following process diagram uses a Remove PDF Password Encryption operation to decrypt a PDF document, and then saves the document to the hard drive using the Write Document operation. If an EncyrptionServiceException exception occurs when the document is being decrypted, the Send With Document operation sends an email to notify the administrator.

View full size graphic

Handling situational errors using the Stall service

Use the execute operation that the Stall service provides to prevent situational errors that you anticipate.

For example, processes can use data that is provided from an external resource, such as a partner’s database. The executeScript operation from the Execute Script service can be used to verify that the data is valid. If the data is not valid, the Execute operation from the Stall service can stall the process instance while the data in the database is corrected.

View full size graphic