Templates

kenaflow offers two methods for template processing.

The first one uses Invoke-KFTemplate to process strings with placeholders.

The second one uses Invoke-KFFileTemplate to process Microsoft Word and/or Microsoft PowerPoint files with placeholders.

String Processing (Invoke-KFTemplate)

We have implemented a template engine in kenaflow that runs easily through strings and replaces placeholders with concrete values.

This can be used, for example, to send e-mails or to create PDF files.

Example:

Invoke-KFTemplate "{{Modified|yyyy-MM-dd}}"

A string can use the following placeholders:

{{<listitem-field-name>}}

[[<config-key>]]

((<local-config-key>))

<< PowerShell >>

Some placeholders (except PowerShell placeholders) may have a formatting "hint" after the given key, such as {{DateColumn|yyyy-MM-dd}}.

Allowed characters after the pipe are |:

a b c d e f g h i j k l m n o p q r s t u v wq x y z A B C D E F G H I J
K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 : , . - /
*<Space>*

For SharePoint user columns, you can specify |id after the name of the field so that the user's ID is used instead of the display name. E.g. {{Author|id}}. In case of multi-value user fields the items are separated by , .

For SharePoint lookup columns, you can specify |id after the name of the field so that the item ID of the lookup field instead of the lookup value . E.g. {{SomeLookupColumn|id}}. In case of multi-value lookup fields the items are separated by , .

For SharePoint taxonomy columns, you can specify |id after the name of the field so that the item ID of the taxonomy field instead of the taxonomy value . E.g. {{SomeTaxonomyColumn|id}}. In case of multi-value taxonomy fields the items are separated by , .

For SharePoint choice cloumns with multiple values the items are separated by , .

For date fields, the date format can be specified after the pipe character |. E.g. {{Created|yyyy-MM-dd}}

For bool fields ("Yes/No fields") you can specify string values for "yes" and "no", e.g. {{YesNoColumn|Why not!|No way!}}

Here you will find a list of the possible format types: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings

To use "{{", "}}", "[[", "}}", "((" and "))" as text you need to escape them with "" (backslash character) befor each brace character.

The PowerShell placeholders << PowerShell >> are disabled by default in the global configuration (setting allowPowerShellPlaceholders). If it is set to False there the workflow cannot overwrite it. But if it set to true it is possible to enable it for a certain workflow using setting AllowPowerShellPlaceholders in the _wfconfig.ps1. Default is $false. It is not inherited from the global configuration!

To specify "<<" or ">>" inside the PowerShell placeholder you need to escape them: "\>\>" and "\<\<". The workflow developer is responsible that the PowerShell content - that is executed as normal PowerShell - does not do any harm to the machine. It's not possible for kenaflow to check the "sense" of the PowerShell code. The PowerShell need to return a stringify-able value.

You have to escape any ">" or "<" character inside the PowerShell placeholder with "\>" and "\<".

The parameter -LocalConfig of the cmdlet can be used to apply local configuration values to be replaced with placeholders like ((LocalValue1)). With -LocalConfig you can pass in a PowerShell HashTable object like this:

$LocalConfig = @{ LocalValue1 = "Hello kenaflow" }
Invoke-KFTemplate "((LocalValue1))" -LocalConfig $LocalConfig

If Invoke-KFTemplate is used in a workflow of the following type the list item placeholders are not available because there is no default item context:

  • Email Workflow
  • SharePoint Site Workflow
  • PowerShell Workflow ... but you can specify the parameter -Item to pass in a SharePoint list item, e.g. if you gathered one using PowerShell. This will work in SharePoint connected workflows, like an email workflow with SharePoint connection or a site workflow. If you use pure PowerShell ablilities to connect to SharePoint - e.g. in a PowerShell workflow - you can use Set-KFContext to set the SharePoint for kenaflow.

Here is an example for a Site workflow script (snippet) where a list item is loaded manually and passed to Invoke-KFTemplate

$item = Get-PnPListItem -List "Some List" -Id 1
Invoke-KFTemplate -item $item -template "{{Author}}"

See the Invoke-KFTemplate cmdlet section for more information: Invoke-KFTemplate

Special Values in the Config List Object

The workflow config list list was already described. Its values are available with placeholders of the style ((xxx)).

There are so special values, that are set by kenflow:

  • KFInVersionConflict : Sometimes "version conflicts" occur during workflow execution if an SharePoint item was changed while the workflow is running. Normally this is related to a user action in SharePoint. In this case the "Version Conflict" handler executes the current workflow script again.
  • KFLastItemModifiedFlag : After processing a SharePoint list item the workflow engine restores the last editor and the last modified timestamp. But the item actually was modified by the workflow. That this happend is saved in the kenaflow Field.
  • KFLastExecutionType : The reason of the last workflow made change of the item, taken from the kenaflow field
    • normal : a "normal" time-based workflow run changed the item
    • remote event : a "SharePoint Remote Event" exection changed the item
    • link event : a "Link Remote Event" execution changed the item
    • trigger event : a "Trigger Event" execution changed the item
  • LastEditor : In case of a SharePoint list or statemachine workflow: The user field value of "Editor" at the start of the item processing.
  • LastModified : In case of a SharePoint list or statemachine workflow: The date field value of "Modified" at the start of the item processing.
  • KFLastRun : (Server local) DateTime of the last workflow run as SharePoint compatible ISO-String
  • KFCurrentStart : (Server local) DateTime of the current workflow start as SharePoint compatible ISO-String
  • KFLastRunDT : (Server local) DateTime of the last workflow run (as DateTime)
  • KFCurrentStartDT : (Server local) DateTime of the current workflow start (as DateTime)
  • KFLastRunUtc : UTC DateTime of the last workflow run as SharePoint compatible ISO-String
  • KFCurrentStartUtc : UTC DateTime of the current workflow start as SharePoint compatible ISO-String
  • KFLastRunUtcDT : UTC DateTime of the last workflow run (as DateTime)
  • KFCurrentStartUtcDT : UTC DateTime of the current workflow start (as DateTime)

Word / PowerPoint Processing

kenaflow is able to replace placeholders in Word files (.docx) and PowerPoint files (.pptx). The result is a again a Word file or PowerPoint file.

Processing Microsoft Office files is not easy. But we managed to replace tokens in almost all file parts, such as headers, footers, tables, ... If something is missing please contact us at support kenaro.com.

The placeholders work the same as for Invoke-KFTemplate (section above), but they need an additional placeholder marker right and left around the kenaflow token. The additional marker characters can be configured in the global configuration, section "cmdletConfic". The default markers are %{ (left) and }% (right.

Example: %{{{Title}}}% : the field name surrounded with curly braces will insert / replace with the SharePoint list items Title field value - in case you have a SharePoint Site or List workflow or you specified a list item using parameter -Item.

You can also use config values from the kenaflow Config List using placeholders like %{[[ConfigValue]]}% with square braces.

Or you can specify a PowerShell HashTable object like @{SomeValue = 1; Date = [DateTime]::Now.ToString("yyyy-MM-ss")} with paramter -LocalConfig. Than you use round braces to surrond the config value: %{((SomeValue))}%.

You can load the Word or PowerPoint template file from:

  • a SharePoint location (if the workflow is SharePoint-connected)
  • a System.Byte array (.NET)
  • a System.IO.Stream (.NET)
  • a file path (relative to the workflow folder or absolute) ((The kenaflow service account need to have read permissions on the file.))

The produces file can be retrieved from the cmdlet as:

  • a local stored file (The kenaflow service account need to have write permissions on the file.)
  • a SharePoint location (if the workflow is SharePoint-connected)
  • a System.Byte array (.NET)
  • a System.IO.Stream (.NET)

Here are two nerdy examples for template processing.

Workflow script:

param($wf, $web, $item, $config, $eventData)

if($wf-eq$null){import-module "C:\Program Files\kenaflow\kenaflow.runtime.dll";Invoke-Kenaflow;exit}

$localConfig = @{ kenaflow = "Workflow Engine" }

$s = $null
try {
    Invoke-KFFileTemplate -TemplateUrl "/sites/kenaflow/shared documents/ppt-template.pptx" `
        -TemplateType PowerPoint -ToFile "$(split-path $MyInvocation.MyCommand.Path)\test.pptx" `
        -LocalConfig $localConfig
    Invoke-KFFileTemplate -TemplateUrl "/sites/kenaflow/shared documents/doc-template.docx" `
        -TemplateType Word -ToFile "$(split-path $MyInvocation.MyCommand.Path)\test.docx" `
        -LocalConfig $localConfig
} catch {
    Write-KFLog $_.Exception.Message
}

The result files are saved to the workflow folder.

This is a screenshot of the template library:

template library

This is a screenshot of the SharePoint list to be processed:

sharepoint list

This is the Word template with processing result:

word example

This is the PowerPoint template with processing result:

powerpoint example

Discussion