Introduction and Syntax

kenaflow provides a set of PowerShell Cmdlets that allow you to perform frequently recurring tasks in your workflow scripts.

The Cmdlets are designed for the kenaflow runtime environment and can not be used without them, with a few exceptions.

In the following descriptions we use the following syntax:

AnyKindOf-PowerShellCommand 
	[-optionalParameterName] <parameter-value> 
	[-optionalParameter <parameter-value> (<default-value>)] 
	[-optionalSwitch[:<default-value>]] 
	[-parameterWithConstantValues Value1 <or> Value2 <or> Value3]

The PowerShell-Cmdlet is called AnyKindOf-PowerShellCommand.

This is followed by a mandatory parameter whose name -optionalParameterName can be omitted. In this case, only the <parameter-value> has to be specified.

If there are several parameters with an optional name, then the order of their <parameter values> must be strictly adhered to!

The following is a fully optional parameter that has the name -optionalParameter. If this parameter is not specified, the specified (<default-value>) will be used. The default value may be a concrete value or a description, such as (the current list item).

If the parameter name of an optional parameter is specified, a <parameter-value> must also be specified.

In PowerShell there are "switches" that have no actual parameter-value but only exist or do not exist. In PowerShell, for example, there are the much-used switches -Verbose or -Confirm.

A switch always has a default value that is either $true or $false. If the switch parameter is omitted, this default value is used.

If the switch is specified, its value is automatically $true.

To change the default value of a switch from $true to $false, the following lines need to be written in PowerShell:

Remove-Item "...any file..." -Confirm:$false

The Remove-Item command always reassures if a file should really be deleted before deleting it. The -Confirm switch is set to $true by default. In order to execute the deletion of the file without enquiry, -Confirm must be set to $false.

Some PowerShell parameters have fixed presets or options that can be specified as <parameter-value>. The possible values are specified after the parameter, for example:

[-parameterWithConstantValues Value1 <or> Value2 <or> Value3]

In a workflow script, "Value1" or "Value2" or "Value3" can be used.

For some Cmdlets there are several so-called "parameter sets". This means that some parameters may only be used in combination with certain others. If a parameter from a certain parameter set is used, the parameters from other parameter sets are not permitted. An error is thrown and the Cmdlet is not executed.

There may be parameters that apply to multiple parameter sets or independent of parameter sets.

The syntax for such Cmdlets is usually to write these sets as multiple lines. All parameters are specified, including those that are valid for all parameter sets or for several.

Error handling

All kenaflow specific Cmdlets have the optional parameter [-ThrowErrors[:$true]]

This parameter can be used to catch any errors that may occur during the execution of each Cmdlet, so that the execution of the PowerShell script is not hindered.

If you do not specify the switch with the value $false, the errors are passed on to the PowerShell runtime, which can cause the workflow script to break down without any other error handling.

e.g.:

Get-KFUserInfo -UserName 'kenaflow' -ThrowErrors:$false

If an error occurs in this example, then it can be queried with Get-KFLastResult. The return of the Get-KFLastResult Cmdlet then contains an Exception object.

At the level of each workflow script, the ThrowErrors behavior can be set:

Set-KFThrowErrorsPreference [-ThrowErrorPreference] $true <or> $false

Although by default -ThrowErrors is set to $true, this standard can be overridden with Set-KFThrowErrorPreference. When used, this new default setting applies until the end of the current script or until the next use of Set-KFThrowErrorsPreference.

e.g.:

Set-KFThrowErrorsPreference $false
Get-KFUserInfo -UserName 'kenaflow'
$e = Get-KFLastResult

Here, the default setting for -ThrowErrors of Get-KFUserInfo is set to $false by Set-KFThrowErrorPreference. So no error is thrown if the user does not exist.

The value can be overridden for each Cmdlet. e.g.:

Set-KFThrowErrorsPreference $false

#some Code

Get-KFUserInfo -UserName 'kenaflow' -ThrowErrors:$true

An error would be thrown here if the user 'kenaflow' does not exist.

At workflow configuration level in _wfconfig.ps1, the ThrowErrorsPreference = $true parameter can be used to set the default value for the entire workflow and all workflow scripts in the workflow. This value can later be overridden with Set-KFThrowErrorsPreference in the script or with the -ThrowErrors parameter for a Cmdlet.

Discussion