Synchronicity, transactions, and errors

Error handling for workflows depends on whether the workflow is running synchronously or asynchronously.

Synchronous and asynchronous workflow

It is possible to start workflow either synchronously or asynchronously. To do so, use one of the start methods described in Instantiating a workflow. These methods are:

start()
start(version)
startAsynchronously()
startAsynchronously(version)

If a workflow runs synchronously, then it continues to go through one AutoStep Workflow Step or ManualStep Workflow Step after another until it arrives at a stop condition. This advance through the workflow can encompass one or multiple steps. The workflow executes the current step unless there is an error, and then continues to the next step, if possible. There can be many different reasons that a workflow cannot continue to the next step.

For example, the workflow can enounter:

An activity step (ActivityStep Workflow Step). This can result in the creation of one or more activities, causing the workflow to pause until the closure of all the activities.
A communication step (MessageStep Workflow Step), which can result in a message being sent to another system, causing the workflow to wait until receiving a response.
A step that stipulates a timeout (ManualStep Workflow Step), which causes the workflow to wait for the timeout to complete.
It can encounter a step that requires a trigger (ManualStep Workflow Step), which causes the workflow to wait until someone (or something) activates the trigger.

Ultimately, the workflow can run until it reaches an Outcome Workflow Step, at which point, it is done.

After pausing, the workflow waits for one of the following to occur:

If waiting on one or more activities to complete, it continues after the closure of the last activity.
If waiting for an acknowledgment of a message, it continues after receiving the appropriate response.
If waiting on a timeout, it continues after the timeout elapses.
If waiting on an external trigger, then someone or something must manually invoke a TRIGGER from outside the workflow infrastructure. This can happen either from the PolicyCenter interface (a user clicking a button) or from Gosu. In either case, this is done through a call to the invokeTrigger method on a Workflow instance.

The action of completing an activity or the receipt of a message response automatically creates a work item to advance the workflow. A background batch process checks for timeout elements. It is responsible for finding timed-out workflows that are ready to advance and creating a work item to advance them.

The `invokeTrigger` method

If a user (or Gosu code) invokes an available trigger (TRIGGER) on a ManualStep Workflow Step, the workflow can execute either synchronously or asynchronously. A Boolean parameter in the invokeTrigger method determines the execution type. This method takes the following signature:

void invokeTrigger(WorkflowTrigger triggerKey, boolean synchronous)

For example (from PolicyCenter):

policyPeriod.ActiveWorkflow.invokeTrigger( trigger, false )

The trigger parameter defines the TRIGGER to use. This must be a valid trigger defined in the WorkflowTriggerKey typelist.

The synchronous value in this method has the following meanings:

`true`	(Default) Instructs the workflow to immediately execute in the current transaction and to block the calling code until the workflow encounters a new stopping point.
`false`	Instructs the workflow to run in the background, with the calling code continuing to execute. The workflow continues until it encounters a new stopping point.

Trigger availability

For a trigger to be available, the workflow execution sequence must select a branch for which both of the following conditions are true:

A trigger must exist on the step.
There is no other determinable path (which usually means that no timeout has already expired).

Thus, if both of these conditions are true, after an invocation to the invokeTrigger method, the Workflow engine starts to advance the workflow from the selected branch again.

Invoking a trigger

Invoking a trigger (either synchronously or asynchronously) does the following:

It updates the workflow. Any changes made to a transaction bundle that were committed by the actual invocation of the trigger, are committed.
It causes the workflow to create a log entry of the trigger request. If there is an error in the workflow advance, any request to the workflow to resume causes the process to start again.
If the Workflow engine determines that all the preconditions are met for continuing, it does the following:
1. It determines the locale in which to execute.
  This is the locale that PolicyCenter uses for display keys, dates, numbers, and other similar items. By default, this is the application default locale. It is important for the Workflow engine to determine the locale as it is possible to override this locale for any specific workflow subtype. You can also override the locale in the workflow definition on the workflow element.
It steps through each of the workflow steps (meaning that it performs all the actions within that step) until it cannot keep going.
It commits the transaction associated with the executed steps to the database.

Error handling and transaction rollback

If there is an error during a workflow step, the Workflow engine rolls the database back and leaves it in the state that it was previouosly in. If working with an external system, you need to do one of the following:

Design the services in the external system.
Use the Guidewire message subsystem to keep an external system state in synchronization with the application database state.

It is important to understand whether a workflow executes synchronously or asynchronously because the type of execution affects errors and transaction rollbacks.

Execution type	Application behavior
Synchronous	If any exception occurs during synchronous execution, even after the workflow has gone through several steps, PolicyCenter rolls back all workflow steps, along with everything else in the bundle. The error cascades all the way up to the calling code, which is the code that started the workflow or invoked the trigger on the workflow. If you start the workflow or invoke the trigger from the PolicyCenter interface, PolicyCenter displays the exception in the interface. If some other code started the workflow, that code receives the exception.
Asynchronous	If any exception occurs during asynchronous execution (as it executes in the background), PolicyCenter logs the exception and rolls back the bundle in a similar manner to the synchronous case. PolicyCenter then handles workflow retries in the standard way through the worker. PolicyCenter leaves the work item used to advance the workflow checked out. It simply waits until the `progressinterval` defined for the workflow work queue expires. At that point, a worker picks it up and retries it. The work queue configuration limits the number of retries. If all retries fail, PolicyCenter marks the work item as failed and it puts the workflow into the `Error` state. A workflow in the Error `state` merely sits idle until you restore it from the Administration tab within PolicyCenter. Restoring the workflow creates another work item. After you manually restore a workflow from an `Error` to an `Active` state, it again tries to resume whatever it was doing as it left off, such as: Entering the step Following the branch Attempting to perform whatever it was doing at the time the exception occurred Of course, if you have not corrected the problem that caused the error, then the workflow can drop back into `Error` state again. It does so only after the work item performs its specified number of retries.

Execution type

Application behavior

Synchronous

If any exception occurs during synchronous execution, even after the workflow has gone through several steps, PolicyCenter rolls back all workflow steps, along with everything else in the bundle. The error cascades all the way up to the calling code, which is the code that started the workflow or invoked the trigger on the workflow.

If you start the workflow or invoke the trigger from the PolicyCenter interface, PolicyCenter displays the exception in the interface.
If some other code started the workflow, that code receives the exception.

Asynchronous

If any exception occurs during asynchronous execution (as it executes in the background), PolicyCenter logs the exception and rolls back the bundle in a similar manner to the synchronous case.

PolicyCenter then handles workflow retries in the standard way through the worker. PolicyCenter leaves the work item used to advance the workflow checked out. It simply waits until the progressinterval defined for the workflow work queue expires. At that point, a worker picks it up and retries it. The work queue configuration limits the number of retries. If all retries fail, PolicyCenter marks the work item as failed and it puts the workflow into the Error state. A workflow in the Error state merely sits idle until you restore it from the Administration tab within PolicyCenter. Restoring the workflow creates another work item.

After you manually restore a workflow from an Error to an Active state, it again tries to resume whatever it was doing as it left off, such as:

Entering the step
Following the branch
Attempting to perform whatever it was doing at the time the exception occurred

Of course, if you have not corrected the problem that caused the error, then the workflow can drop back into Error state again. It does so only after the work item performs its specified number of retries.