Recovering Suspended Tokens

Introduction

When users work on a process, a process token moves along the designed process model, which is defined by the process elements and their connections. Suspension happens when a failure occurs during the process instance update operations, that is, when the process tokens are processed and moved. Failures typically happen in the following processing phases:

1. When the token is "incoming" to a process element.
2. While the token is locally processed (the actual processing of the functionality defined by the token's current process element).
3. When the token is "outgoing", that is, the local processing has been completed and the token is about to move to the following process element.

These phases are illustrated in Figure 1:

Figure 1: Phases a token goes through when visiting a process element

Depending on the phase a token is in and on the type of process element the token is currently visiting, either the process instance itself or the process token is suspended.

There are various cases in which process instances or process tokens can be suspended. For each of them, we will describe where and how suspension happens, as well as how the suspended process instance or token can be recovered.

General Cases

Suspension can happen in the very first steps of a process instance update operation, that is, before the tokens are moved.

1. The process id is not set on the token set. This can happen at a very early stage of the Sub-Process initialization, when a failure occurs before the process id is set. As a consequence, the parent is suspended.
   • Root process tokens: the process instance is suspended.
     • Solution: Reactivate Process Instance.
   • Sub-process tokens: the Sub-Process token is suspended.
     • Solution: Restart Process Token.
2. The model (Business Object) of the current process element was not found. As a consequence, the parent gets suspended.
   • Root process tokens: the process instance is suspended.
     • Solution: Reactivate Process Instance.
   • Sub-process tokens: the Sub-Process token is suspended.
     • Solution: Restart Process Token.
3. A process token is found, where the element does not exist anymore. In the case of a new model/Business Object version where a process element has been removed, suspension happens on the first update operation after the process instance is migrated to that version. The process token is suspended.
   Error message: "Process Element not found for Process Token: [token id] (workflow: "[Process ID], version=[version uuid], element=[element id, e.g. 5].
   Solution: The process token cannot be reactivated "on site", therefore you need to:
   1. Migrate back to the previous version and reactivate the process token according to the reactivation rules specific to that process element.
   2. Move the token to an existing element in the process (typically the element before or after the removed element). This requires an analysis of the process design to find the best solution.

Incoming Tokens

An incoming token is a token that is still sitting on the incoming connection. The process element checks if the incoming token should be "pulled" onto the element. Suspension happens for incoming tokens in the cases described below.

Complex Gateway

If the join expression on a complex gateway (for incoming tokens):

• Throws an exception
• Does not return an Indexed Collection of WorkflowToken
• Or the returned Indexed Collection contains a null entry

Solutions:

• Root process tokens: the process instance is suspended.
  Solution: Reactivate Process Instance.
• Sub-process token: the Sub-Process token is suspended.
  Solution: Restart Process Token.

Other Cases

Suspension happens when an incoming token encounters a problem, for example:

• The model (Business Object) of the current process element was not found. As a consequence, the parent item (process instance or Sub-Process token) is suspended. Solution:Reactivate Process Instance.
• An internal (processing) error occurs.
  Solution:Reactivate Process Instance.
• A token either sits on a process element defined by an extension that is not running/installed, or such an element has an incoming token. The parent item (process instance or Sub-Process token) is suspended.
  Exception: "Custom Task implementation not found: < ExtensionName > : < ClassName >"
  Solution: Install and start the extension, Reactivate Process Instance.

Local Token Processing

Process tokens are suspended while processing a token on a process element and a processing exception is thrown. Such exceptions occur in various situations, depending on the process element definition, as detailed below.

NOTE: General error handling can be defined at different levels:

• At the process element level.
• If set to "default" on the process element,
  • Inherited from the current process model or
  • In FNZ Studio configuration.

Based on the defined error handling strategy, process exceptions are ignored, tokens get suspended, or exceptions are propagated upwards.

During the local processing phase of a process element, some general steps common to all process elements are performed, where processing exceptions can be thrown. These include the whole processing life cycle, including loop preparation and processing. Note that loops can only be defined for process activities, not for events.

1. Loop preparation (if a loop is defined)
2. Process element-specific token initialization
3. Process element-specific token processing
4. Process element-specific token completion/post-processing
5. Loop completion/post-processing (if a loop is defined)

In the following sections, we will first identify those cases in which a token gets suspended in the loop preparation and processing (Steps 1 and 5). Then, we will detail the cases in which element-specific processing can lead to suspension (Steps 2 to 4).

Loop Defined on Process Activities

When a loop is defined on a process activity, there are several loop-specific properties set on the process token that help identify the actual stage of the loop processing. Depending on the type of loop and on whether the loop is processed sequentially or in parallel, different properties are defined, as shown in Table 1.

	Sequential Processing	Parallel Processing
For loop	LoopIndex LoopStart LoopEnd LoopIncrement	LoopId (id grouping loop tokens) LoopIndex (see Note 1)
For Each loop	LoopIndex = 1,2, ... , n LoopCollectionVariable (internal variable)	LoopId (id grouping loop tokens) LoopIndex = 1,2, ... , n
While loop	LoopIndex = 1,2, ... , n	LoopId (id grouping loop tokens) LoopIndex = 1,2, ... , n

Table 1: Loop token properties

Note: LoopIndex starts from LoopStart, and increments using LoopIncrement up to LoopEnd.

These properties can be inspected for any running process instance with a token on a loop activity, as shown in Figure 2. In that example, the current process token is the first loop token (LoopStart=1, LoopIndex=1) out of five (LoopEnd=5, LoopIncrement=1).

Note: These properties are internal and subject to change. Therefore, in FNZ Studio's solutions, they should only be used to perform inspections during the manual recovery of suspended process tokens.

Figure 2: Screenshot of loop attributes

We will focus on the problems that may occur first in a parallel loop, and then in a sequential loop.

Parallel Loop Preparation

The parallel loop has a token preparation phase. As an indicator, in this phase, loop properties have not been set yet for tokens. Suspension can happen in the following cases:

• For loop (See Figure 3 for loop attributes)

  • Error in the evaluation of the start, end or increment expressions.
  • Any return value of those expressions is not convertible to an integer.
  • Number of iterations > nm.workflowengine.maxloopiterations.

  

  Figure 3 : Screenshot of attributes for "For loop configuration"

• For Each loop

  • Error in the evaluation of the collection expression.
  • Return value of the collection expression is not of type collection.
  • Collection size > nm.workflowengine.maxloopiterations

• While loop

  • Error in the evaluation of the while condition.
  • While condition does not return a Boolean.

General Solution: Restart Process Token

During Parallel Loop Processing

A failure while processing a parallel loop can lead to the suspension of the process token. The recovery of these tokens is not loop-specific, but depends on the type of process activity. See Section 4.2 for the types of failures that can occur for each process activity and how these tokens can be recovered.

End of Parallel Loop Processing

A token is suspended when a process instance has been migrated from a non-loop activity to a loop activity. In this case no loop id is set, which leads to failure.

Solution: Manually Move Token (to the following element in the process flow).

Sequential Loop Preparation and Processing

In a sequential loop, loop tokens are generated on the go while the loop condition is valid. There is a short preparation phase at the beginning, where the loop expression is first evaluated. In addition, there are short preparation steps in each iteration, during which a new loop token is created, before the loop-specific properties are set. In this phase, the process token can get suspended in the following cases:

• For loop (See Figure 3)
  • Error in evaluation of start, end or increment expressions.
  • Any return values of those expressions are not convertible to an integer.
  • Number of iterations > nm.workflowengine.maxloopiterations.
• For Each loop
  • Error in evaluation of collection expression.
  • Return value of collection expression is not a collection.
  • Collection size > nm.workflowengine.maxloopiterations.
• While loop
  • Error in evaluation of while condition.
  • While condition does not return a Boolean.

General Solution:Restart Process Token.

Between Iterations of Sequential Loop

Between the iterations of a sequential loop, the process token may get suspended in the following case:

• For and For Each loop:
  • The reverse condition evaluation fails. This condition is used to navigate back to a previous value within a loop: for example, if the loop defines a sequence over a party screen, we navigate to the previous party.

Solution: Fix the problem and set the token to completed.

During Local Processing of Activity of a Sequential Loop

As with the parallel loop processing, a failure during the activity processing in a sequential loop can lead to suspension. The recovery of these tokens is not loop-specific, but depends on the type of process activity. Check the Process Activities section for information on the types of failure that can occur for each process activity and how those tokens can be recovered.

Process Activities

Process tokens can be suspended during activity-specific token initialization and processing.

Generally, after initialization, the token status is directly set either to completed or ready (for example if a user interaction is required or a service call is invoked). In these cases, the token waits to be set to complete from an external action. Failures caused during "external actions" (such as service calls) or during user interactions do not lead to suspension. However, Integration Links and (embedded) Sub-Processes are an exception to this.

The specific cases in which a token can be suspended depend on the activity the token is currently visiting. They are detailed in the following sections.

Activity Overview

Table 2 summarizes, for a number of process activities, all the cases in which tokens can be suspended and how they can be recovered: TokenSuspension_Summary_Table.pdf

PDF Generation Task

A process token can be suspended for a PDF generation task if one of the following failures occurs:

• Unexpected failure of the PDF generator. Solution:Restart Process Token if the PDF(s) need to be generated, otherwise set it to completed and update.
• Empty list of actions. Solution: Analyze why no actions have been set. Based on this analysis, move the token back in the process to re-run, or set it to completed and update.

Screen Task

A process token can be suspended on a Screen task if one of the following failures occurs:

• In the Properties tab, when selecting a screen in the process model:
  • Screen property:
    • No screen has been selected.
    • An expression has been defined and leads to a validation error or the return value is NULL or an empty string.
    • The selected/calculated screen does not exist.

Solution:Restart Process Token.

Integration Link Task

A process token can be suspended on an Integration Link task if one of the following failures occurs:

• During Integration Link initialization:

  • If, for the Integration Link id property:
    • No Integration Link is set/has been selected.
    • An expression has been defined and leads to a validation error or the return value is NULL/empty.
  • The Integration Link does not exist.
  • The Integration Link is not started.
  • If, for the message property:
    • The expression leads to an evaluation error.
    • The expression return value is not serializable.

  Solution: Restart Process Token.

• During Integration Link processing:

  • For synchronous Integration Link calls:
    • An exception is thrown during the Integration Link processing.
      • The expression evaluation fails.
      • The expression return value cannot be assigned to the binding variable.
  • For asynchronous Integration Link calls:
    • An exception is thrown during the Integration Link call processing.
    • When the processing has already been completed successfully and:
      • The call return value cannot be assigned to the binding variable.
      • There is an error in the evaluation of the return value binding expression.
    • When the Integration Link call failed during processing.

  Solution: Restart Process Token or manually compensate (in any case, an analysis of the situation is required).

Sub-process

A Sub-Process can either be suspended during the initialization phase or while tokens on process elements are processed, as detailed below:

• Initialization of the Sub-Process. The Sub-Process token can be suspended in the following cases:

  • Process property:
    • No process is set.
    • A failure in the evaluation of the process expression occurs.
    • The expression result is null or an empty string.
  • Max nesting depth > nm.workflow.nesting.maxdepth (16).
  • Participant evaluation fails, see Table 2.
  • Due date evaluation fails, see Table 2.
  • Task list name evaluation fails, see Table 2.
  • The selected process does not exist. Solution: Restart Process Token. Note: Here, the process token refers to the Sub-Process token (the one sitting on the super process element). You can check if any tokens other than the Sub-Process token have been created in the scope of the Sub-Process. It is safe to assume that the Sub-Process has been initialized, otherwise, you are still in the initialization phase and you can use this solution.

• Within the Sub-Process scope: a suspension during the processing of the process element defined by the Sub-Process is "specific to the process element type", as is its recovery. Check Section 4 for the types of failures that can occur for each process element and how those tokens can be recovered.

Intermediate Events

A process token is suspended if an exception is thrown in one of the following cases:

• Conditional Intermediate Event
  • Evaluation of the condition expression fails.
• Receive Message Intermediate Event
  • Evaluation of the receive message filter expression fails.
• Receive Signal Intermediate Event
  • If the signal name is defined by an expression and its evaluation fails.
• Send Message Intermediate Event
  • No message queue has been selected. Error Message: "No Process Message Queue selected"
  • If an expression has been defined for the message queue.
    • Message queue expression returns null. Error message: "No Process Message Queue selected".
    • Evaluation failure in the script code of any message properties (see Figure 4).
    • Lifetime is not a valid time span (example of a valid timespan: 3d 2h 5m).
    • Evaluation of pre-send script fails.
    • Result of the data expression is not serializable.
• Send Signal Intermediate Event
  • Evaluation of the signal name/lifetime expression fails.
  • Lifetime is not a valid time span.
• Timer Intermediate Event
  • Evaluation of the timer expression fails.
  • No timestamp or NULL returned by timer expression.

General Solution:Restart Process Token

Figure 4: Message configuration of Send Message Intermediate Event

End Event

A process token is suspended if an exception is thrown in one of the following cases:

• Error End Event

  • Evaluation of error code expression fails.

  Solution: Restart Process Token.

• Message End Event

  • See Section 4.2.6 (Send Message Intermediate Event)

• Signal End Event

  • See Section 4.2.6 (Send Signal Intermediate Event)

Attached Intermediate Events

When a failure occurs during the processing of attached intermediate events, the parent token is suspended when exceptions are thrown. The parent token corresponds to the process instance when the attached intermediate event is defined in the scope of the root process token or the Sub-Process token (if the attached intermediate event is specified for an activity defined in the scope of a Sub-Process). Whether an exception is thrown or not depends on the type of intermediate event:

• Conditional Intermediate Event:
  • Condition expression evaluation fails.
• Receive Message Intermediate Event:
  • Message filter expression evaluation fails.
• Timer Intermediate Event:
  • Evaluation of time expression fails (variable not found etc.).
  • Time expression returns null.
  • Time expression does not return a date/timestamp.

General Solution

Suspended process instance: Fix Error, Reactivate Process Instance.

Suspended Sub-Process token: Fix Error, Restart Process Token.

Outgoing Tokens

Finally, process tokens can be suspended if an exception occurs for outgoing tokens (before the token leaves an element).

Token Leaving a Link Source Element

• For dynamic targets, when the evaluation of the target expression fails.

• The target element (Link Target element) does not exist.

Solution: Restart Process Token.

Token Leaving Complex Gateway

Process tokens are suspended if there are any problems in the split expression:

• Evaluation of split expression fails.
• Return value is not an Indexed String.
• Return value is NULL.
• Returned Indexed String is an empty list or no matching connection AND no default connection have been defined.

Solution:Restart Process Token.

All the Other Cases with Outgoing Tokens

• Outgoing Conditional Connection
  • Error when evaluating condition expression.
  • Condition does not return a Boolean.
• For labeled connections, if the variable $action does not exist.
• If no outgoing connection could be activated (e.g. no conditional connections could be activated and no default connection exists).

Solution:Restart Process Token.

Overview of Solutions

In this section, we summarize the solutions referenced throughout the document, explaining the steps involved in recovering suspended process instances and process tokens.

Restart Process Token

1. Fix model/expression/error.
2. Restart Token.
3. Update Process Instance.

Reactivate Process Instance

1. Reactivate Process Instance.
2. Update Process Instance.

Figure 6 :

Set Process Token to Completed

1. Set Token to completed.
2. Update Process Instance.

Manually Move Token

1. Manually move Token to target/suitable process element.

2. Update Process Instance.

   Note: Manually moving tokens requires the Process Migration extension. See 'case 5' in the "Example: Typical Use Cases" chapter for details on manually moving tokens.