Error Handling

Error Handling Basics

Error handling in scripts is a very importent task for a kenaflow workflow developer.

Errors can happen - as you know - by making things wrong or by having errors in the software (kenaflow => could happen, sorry) or in the infrastructure (SharePoint, Exchange, mail server, network infrastructure, ...)

Normally, all these errors cause exceptions to be thrown in the script.

kenaflow takes exceptions and reports them to the developer. kenaflow also sends emails in case of error, if this is configured in _wfconfig.ps1 or in the global configuration.

There are also possibilities to handle errors before they reach the engine level, i.e. to handle the exceptions within the workflow.

Basically, all mechanisms of PowerShell that every PowerShell developer knows can be used.

try {

	throw "an exception"
} catch {
	Write-KFLog "Handeld error: $($_.Message)"
}

This error is handlet (catched) and not send to kenaflow. The engine will not handle this error because it never get informed about this error.

All cmdlets of kenaflow (that are not part of the embedded "SharePoint Patterns and Practices PowerShell" module) habe the default switch parameter -ThrowErrors with a default value of $true. It can be used to "hide" exceptions.

If specified like this:

Get-KFUserInfo "this is not a valid user" -ThrowErrors:$false

... the exception will not be thrown by the script and not handled by kenaflow. It is also not catch-able with try...catch....

Therefore you can use Get-KFLastResult to get the result of the last kenaflow cmdlet. If an exception occured you will get this exception.

Get-KFUserInfo "this is not a valid user" -ThrowErrors:$false
if( (Get-KFLastResult) -is [System.Exception] ) {
	Write-KFLog "Something went wrong".
}

Instead of specifying -ThrowErrors on each cmdlet you can use the cmdlet Set-KFThrowErrorsPreference to set the default.

You can use to cmdlet Get-KFThrowErrorsPreference to get the current default.

The workflows default is configured in _wfconfig.ps1. If nothing is set exceptions are thrown by default!

Error Handling Scripts

In addition to these options, there is also the option to define an "error handling script" for a workflow.

The script is specified in _wfconfig.ps1.

The setting is:

    #* Here you can specify a script for error handling. It's 
    #*   processed in case of exceptions within the workflow script. 
    #*   Please read https://doc.kenaflow.com/basics/errorhandling 
    #ErrorHandlingScript = "errorHandling.ps1"

As described above if an error / exception occurs the workflow script is aborted. Normally kenaflow handles the error. The default handling is to stop the workflow and inform the developers - if configured - via email.

If an error handling script is configured it is used to process the exception.

The default error handling script is named errorHandling.ps1 and has the following default content. The first line for the parameters differes for the different workfow types. Here is the line for SharePoint list workflows and SharePoint state machine workflows.

param($wf, $config, $exception, $item, $eventData)

if($null-eq$wf){write-error "You need to run a workflow script and force an error.";exit;}


#Return one of these values:
# 0 or "ThrowException" or [KenaflowErrorHandlingResults]::ThrowException
# 1 or "Okay" or [KenaflowErrorHandlingResults]::Okay
# 2 or "StopItemWithSuccess" or [KenaflowErrorHandlingResults]::StopItemWithSuccess
# 3 or "StopStateWithSuccess" or [KenaflowErrorHandlingResults]::StopStateWithSuccess
# 4 or "StopWorkflowWithSuccess" or [KenaflowErrorHandlingResults]::StopWorkflowWithSuccess
# 5 or "StopItemWithFailure" or [KenaflowErrorHandlingResults]::StopItemWithFailure
# 6 or "StopStateWithFailure" or [KenaflowErrorHandlingResults]::StopStateWithFailure
# 7 or "StopWorkflowWithFailure" or [KenaflowErrorHandlingResults]::StopWorkflowWithFailure
#
# "ThrowException" is default in case nothing is send back
#
# "Okay" indicated that the error handling script has handled the exception and the engine must not take care.
#
# You cannot send other data back to _kenaflow_!

return 0

Here is the description of the script parameters:

• $wf denotes the workflow configuration, which contains all the settings defined in the workflow configuration file _wfconfig.ps1.

• $config is a PowerShell hashtable that contains the additional configuration stored in SharePoint. See chapter Workflow Lists.

• $exception contains the exception that caused the abortion of the workflow script.

• $item contains the current SharePoint List item (for State Machine Workflows or List Workflows or Email Workflows). It is $null in case of executing exceptions from the pre-query script (for State Machine Workflows or List Workflows) and it DOES NOT EXIST AT ALL for SharePoint Site Workflows and PowerShell Workflows

• $eventData contains the current remote event data. Or it is $null if there is no event data. For Email Workflows this parameter does not exist!

For SharePoint Site Workflows and PowerShell Workflows the first line looks like this:

param($wf, $config, $exception, $eventData)

For Email Workflows the first line looks like this:

param($wf, $config, $exception, $item)

In case of an Email workflow or an SharePoint List workflow StopStateWithSuccess behaves as StopWorkflowWithSuccess and StopStateWithFailure behaves as StopWorkflowWithFailure.

In case of an PowerShell workflow StopItemWithSuccess and StopStateWithSuccess behaves as StopWorkflowWithSuccess and StopItemWithFailure and StopStateWithFailure behaves as StopWorkflowWithFailure.

In case of errors inside the pre-query script StopItemWithSuccess and StopStateWithSuccess behaves as StopWorkflowWithSuccess and StopItemWithFailure and StopStateWithFailure behaves as StopWorkflowWithFailure.