Workflow Scripts
The following information applies to each of the script files for
- Site Workflows
- List Workflows
- State Machine Workflows
- Email Workflows
- PowerShell Workflows
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
.