Section "RER"

kenaflow can receive "remote event" sent by SharePoint or other messages send by third party applications by using an web API.

To enable this feature you need to configure this section.

When changing the Remote Event handler settings in the you maybe need to run kenaflow.exe --updatenetsecurity to grant access to the new URL.

rerRunnerSP2013

    <entry key="rerRunnerSP2013" type="System.Int32" default="1"></entry>

Here you can specify how many processes are used to process SharePoint 2013 related remote events. We call this "runner process". If you have SharePoint 2013 workflows that are configured to receive events you need to set this setting at least to "1".

In DEVELOPER edition and FREE edition you cannot configure this setting. You will have always "1" runner process.

useInstanceIdForSeparation

<entry key="useInstanceIdForSeparation" type="System.Boolean" default="true"></entry>

If set to true the instance ID of kenaflow is used in the RER endpoint url.

E.g. https://kenaflow.machine.local/21af8498-38f2-4567-a79e-721c75d68be7/rer/check

( rer/check is already handled by this kenaflow instance. )

This can be used to run multiple kenaflow instances on one server.

useAliasForSeparation

<entry key="useAliasForSeparation" type="System.Boolean" default="False"></entry>

If set to true kenaflow will use an alias for instance separation - in parallel or instead of useInstanceIdForSeparation.

rerAlias

<entry key="rerAlias" type="System.String" default="kenaflow"></entry>

This must be set if useAliasForSeparation is set to true.

This alias will be used in the kenaflow remote event endpoint URL.

E.g. <entry key="rerAlias" type="System.String" default="kenaflow">kenaflowProd</entry>

In combination with other settings - e.g. rerHost - this will enable this url: https://kenaflow.machine.local/kenaflowProd/rer/check.

rerRunnerSP2016

    <entry key="rerRunnerSP2016" type="System.Int32" default="1"></entry>

Here you can specify how many processes are used to process SharePoint 2016 related remote events. We call this "runner process". If you have SharePoint 2016 workflows that are configured to receive events you need to set this setting at least to "1".

In DEVELOPER edition and FREE edition you cannot configure this setting. You will have always "1" runner process.

rerRunnerSP2019

    <entry key="rerRunnerSP2019" type="System.Int32" default="1"></entry>

Here you can specify how many processes are used to process SharePoint 2019 related remote events. We call this "runner process". If you have SharePoint 2019 workflows that are configured to receive events you need to set this setting at least to "1".

In DEVELOPER edition and FREE edition you cannot configure this setting. You will have always "1" runner process.

rerRunnerSPO

    <entry key="rerRunnerSPO" type="System.Int32" default="1"></entry>

Here you can specify how many processes are used to process SharePoint Online related remote events. We call this "runner process". If you have SharePoint Online workflows that are configured to receive events you need to set this setting at least to "1".

In DEVELOPER edition and FREE edition you cannot configure this setting. You will have always "1" runner process.

rerRunnerSPON

<entry key="rerRunnerSPON" type="System.Int32" default="1"></entry>

This enables the Remove Event runner for SharePoint Online using the new PNP library.

rerRunnerPOSH

    <entry key="rerRunnerPOSH" type="System.Int32" default="1"></entry>

Here you can specify how many processes are used to trigger PowerShell based workflows that are not related to SharePoint. We call this "runner process". If you have "pure" PowerShell workflows that are configured to receive data you need to set this setting at least to "1".

In DEVELOPER edition and FREE edition you cannot configure this setting. You will have always "1" runner process.

RemoteEventHandlerName

    <entry key="RemoteEventHandlerName" type="System.String" default="kenaflow"></entry>

When a kenflow workflow is configured to receive events from SharePoint the URL of kenaflow is registered in SharePoint as "Remote Event Receiver". This registration requires a name. The name is build from this setting used as prefix and additionally the workflow ID to be unique.

rerQueueDir

    <entry key="rerQueueDir" type="System.String" default=".\queue"></entry>

Received events and data are stored in (encrypted) files on this before processing them using the "runner" processes of kenaflow.

Here you specify the location where the events are stored. You can specify a path relative to the ProgramDataFolder (default is .\queue) or a custom absolute path. kenaflow (its service account) need to have write permission at the configured location.

rerPermQueueDir

<entry key="rerPermQueueDir" type="System.String" default=".\permqueue"></entry>

In case of permanent running workflows you can store their incoming remote events in memory or on disk. In the case of writing them to disk the messages are stored in the directory configured in global setting rerPermQueueDir.

rerResponseQueueDir

<entry key="rerResponseQueueDir" type="System.String" default=".\responsequeue"></entry>

Remote events can send data back to the caller. The response is send by a specialized kenaflow process (kenaflow.exe --rer). The response is saved a data file from the workflow executing process in the director rerResponseQueueDir.

keepProcessedEventsDir

<entry key="keepProcessedEventsDir" type="System.String" comment="Leave empty to remove processed events"></entry>

For debug purpose the processed remove events can be stored in a separate folder. This you can specify here.

If empty (default) the processed remote events are deleted.

rerHost

    <entry key="rerHost" type="System.String" comment="dns of kenaflow" default="+"></entry>

This setting is used for "Remote Event Receiver" URLs registered with workflows, e.g. SharePoint workflows that can be triggered by SharePoint.

You will need this setting to trigger workflows with custom data or unstructured data using the kenaflow web API.

Specify the FQDN or hostname of the kenaflow machine.

Use + for IP address based remote event receivers.

rerHostIp

    <entry key="rerHostIp" type="System.String" comment="ip of the server used for remote events. Only required if 'rerHost' is '+'"></entry>

IP of the server to be used for remote events.

For generating an HTTP endpoint a host name (rerHost) or an IP (rerHostIp) is required.

This setting is only required if 'rerHost' is '+'.

rerHostUsesSSL

    <entry key="rerHostUsesSSL" type="System.Boolean" default="false"></entry>

kenaflow can receive data from SharePoint or by using the kenaflow web API using SSL. If you want to use SSL you must set this setting to true. You need to specify an SSL certificate using program switch --confighttp.

rerWarnAndRedirectHTTP

<entry key="rerWarnAndRedirectHTTP" type="System.Int32" default="-1" comment="Used only when rerHostUsesSSL is true... Writes a warning to the log and redirects the request with 302 to the SSL address."></entry>

By default remote event endpoint URLS always use SSL. You can specify a HTTP port (without SSL) here. In this case the HTTP endpoint will answer with a "Permanent Redirect" (302) HTTP response and the correct HTTPS (SSL) remove event endpoint URL.

There is only the "redirect answer". No event data is processed!

rerPort

    <entry key="rerPort" type="System.Int32" default="80"></entry>

kenaflow can receive data from SharePoint or by using the kenaflow web API using SSL. Here you specify the HTTP port. If you want to use SSL you need to specify the appropriate port (normally 443) yourself!

excludeCurrentUser

    <entry key="excludeCurrentUser" type="System.Boolean" default="true" comment="Remote events related to the current user will be excluded to prevent event floods."></entry>

As part of its normal function kenaflow changes SharePoint list items. If remote events are registered with a kenaflow workflow every change in a SharePoint list are send as remote events to kenaflow. Without this setting you would produce an endless loop: "User change in SharePoint" => trigger workflow by SharePoint remote event => kenaflow workflow changes the list item during processing => the change triggers the workflow by SharePoint remote event => kenaflow workflow changes the list item during processing the change triggers the workflow by SharePoint remote event => ... and so on ...

SharePoint stores the data-changing user in the remote event.

kenaflow reads this information and ignores remote events coming from the current user that runs kenaflow. This is the service account of kenaflow.

You should not change this setting.

excludeUsers

    <entry key="excludeUsers" type="System.String" default="|app@sharepoint" comment="exclude additional users. separate them by using ';'. all parts (separated by ;) will be treated as regular expressions!"></entry>

Please read the description of setting excludeCurrentUser first.

Here you configure patterns for users that also should be ignored additionally to the "current user" (kenaflow service account).

First: you can specify multiple patterns by using ";" as separator.

Event triggering users are compared to each pattern configured here: If the event triggering user END WITH one of this patterns the event is ignored!

Default: "|app@sharepoint" => This is used to ignore ALL events triggered by "app credentials".

rerCheckDuringWorkflowExec

    <entry key="rerCheckDuringWorkflowExec" type="System.Boolean" default="true"></entry>

kenaflow workflows are able to receive remote events from SharePoint. This requires a registration of the kenaflow workflow on each SharePoint list that is connected to a kenaflow workflow.

This registration can be forced using program switch --registerrer.

For removing the registration of a certain workflow you can use --unregisterrer.

if this setting is set to true (this is the default) on each workflow run the RER registration is checked. The registration on SharePoint added if missing and removed if present but not configured for the workflow. So you do not need to use --registerrer or --unregisterrer (when you want to disable remote events).

postponeEventOnScriptError

    <entry key="postponeEventOnScriptError" type="System.Int32" default="30" comment="In Seconds"></entry>

In case of errors during processing an remote event this event will be postponed for the amout of seconds specified here.

eventMaxAge

<entry key="eventMaxAge" type="System.Int32" default="120" comment="In Seconds"></entry>

You can specify here how old stored remote events can be before they are removed from the queue.

This is important if the processing of a remote event fails. It is then placed back in the queue until the eventMagAge is reached.

encryptRemoteEvents

    <entry key="encryptRemoteEvents" type="System.Boolean" default="true"></entry>

Remote events received from SharePoint or third party systems using the kenaflow web API are queued on disk. Here you specify whether kenaflow should or should not encrypt the queue files.

Default: true = encrypt

sslCertThumbprint

    <entry key="sslCertThumbprint" type="System.String" default=""></entry>

Using command line switch --confighttp you can register an SSL certificate for remote event endpoints (Remote Event).

If you register an SSL certificate it's thumbprint is written to this setting.

Please use command line switch --securing to grant access for users to the certificate.

rerReponseCheckEnabled

    <entry key="rerReponseCheckEnabled" type="System.Boolean" default="true"></entry>

The main mode of kenaflow (--run) by default triggers the RER endpoints of kenaflow to check their availability. If the remote event receiver process (kenaflow.exe --rer) does not serve the endpoint it gets restarted.

This setting can be used to disable this check mechanism.

The following settings can be used to fine tune the RER checker (if enabled).

rerReponseCheckInterval

    <entry key="rerReponseCheckInterval" type="System.Int32" comment="in milliseconds" default="5000"></entry>

This sets the check interval.

rerReponseCheckTimeout

    <entry key="rerReponseCheckTimeout" type="System.Int32" comment="in milliseconds" default="5000"></entry>

This sets the timeout for HTTP endpoint check.

rerReponseCheckFailCount

    <entry key="rerReponseCheckFailCount" type="System.Int32" default="5"></entry>

After this amount of failed checks the RER process gets terminated and restarted.

rerReponseCheckEnabledSPRER

    <entry key="rerReponseCheckEnabledSPRER" type="System.Boolean" default="true"></entry>

This enables or disables the SharePoint remote event receiver endpoint checker.

    <entry key="rerReponseCheckEnabledLINK" type="System.Boolean" default="true"></entry>

This enables or disables the link remote event receiver endpoint checker.

rerReponseCheckEnabledCDA

    <entry key="rerReponseCheckEnabledCDA" type="System.Boolean" default="true"></entry>

This enables or disables the custom data remote event receiver endpoint checker.

rerReponseCheckEnabledUDA

    <entry key="rerReponseCheckEnabledUDA" type="System.Boolean" default="true"></entry>

This enables or disables the unstructured data remote event receiver endpoint checker.

enableWfRerListenerForSP

<entry key="enableWfRerListenerForSP" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for "SharePoint" remote events.

enableWfRerHostListenerForLinkAnswers

<entry key="enableWfRerHostListenerForLinkAnswers" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for "Link" remote events.

enableWfRerHostListenerForLinkAnswersAuth

<entry key="enableWfRerHostListenerForLinkAnswersAuth" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for NTLM authenticated "Link" remote events.

enableWfRerHostListenerCustomData

<entry key="enableWfRerHostListenerCustomData" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for anonymous "Custom Data" remote events.

enableWfRerHostListenerCustomDataAuth

<entry key="enableWfRerHostListenerCustomDataAuth" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for NTML authenticated "Custom Data" remote events.

enableWfRerHostListenerCustomDataBasic

<entry key="enableWfRerHostListenerCustomDataBasic" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for basic authenticated "Custom Data" remote events.

enableWfRerHostListenerUnstructuredData

<entry key="enableWfRerHostListenerUnstructuredData" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for anonymous "Unstructured Data" remote events.

enableWfRerHostListenerUnstructuredDataAuth

<entry key="enableWfRerHostListenerUnstructuredDataAuth" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for NTLM authenticated "Unstructured Data" remote events.

enableWfRerHostListenerUnstructuredDataBasic

<entry key="enableWfRerHostListenerUnstructuredDataBasic" type="System.Boolean" default="true"></entry>

Enables or disables the remote event listener for basic authenticated "Unstructured Data" remote events.

Full Section Default

<section name="rer">
  <entry key="useInstanceIdForSeparation" type="System.Boolean" default="true"></entry>
  <entry key="useAliasForSeparation" type="System.Boolean" default="False"></entry>
  <entry key="rerAlias" type="System.String" default="kenaflow"></entry>
  <entry key="rerRunnerSP2013" type="System.Int32" default="1"></entry>
  <entry key="rerRunnerSP2016" type="System.Int32" default="1"></entry>
  <entry key="rerRunnerSP2019" type="System.Int32" default="1"></entry>
  <entry key="rerRunnerSPO" type="System.Int32" default="1"></entry>
  <entry key="rerRunnerSPON" type="System.Int32" default="1"></entry>
  <entry key="rerRunnerPOSH" type="System.Int32" default="1"></entry>
  <entry key="RemoteEventHandlerName" type="System.String" default="kenaflow"></entry>
  <entry key="rerQueueDir" type="System.String" default=".\queue"></entry>
  <entry key="rerPermQueueDir" type="System.String" default=".\permqueue"></entry>
  <entry key="rerResponseQueueDir" type="System.String" default=".\responsequeue"></entry>
  <entry key="keepProcessedEventsDir" type="System.String" comment="Leave empty to remove processed events"></entry>
  <entry key="rerHost" type="System.String" comment="dns of kenaflow" default="+"></entry>
  <entry key="rerHostIp" type="System.String" comment="ip of the server used for remote events. Only used if 'rerHost' is '+'"></entry>
  <entry key="rerHostUsesSSL" type="System.Boolean" default="false"></entry>
  <entry key="rerWarnAndRedirectHTTP" type="System.Int32" default="-1" comment="Used only when rerHostUsesSSL is true... Writes a warning to the log and redirects the request with 302 to the SSL address."></entry>
  <entry key="rerPort" type="System.Int32" comment="default (if -1 or empty) is 80 or 443 based on 'rerHostUseSSL'" default="-1"></entry>
  <entry key="excludeCurrentUser" type="System.Boolean" default="true" comment="Remote events related to the current user will be excluded to prevent event floods."></entry>
  <entry key="excludeUsers" type="System.String" default="|app@sharepoint" comment="exclude additional users. separate them by using ';'. all parts (separated by ;) will be treated as regular expressions!"></entry>
  <entry key="rerCheckDuringWorkflowExec" type="System.Boolean" default="true"></entry>
  <entry key="postponeEventOnScriptError" type="System.Int32" default="5" comment="In Seconds"></entry>
  <entry key="eventMaxAge" type="System.Int32" default="120" comment="In Seconds"></entry>
  <entry key="encryptRemoteEvents" type="System.Boolean" default="true"></entry>
  <entry key="sslCertThumbprint" type="System.String" default=""></entry>
  <entry key="rerReponseCheckEnabled" type="System.Boolean" default="true"></entry>
  <entry key="rerReponseCheckInterval" type="System.Int32" comment="in milliseconds" default="5000"></entry>
  <entry key="rerReponseCheckTimeout" type="System.Int32" comment="in milliseconds" default="5000"></entry>
  <entry key="rerReponseCheckFailCount" type="System.Int32" default="5"></entry>
  <entry key="rerReponseCheckEnabledSPRER" type="System.Boolean" default="true"></entry>
  <entry key="rerReponseCheckEnabledLINK" type="System.Boolean" default="true"></entry>
  <entry key="rerReponseCheckEnabledCDA" type="System.Boolean" default="true"></entry>
  <entry key="rerReponseCheckEnabledUDA" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerForLinkAnswers" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerForLinkAnswersAuth" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerCustomData" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerCustomDataAuth" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerCustomDataBasic" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerUnstructuredData" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerUnstructuredDataAuth" type="System.Boolean" default="true"></entry>
  <entry key="enableWfRerHostListenerUnstructuredDataBasic" type="System.Boolean" default="true"></entry>
</section>