General Workflow Settings

Here are all workflow type independend ("general") workflow settings.

Version = "4.0";

A workflow will only work with the following version of kenaflow. After you tested your workflow with a new version of kenaflow you can change the following setting.

Enabled = $false;

This is used to enable or disable the workflow.

$true means: "Run the workflow" ==> ENABLED $false means: "Do not run this workflow" ==> DISABLED

Slot = 0;

The execution slot.

Default: 0

If slots are not configured in global configuration this setting is ignored!

Priority = 0;

The execution priority.

Default: 0

Type = "";

This specifies the workflow type. Possible values:

  • SHAREPOINT
  • EMAIL
  • POWERSHELL

SubType = "";

This specifies the sub-type of the workflow, depending on the Type.

Possible values are:

  • Type is SHAREPOINT
    • ALL
    • LASTMODIFIED (alias LIST)
    • QUERY
    • SITE
    • STATEMACHINE
  • Type is EMAIL
    • EXCHANGE2007SP1
    • EXCHANGE2010
    • EXCHANGE2010SP1
    • EXCHANGE2010SP2
    • EXCHANGE2013
    • EXCHANGE2013SP1
    • EXCHANGE
    • EXCHANGEONLINE
    • POP3
    • IMAP
  • For Type POWERSHELL this is always empty.

Name = "";

This is the name of the workflow. Technically this will not be used.

Id = "";

Each workflow needs an unique ID (System.Guid).

If two workflows have the same ID things will go wrong. One of the workflow will not execute.

You can create such an ID using this PowerShell command: [guid]::newGuid().tostring('d').

AdditionalConfigFiles = @("..\global_config.ps1")

With this parameter it is possible to control the serialization process of the workflow configuration. Here you can specify one or more files whose "last write timestamp" are checked during deserialization. If the file(s) where modified the workflow configuration is executed and gets reserialized.

ScriptFolder = "";

In 99,99% of all cases the workflow script(s) are in the same folder as _wfconfig.ps1.

But if you need to configure it otherwise you can specify the script folder here.

TBE = 60;

This means "Time Between Execution".

Between two starts of the workflow the configured amount of seconds must elapse.

You can disable a time based run of a workflow if you set TBE < 0.

You need to set TBE to > 0 to use Cron (see below). Because a value < 0 disables time-based runs and that includes Cron based runs.

Cron = "* * * * * *";

You can specify an CRON-style pattern for the time based execution of the workflow.

This CRON pattern will be calculated relative to the last workflow run timestamp.

The setting "30 * * * * *" means: Execute 20 minutes past the full hour - every hour.

The setting "15 8-12 * * * *" means: Execute this 15 minutes past the full hour from 8 o'clock to 12 o'clock.

If the workflow is never run this setting is ignored. The workflow will execute once immediately.

The calculated time for the next execution is not guaranteed by kenaflow, because exact scheduling is not possible.

Permanent = $false;

Sets the workflow to run in a seperate dedicated process instead of the normal queue based execution mode.

Locking = $true;

During a time based workflow run the same workflow should start also on another kenaflow server (in case of scaling). If your really sure that you want to run multiple instances of the same workflow than you can set this to $false.

Default is $true which means: Only one instance of the workflow IF IT RUNS TIME-BASED.

If a certain workflow is started in a remote event handling scenario it can run multiple times in parallel.

CustomLibrary = ""; CustomLibrary = @("");

You can specify one or more custom PowerShell library here. They are executed before the workflow script is executed.

In the libraries you can initialize variables and provide functions.

You can share such libraries with multiple workflows!

On global level there can be one custom library, configured in global configuration Section "Basic".

If this global custom library is specified it will be executed before the workflows custom libraries, if one or more are specified.

ErrorHandlingScript = "errorHandling.ps1"

Here you can specify a script for error handling.

It's processed in case of exceptions within the workflow script.

Please read this artice for details Error Handling.

PreProcessingScript = "preProcessing.ps1"

This script is executed after the workflow is started. Before any connection, e.g. to SharePoint, is initiated.

The script start with this line to receive the correct parameters:

param($wf, $eventData)

PostProcessingScript = "postProcessing.ps1"

This script is executed before the workflow is finished.

The script start with this line to receive the correct parameters:

param($wf, $eventData)

Debug = $false;

You can mark a workflow as being "in debug".

You can evaluate the debug state with Cmdlet Get-KFInDebug.

This can be used to have script portions that are only executed during debug.

Default: $false.

NoSerializing = $false;

The file _wfconfig.ps1 is a PowerShell script. It is executed when it was changed.

By default the resulting configuration object is serialized for performance reasons.

If you do not which kenaflow to serialize the configuration object and always evaluate _wfconfig.ps1 then you set this setting to $true.

Default: $false

MaxLifetimeOfSerialization = <value>;

The workflow configuration is a script and its return value is the workflow configuration object containing all the settings. For performance reasons this configuration object is serialized. The workflow config is not executed as long as it is not changed or kenaflow is not updated. You can stop the serialization with property DoNotSerialize. But this is a significant loose of performance. Therefore you can use the property MaxLifetimeOfSerialization to specify the maximum lifetime of the serialization. <value> can be a System.TimeSpan object or a timespan as string or an amount of seconds as System.Int or an amount of seconds as number in a simple string. This is equivalent:

  • MaxLifetimeOfSerialization = [System.Timespan]"0:1"
  • MaxLifetimeOfSerialization = "0:1"
  • MaxLifetimeOfSerialization = "60"
  • MaxLifetimeOfSerialization = 60 All of these examples stand for 1 minute or - to be precise - for 60 seconds.

At time of serialization the next point in time for re-serialization is set and stored in the serialized configuration object.

RunCondition = @{ConfigKey='<a-key>'; ConfigValue='<a-value>'}

This can be used to run or stop the workflow in an early state before items are processed.

You can specify a key as <a-key> from the workflow config list (in case of SharePoint workflows) or a key from the collection ConfigListDefaults (for all workflow types). The value of the key must match the <a-value> setting of RunCondition. This is case sensitive!

If the value does not match the workflow will be stopped.

In case of multi-web SharePoint workflows the comparison is made for each web. If the webs config value for the given key does not match the <a-value> setting the web processing will be skipped. The next web is getting processed.

StopWorkflowOnScriptError = $true;

Here you configure if workflow scripts should be stopped if errors (exceptions) occur during execution.

Default is $true.

ConfigListDefaults = @{ "kenaflow"="cool" };

kenaflow workflows can use key-value-pairs for configuration. For SharePoint workflows and Email workflows with SharePoint connection these settings are stored in a SharePoint list (see property ConfigList above) where process owner (typically not workflows developers) can edit the config values, such es email templates.

Here you specify the default values. They are written to SharePoint when creating the config list with command line switch --createconfiglist.

In case of Email workflows (without SharePoint connection) and PowerShell workflows there is no SharePoint based config list. In this case the content from this setting is passed to the workflow script as config object.

AlertAddresses = @();

In case of workflow errors the configured users will get an email.

Here you specify one or more email.

AltertAddresses = @("developer1@example.com", "delevoper2@example.com")

AlertFloodProtection = 60;

If AltertAddresses are configured (setting above) than the configures users will receive mails in case of workflow errors.

Here you can configure an amout of seconds between two of such error mails. This can help to prevent email flood.

Default: no flood protection.

MailFrom = "";

Address of the sender of mails that the workflow sends.

If empty (default) it will be taken from the kenaflow global config.

MailReply = "";

Address of the "reply-to" address of mails that the workflow sends.

If empty (default) it will be taken from the kenaflow global config.

MailSubjectPrefix = $null;

You can specify a prefix for the eMail subject of every mail that is sent from this workflow. But the global setting subjectPrefixOverwrite of kenaflow must allow this to work!

Use $null to use the global setting (if specified) or use empty string ("" = two double or '' = two single quotes) to have 'no' prefix, (if the admin allowed you to overwrite the global setting)

Default (if not specified) is $null

MailSubjectSuffix = $null;

You can specify a suffix for the eMail subject of every mail that is sent from this workflow. But the global setting subjectSuffixOverwrite of kenaflow must allow this to work!

Use $null to use the global setting (if specified) or use empty string ("" = two double or '' = two single quotes) to have 'no' suffix, (if the admin allowed you to overwrite the global setting)

Default (if not specified) is $null

MaxExecutionTime = -1;

After this amount of time elasped the workflow execution will be stopped

Default: -1

-1 = use default from global configuration.

ThrowErrorsPreference = $true;

If the execution of a kenaflow sepcific Cmdlet fails an exception will be thrown by default. This causes the workflow script to stop.

The default is $true.

If you set this setting to $false you can supress exceptions.

If an exception occures it can be read by using cmdlet Get-KFLastResult.

ErrorActionPreference = 'Stop';

PowerShell commands such as cmdlets can fail during execution. PowerShell has a default error handling mechanism that allows the PowerShell runtime to coninue its work or handle errors in a different way, e.g. asking the user to continue or stop.

With this setting you can specify the default action of PowerShell in case of errors in the workflow script.

  • Stop : Stop the script
  • Continue : Report the error and continue the script execution if possible
  • 'SilentlyContinue` : Do not report the error and continue silently if possible

This default handling can be overwritten when execution the script in the debugger by setting -ErrorActionPreference parameter of Invoke-Kenaflow.

writeMailsToDiskDuringDebug = $true;

When running a workflow script in a debugger such as Visual Studio Code or Windows PowerShell ISE all mails are written to disk by default. The folder is configured here: Global Configuration setting mailsOnDisk of Section "MailDev"

A workflow developer should first configure redirectAllMails (description below) and then set writeMailstoDiskDuringDebug to $false.

Default is $true.

alwaysWriteMailsToDiskInsteadSending = $false;

You can force kenaflow to write all mails to files in the file system. This can be used for debug or in case of troubleshooting.

Mails are written to the folder configured in Global Configuration setting mailsOnDisk of Section "MailDev"

redirectAllMails = @();

During workflow development all emails should be redirected to the workflow developer. With this setting you can specify one or more email addresses.

ALL mails the workflow sends will be redirected to this address(es).

SendOutputToMainProcess = $false;

When writing objects to the PowerShell pipeline they will in the last level always be caught by kenaflow runtime environment if no other PowerShell command captures them.

When kenaflow receives such objects they are written to the log IF this setting is $true. Default is $false, so nobody will see the objects.

MaxExecutionTime = -1;

After this amount of time elasped the workflow execution will be stopped;

-1 = use default from global configuration. Default there is 600 seconds.

ScriptFolder = "";

Can be used to configure the folder where the workflow scripts are.

By default its the same folder that _wfconfig.ps1 is in.

FileTemplateStartMarker = ""; and FileTemplateEndMarker = "";

This is used for Invoke-KFFileTemplate and specified the start marker and end marker for placeholders in Word and PowerPoint files.

The default is taken from the global configuration. (Default there is %{ and }%.)

AllowPowerShellPlaceholders

This setting is related to Invoke-KFFileTemplate.

If set to $true Word and PowerPoint templates can contain placeholders of the style <<...>> that are executed as PowerShell code during placeholder replacement.

Default: $false

SmtpServer = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be the host name (DNS) or IP address of your outgoing SMTP server.

SmtpServerPort = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be a valid port as number in the range 1 <= value <= 65535

SmtpUseSsl = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be $true or $false

SmtpUseLegacySender = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be $true or $false

The "legacy sender" uses the .NET Framework implemantation for sending SMTP messaged. The "new sender" (if the setting is $false) the sender of open source library MailKit is used instead.

SmtpSecurity = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be one of the folling numbers:

  • 0 => None
  • 1 => Auto
  • 2 => StartTls
  • 3 => SslOnConnect

SmtpUseDefaultCredentials = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be $true or $false

SmtpUserName = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be a valid user name for SMTP authentication.

SmtpPassword = $null;

Can be used to overwrite the setting in the Global Configuration for this particular workflow.

By default this setting is missing. The Global Configuration setting is then used.

If specified it must be the valid password as plain text for the user in setting SmtpUserName