List Workflow Configuration

The workflow settings described in this section belong to SharePoint List Workflows.

Type = "SHAREPOINT";

This specifies the workflow type. This must be SHARPEOINT in order to be an email workflow.

SubType = "";

Valid values for a list workflow are:

  • ALL
  • LASTMODIFIED
  • QUERY

Platform = "";

You need to specify the used SharePoint platform here:

  • sp2013
  • sp2016
  • sp2019
  • spo

Environment = "";

This can be used to specify the SharePoint Online hosting environment:

  • production : Default Office365 environment
  • usgovernment : Office365 for US Government
  • germany : Offic365 in the "German Cloud"
  • china : Office365 in China Cloud
  • ppe : ?

Platform must be spo to use this setting!

Connection = <object>

You can execute a SharePoint workflow on multiple lists in multiple webs. The executed workflow script is always the same. All other settings are identical (names of lists such as error list or data list). But the lists can be configured per web. If you configure this property you cannot configure Web, AlternateWebUrls and List in parallel. The <object> looks like this:

Connection = @(
  @{ 
    Web = "https://firstweb.sharepoint.farm"; 
    List = @("List 1", "List 2");
    AlternateWebUrls = @();
  },
  @{ 
    Web = "https://secondweb.sharepoint.farm"; 
    List = "List 3";
    AlternateWebUrls = @();
  },
  @{ 
    Web = "https://thirdweb.sharepoint.farm"; 
    List = @("List 4", "List 5");
    AlternateWebUrls = @();
  }
)

For a description of Web, List and AlternateWebUrls please read the descriptions of the properties below.

Web = "";

Full URL to the SharePoint web where the workflow list is in.

Do not specify this setting if you have configured Connection!

List = @("");

Title (!) of one or more the SharePoint list where the workflow operates on. Each list are called "workflow list".

You can specify more than 1 list. All of them have to resist in the same web. But sometimes it's required to process multiple lists with the same script. There is no need for more than 1 workflow to do that.

You can continue to use a single string: List = "Custom List";. That is equal to List = @("Custom List");

Do not specify this setting if you have configured Connection!

RetryOnVersionConflict = $false;

Force workflow script to run again in case of "version conflict" (parallel item modifications in SharePoint).

Default: $false

UserProfileCacheLifetime = 60;

With Get-KFUserInfo a workflow script can query the SharePoint user profile store.

To reduce the calls in case of querying the same account during the workflow run the requested profiles are cached.

Default: global configuration. There: 60 seconds.

spUser = ""; and spPwd = '';

The following two parameters can be used to specify credentials for the workflow for SharePoint access.

If not specified the executing user will be used to access SharePoint.

This user need to have permissions on all object the workflow need to access, e.g. workflow list, items, data list, config list, ...

However it is possible to store credentials in a protected fashion using the parameter --setusername on kenaflow.exe. This will write the encrypted credentials to these two parameters. - Encryption of credentials uses the kenaflow encryption passphrase configured in global configuration. - If encrypted the setting contains a Base64 encoded string that starts with unicode character 0xFFFF. This means that the plain spUser and spPassword are not allowed to start this character!

spoAppId = ""; and spoAppSecret = '';

Only if platform is 'spo' = SharePoint Online

Here you can specify "app credentials" to access SharePoint online.

Please read article App ID & App Secret.

You can store encrypted credentials here with program switch --appid on kenaflow.exe. - If encrypted the setting contains a Base64 encoded string that starts with unicode character 0xFFFF. This means that the plain spUser and spPassword are not allowed to start this character!

AlternateWebUrls = @();

A list of alternate URLS, e.g. if a web application has Alternate Access Mappings.

Remove Events could be received with such an alternate URL.

Do not specify this setting if you have configured Connection!

ConfigList = "WFconfig";

Defines the name of the workflow config list.

DataList = "WFData";

Defines the name of the workflow sata list

HistoryList = "WFHistory";

Defines the name of the workflow history list

ErrorList = "WFErrors";

Defines the name of the workflow error list

PreQueryProcessing = "preQueryProcessing.ps1";

If specified this script is executed before querying.

Default: no pre-query script.

Please read Workflow Scripts.

RER = $false;

Specified whether the workflow offers "Remote Event" endpoints.

A list workflow can receive SharePoint Remote Events, Custom Data Remote Events and Link Remote Events.

Please read Remote Event.

REREvents = @();

List of strings that contain the subscribed remote events

Valid strings:

  • ITEMADDED
  • ITEMUPDATED

Default: Both.

RERHandlerName = "kenaflow_wf1";

Optional. Used as prefix for the name of the SharePoint Remote Event Receiver.

The default name is configured in the global configuration. It is "kenaFlow".

MaximumRerLifetime = 120;

Specifies how long a Remote Event is valid before it is skipped forever (if not processed).

Default: configuration in global config. There is default: 120s.

PostponeFailedRer = 5;

Specifies how long a a remote event is postponed in case of errors during processing.

Default: configuration in global config. There is default: 5s.

LastModifiedBasedOnLastRun = true;

If $true :

  • the timestamp LastRun of the workflow will be used to identify "last modified" items
  • the queried items for processing are sorted by ID.

If $false :

  • a time stamp file is written after processing all items or
  • a time stamp file is written if the workflows is timed out and forced to stop and
  • the queried items for processing are sorted by their "Modified" timestamp.

ItemBatchCount = -1;

Count of list items queried from SharePoint at one request.

Default: -1

-1 = use default from global configuration. Default: 1000.

ItemReCheckTime = -1;

Amount of time before each item is checked to be processed.

Default: -1

  • -1 = use default from global configuration. Default: 60 seconds;
  • 0 = check immediately

Background: If you query 1000 items from SharePoint to be processed by your workflow it could take minutes until item #200 is processed. Maybe the item does not need processing at this point in time because e.g. it was changed since them and would not match the query if it would be requested now. - Thats what kenaflow does. It "re-checks" all follwoing items to be "in query" right before executing them.

IgnoreFoldersInQuery = $false;

Handle lists and libraries "flat" by ignoring folders.

Default: $false.

Query="...";

This uses by default the kenaflow query language: Queries.

However if the query string starts with "<" it will be treated as CAML.

ItemChangeHashFields = <value>;

If you only want to process item with changes in certain item fields (columns) you can specify the list of names here.

If you want only process items with changes in any field you can set this simply to $true.

Example:

ItemChangeHashFields = @("Title");

DumpRerEventDataToLog = $false;

When remote events are processes this can be used to force kenaflow to write the remove event data to the log.

Because is could write critical data to log this is disabled by default.

Its mainly there for development.

Permission Sets Settings

PermissionSetCreate="";, PermissionSetRead="";, PermissionSetUpdate="";, PermissionSetDelete="";, PermissionSetManage=""; and PermissionSetApprove=""; can be used in _wfconfig.ps1 to configure the names of kenaflow created permission sets for the kenaflow specific SharePoint permission cmdlets:

Please read article Permissions for details.

Discussion