State Machine Workflows

Example

In your company, you want to use kenaflow to implement a hiring workflow that coordinates the tasks to be performed before and after hiring an employee so that the employee can do his or her job. Order a notebook, reserve a workstation. Print business cards. Order an Office 365 account. Each of these tasks is a "state" in which the process is located. Each state is processed and confirmed by the responsible person. Then the next state is executed, i.e. the responsible person is informed.

Getting Started Knowledge

Workflows of this type are distinguished by the fact that the SharePoint list items are assigned to a state that is managed by the workflow and tells the workflow what state the SharePoint list item is in.

In the context of the state machine workflow actions are executed. If necessary, the state can be changed by external actions, so that the execution of the workflow is influenced.

A "State Machine" workflow is connected to exactly one SharePoint list.

The workflow state is stored as lookup column in the SharePoint list item. The workflow checks the state information and then decides which workflow state should be executed. This allows complex workflows to be constructed by giving the SharePoint list item from one workflow state to the next.

Each workflow state owns a workflow script. This contains the actions that belong to the state. The workflow script of a state can set the SharePoint list item to a different workflow state.

The workflow script belonging to the workflow state is stored as individual files in the workflow directory. The filenames start with S_ - and end with .ps1, because they are PowerShell scripts.

The workflow states that belong to a specific workflow, are defined in the workflow configuration file _wfconfig.ps1.

For each workflow state, it is possible to define which queries (see section Queries) must correspond to a list item in order to be processed by the workflow. It is also possible for each workflow state to process all items that are in this state. Or only execute the workflow script on items that are changed since the last runtime of the workflow state.

Any list item found by querying a workflow state is processed by the state workflow script.

State Machine workflows can have any number of workflow states.

Various objects are passed to the workflow (PowerShell) script:

• the workflow configuration
• the list of workflow states
• the current SharePoint Web
• the current list item
• a list of the workflow configuration data stored in SharePoint

Each state machine workflow can have a "pre-query" script executed by kenaflow before the list items are queried and the workflow scripts are executed.

Each List-workflow and Site-workflow consists of exactly one workflow state, which is executed each time the workflow is executed.

In the case of Site-workflows, the one workflow state is executed exactly once per workflow execution.

In the case of List-workflows, the workflow state is executed for each list item that is determined by the workflow query.

Background Knowledge

The "State Machine" workflow type has some special features since the workflow execution is distributed among several scripts.

The individual states of the workflow are executed one after the other. For this purpose, the list items to be processed are determined separately for each state.

There are 3 ways to query list items to be processed. For each workflow state this can be choosen individually.

• by "LASTMODIFIED" : queries all list items that were modified since the last workflow run
• by "QUERY" : using kenaflow specific Queries or using CAML
• by "ALL" : all list items are processed

The order of the state can be controlled via the workflow configuration.

If the "LASTMODIFIED" type is used for a state, list items are processed that have been changed since the last execution of this workflow state.

The order of workflow states can be set via _wfconfig.ps1. Each state has the optional field ExecutionOrder. If this is not filled, 0 is assumed. Except for the state with the state code (empty): for this ExecutionOrder = -1 is assumed so that this state is always executed first in the standard.

All states with the same ExecutionOrder are sorted by their state code.

Since each workflow can be limited in its runtime, it is possible that a workflow will be terminated before all states have been completed.

kenaflow remembers the last state performed and repeats the sorting of states so that the next time the last executed state is started.

The execution time for each workflow state can be limited.

• When the time is up, kenaflow remembers the last list item ID of the last processed item to continue with the next larger ID on the next run.
• It is also possible to instruct kenaflow to remember the modification time of the last item to start at this point in time at the next run.

After executing a state, kenaflow remembers the date and time of the last execution. This point in time is relevant for the determination of the list items to be processed according to the principle LASTMODIFIED.

Workflows that are terminated because the kenaflow application closed - for example, by restarting the computer,- will usually not save the last execution time. This is not possible because the operating system terminates the software. kenaflow tries to save the time. However, there is no guarantee.

LASTMODIFIED should generally be omitted as the query type for workflow states! Rather, smart queries should be developed for each state, based on list items properties to determine whether or not items need to be processed.

For each workflow state, you can specify how many list items should be retrieved per batch. This setting is either inherited from the workflow, if it exists or from the global configuration of kenaflow. By default, it is 1000. It is important to ensure that this value does not collide with SharePoint's "List View Threshold". This can lead to errors. The SharePoint standard "List View Threshold" is 5000.

Users and processes like workflows are constantly working in SharePoint. List items change.

kenaflow uses queries to determine the list items to be processed. If the query has taken place, it is not executed again until all determined elements have been processed. If the elements change in between, they will still be included in the query being processed.

With the "ItemReCheckTime" setting, you can set for each workflow state the point in time (in seconds from the start of the workflow state) at which each element is to be checked again to see whether processing is still necessary.

The setting is inherited from the workflow if it is missing or if it has a value of -1, if it exists there, or from the global configuration of kenaflow.

A value of 0 indicates that each list item will be checked without delay, whether it still needs to be processed.