Handling Process Instance Failures

A process instance may fail if an executing activity encounters an unexpected error condition (that is, one that is not caught and handled by the process itself).

For example:

  • a database connection failure occurs while a database service task is performing an update.
  • a system out-of-memory error occurs while a script task is running.

When a process instance activity is executing, if a system error causes the activity to throw a Java exception, Process Manager places the process instance in a SUSPENDED, HALTED or FAILED state, depending on:

  1. the error handling configuration that has been applied at the activity, process and/or system-wide levels. The BPM runtime supports two types of error handling - suspendOnError and haltOnError.
  2. the version of TIBCO Business Studio that was used to deploy the process application:
    • suspendOnError is only supported by a process application that was deployed from a pre-3.5.10 version of TIBCO Business Studio.
    • haltOnError is only supported by a process application that was deployed from TIBCO Business Studio version 3.5.10.
Note: For more information about haltOnError and suspendOnError and how they are configured, see "Configuring Error Handling Behavior for Process Instances" in TIBCO ActiveMatrix BPM Administration.

The following diagram shows the different states that a failing process instance may enter, the possible subsequent transitions between states and the ProcessManagerService operations that can be used to trigger these transitions.

The following table lists the ProcessManagerService operations that can be used to change the state of halted process instances. End State is the state to which the process instance will be transitioned on execution of the operation.

These are the only state transitions that can be performed using the BPM public API. Any state transitions not shown in this table can only occur as a result of internal operations.  

Operation Description End State
queryHaltedProcessInstances List halted process instances that match certain criteria. Halted
getAvailableProcessInstanceVariables

setAvailableProcessInstanceVariables

Get/set details of variables available to the failed activity for a particular halted process instance. Halted
ignoreProcessInstance

ignoreProcessInstances

Resume execution of a halted process instance, ignoring the failed activity. Active
retryProcessInstance

retryProcessInstances

Resume execution of a halted process instance, retrying the failed activity. Active
cancelProcessInstance

cancelProcessInstances

Cancel execution of a halted process instance. Cancelled
resumeHaltedProcessInstance

resumeHaltedProcessInstances

Resume execution of a halted process instance as if had not halted. The instance therefore immediately enters a FAILED state. Failed
Note: Where there are similarly-named singular and plural versions of these operations:
  • Use the singular-named version of the operation (for example, retryProcessInstance) to change the state of a single, specified process instance.
  • Use the plural-named version of the operation (for example, retryProcessInstances) to change the state of all process instances for a specified process template.