Workflow Scripts

The following information applies to each of the script files for

Workflow scripts do the actual work in a workflow. These scripts have to be created by the workflow developer.

All workflow types except "State Machine Workflow" have 1 workflow script.

State machine Workflows have a workflow script per workflow state.

Every workflow script can execute all PowerShell commands. This includes all the cool & fancy .NET possibilities that are reachable by PowerShell code.

This is one of kenaflow's strengths: you are not tied to the possibilities that we provide you.

However, kenaflow offers a number of cmdlets for PowerShell, which are described in the chapter Script Reference.

Workflow scripts always start with a param command used by the kenaflow runtime environment to pass necessary objects to the workflow script. These lines are specific to the workflow type.

The next line we call "magic line" because it enables debugging of workflow script from within the workflow execution. You could remove this line but in this case you will not be able to debug workflow scripts with the appropriate kenaflow runtime context!

Magic Line

if($wf-eq$null){Import-Module "<<directory>>\kenaflow.runtime.dll";Invoke-Kenaflow;exit}

<<directory>> is the path to the assembly kenaflow.runtime.dll.

The cmdlet Invoke-Kenaflow does the actual magic for Debugging. You find a description here: Invoke-kenaflow.

Other Workflow Scripts

There are two more workflow scripts that need to be named:

Pre-Query Script

In case of State Machine and List SharePoint workflows it is possible to specify a script before executing the SharePoint list item queries for the actual workflow execution.

It is configured in the worfklow configuration file _wfconfig.ps1

If it is not configured than this is skipped.

IF the workflow script is executed for an remote event the pre-query script is not executed!

What you do in these scripts is the workflow developers thing. E.g. you could read or write data from or to files in the workflow folder. Or you stop the actual workflow execution by some conditions using Stop-KFScript.

The default pre-query script is named preQueryProcessing.ps1 and has the following default content:

param($wf, $config, $eventData)

# This is the code you need to debug. It does not hurt the workflow during prdoction but can be removed of course. 
if($wf-eq$null){Import-Module "<<directory>>\kenaflow.runtime.dll";Invoke-Kenaflow;exit}

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.

  • $eventData is the object that contains the data of the remote event. If the script is executed outside of a remote event this parameter is $null.

Error Handling Script

All workflow types can specify an error handling script.

It is configured in the worfklow configuration file _wfconfig.ps1

If it is not configured than the following mechanism is not present.

The error handling script is executed in case of uncaught exceptions. If you execute a workflow script this could lead to errors in PowerShell - as in every other programming language or application. Especially during development.

If an error / exception occurs the 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 configured the error handling script 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, $list, $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 "StopListWithSuccess" or [KenaflowErrorHandlingResults]::StopListWithSuccess
# 5 or "StopWorkflowWithSuccess" or [KenaflowErrorHandlingResults]::StopWorkflowWithSuccess
# 6 or "StopItemWithFailure" or [KenaflowErrorHandlingResults]::StopItemWithFailure
# 7 or "StopStateWithFailure" or [KenaflowErrorHandlingResults]::StopStateWithFailure
# 8 or "StopListWithFailure" or [KenaflowErrorHandlingResults]::StopListWithFailure
# 9 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.

  • $list contains the current SharePoint list (for State Machine Workflows or List Workflows. IT DOES ONLY EXIST for workflow scripts of the named workflows types. It does not exist for pre-query scripts.

  • $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)

If an error occured inside the error handling script an exception is passed to the workflow engine. There is no "error handling script for the error handling script". (Yes, we got this question once!)

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.

StopListWithSuccess behaves as StopWorkflowWithSuccess for all scripts other than a SharePoint list workflow script or state machine workflow script with multiple lists. The same for StopListWithFailure: it behaves as StopWorkflowWithFailure.

Failure / Success

In case of Email workflows a "Failure" means that the email item is not marked as "read" (IMAP or EXCHANGE) or deleted (POP3).

For all workflow types "Failure" means, that the next run of the workflow is not controlled by "time between execution". The workflow should run again as soon as possible.

Workflow Script Parameters

Here are the parameters / objects passed to workflow scripts by kenaflow.

State Machine Workflow

The following objects are passed in a State Machine Workflow script:

param($wf, $states, $web, $list, $item, $config, $eventData)

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

$states is an object containing all status configurations of the workflow.

$web is the web object on which the workflow operates.

$item is the current list item that the workflow is currently working on.

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

$eventData may contain the 'Remove Event' sent by SharePoint or third party systems to kenaflow. If the workflow script is executed outside the remote event handler this object is $null.

List Workflow

The following objects are passed in a List Workflow script:

param($wf, $web, $list, $item, $config, $eventData)

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

$web is the web object on which the workflow operates.

$item is the current list item that the workflow is currently working on.

$config is a PowerShell hashtable that contains the additional configuration stored in SharePoint. See chapter "Workflow-specific SharePoint lists", subchapter "Workflow Config" list.

$eventData may contain the 'Remove Event' sent by SharePoint or third party systems to kenaflow. If the workflow script is executed outside the remote event handler this object is $null.

Site Workflow

The following objects are passed in a Site Workflow script:

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

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

$web is the web object on which the workflow operates.

$config is a PowerShell hashtable that contains the additional configuration stored in SharePoint. See chapter "Workflow-specific SharePoint lists", subchapter "Workflow Config" list.

$eventData may contain the 'Remove Event' sent by SharePoint or third party systems to kenaflow. If the workflow script is executed outside the remote event handler this object is $null.

Email Workflow

The following objects are passed in a Email Workflow script:

param($wf, $web, $mail, $config)

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

$web this is not $null if the email workflow is connected to a SharePoint web. This is not necessary. In case of "pure" email workflows this parameter is $null.

$mail contains the email that is currently processed.

$config is a PowerShell hashtable that contains the additional configuration stored in SharePoint. See chapter "Workflow-specific SharePoint lists", subchapter "Workflow Config" list. If the workflow is not connected to SharePoint this will only contain the default config values from the _wfconfig.ps1.

PowerShell Workflow

The following objects are passed in a PowerShell Workflow script:

param($wf, $config, $eventData)

$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 config values from the _wfconfig.ps1.

$eventData may contain the 'Remove Event' sent by SharePoint or third party systems to kenaflow. If the workflow script is executed outside the remote event handler this object is $null.

Discussion