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.