MatchPoint – Self-Paced Training

Session 8 – Workflows
Theory

July 2013 | Colygon AG

Disclaimer
The complete content of this document is subject to the general terms and conditions of
Colygon as of October 2012. The client confirms to have received and agrees with the
general terms and conditions of Colygon. This document or parts of it are the property of
Colygon and must not be disclosed to third parties without written permission of Colygon.
Overview
The workflow kit allows you to implement item-based workflows very easily and with support for
powerful MatchPoint functionalities, like the configuration framework or the expression engine.

Let's get started with some information on the model of the workflow kit.

Model
The workflow kit is implemented as a state machine. This means an item that has a MatchPoint
workflow running has a known state at any time. The item is moved between these states using
transitions. A workflow is started using a trigger. When a state is entered, the defined entry actions are
executed. Likewise, when a transition is executed, the actions defined for that transition are executed.
You can combine workflow-states and -transitions freely, therefore you can implement complex
workflows with loops and repetitions using this model.

Implementation
The implementation of the workflow kit uses the following mechanisms:

• Workflows are always started on a specific item, this could be an SPListItem representing a
document for example. An important architectural limitation of the workflow kit is that you
cannot have multiple workflows running on the same item at the same time.

• A SharePoint list called “MatchPoint Workflow Instances” is created automatically on the root-
web of each site collection where a workflow is started. This list is hidden and used to store
the current workflow state of every workflow instance in the site collection. Therefore, a list
item will be created within this list for every workflow instance.

• A “Custom Action” is registered for the display-form toolbar. This allows MatchPoint to display
available operations for a list item to the end-user within the SharePoint ribbon. These
operations can either be triggers that will start a new workflow on the item or transitions that
will move items between workflow states. Additionally, depending on the user's permissions,
administrative operations like the workflow history will be displayed.

• A “Context Menu Provider” is registered. This functionality is part of the MatchPoint API we will
hear about in session 10. The workflow kit context menu provider will generate a context
menu for list items displayed within a MatchPoint Data Grid Web Part. Analogue to the custom
action above, available operations are displayed to the user in this context menu.

www.colygon.com Page 2 of 6
 • A MatchPoint “List Item Event Handler” is registered. This event handler is used to start a
workflow and to execute automatic transitions between workflow states. Since MatchPoint list
item event handlers are only available on SharePoint lists that have the tagging functionality
enabled, the Workflow Kit can be used only on tagging-enabled lists.

Please note that the first two mechanisms make use of standard SharePoint functionality. The second
two mechanisms use the MatchPoint API to implement and register the workflow-specific functionality.
Therefore, the workflow kit is also a good example for a custom solution that is based on the
MatchPoint API.

To enable MatchPoint Workflows on a SharePoint site collection, please make sure that the site
collection feature “MatchPoint Workflow Kit” is enabled.

Workflow Configuration
A MatchPoint workflow is defined within a single configuration file. This allows an easy configuration
and deployment of a workflow to your environment.

Within the configuration file, all States and Transitions, Actions and Triggers are specified. For
some Triggers and Transitions, you can specify user input forms to request information from the
executing user.

And you can specify a workflow tag: For every state of the workflow, a tag will automatically be created
and applied to workflow items. This functionality is similar to the workspace tag which we have used in
session 7.

Following configuration elements can be used:

Triggerss, Transitions, UserInputForms and Actions. They are defined in the following sub
sections.

Triggers
First, you can specify one or more trigger elements. Triggers are responsible for starting the workflow
and routing it to the initial state. You can define three kinds of triggers:

• A ContextMenuTrigger allows starting a workflow - either from the context menu of the item
with a MatchPoint Data Grid Web Part - or from the toolbar within the display form.
Note that this makes use of the custom action and the context menu provider registered by the
workflow kit. On the context menu trigger configuration element, you can specify a user input
form to request additional information from the executing user.

• An ItemAddingTrigger will start a workflow when a list item is added. This uses the
registered list item event hander, more specifically the "item added" event.

• An ItemUpdatingTrigger will start a workflow when a list item is updated. Again, the list item
event hander – this time, the "item updating" event" is responsible for this functionality.

For all triggers, you can specify conditions that will determine whether the trigger should be activated.
This can be the content type of the list item, an URL prefix or a MatchPoint tag. For the context menu
trigger, conditions are evaluated when the context menu is rendered. For the event-based triggers, the
condition is evaluated within the ListItemAdded or ListItemUpdating event.

www.colygon.com Page 3 of 6
Transitions
Workflow transitions are responsible for routing items between workflow states. There are two kinds of
transitions available:

A conditional transition is based on a MatchPoint expression. By using the WorkflowInstance and

the ListItem expression variables, you can use context-specific values, for instance based on user
input, to define a condition. If the expression evaluates to true, the transition is applied. You can
specify a transition to be evaluated either immediately or on the item update event.

The second kind of transition is a user transition. This transition is available from the item context
menu within a MatchPoint Data Grid Web Part or within the toolbar on the display form. Just like a
context menu trigger, a user transition can be configured with a user input form that allows requesting
information from the executing user.

User Input Forms

The configuration of a user input form is similar to the configuration of a Form Web Part or a
Workspace Editor Web Part. You can select from a number of field types to create an input form. Of
course, you can use the expression engine here for defining dynamic visibility conditions, field
validation or connections between different fields. Once the user has defined input values, you can
access these values from the WorkflowInstance expression variable.

Actions
As we have seen, you can use actions both on transitions and (as "entry" actions) on a workflow state.
You can configure a number of different actions. Most actions should be self-explanatory:

Action Type Description

CheckInFileAction Check-In SPListItem(s) by specifying an SPFile, an SPListItem, a
ListItemWrapper, an URL or a set of URLs.

CheckOutFileAction Check out SPListItem(s) by specifying an SPFile, an SPListItem,

an IlistItemWrapper, an URL or a set of URLs.

CopyFileAction Copy or move a file.

CreateListItemAction Create a new list item.

CreateTaskAction Create a new task item.

CreateWebAction Create a new web or site collection.

CreateWorkspaceAction Create a Workspace with a specified workspace template.

DeleteFileAction Delete a file.

DeleteItemAction Delete a list item.

EvaluateAction Evaluate an expression: The EvaluateAction allows access to the

MatchPoint expression engine. Again, you can use the context-
specific variables WorkflowInstance and ListItem in addition to the
standard MatchPoint variables. The result of your expression will be
stored as a workflow instance variable.

ForEachAction Iterate over a collection and execute an action for each of the
elements. You can use any of the other actions within a
ForEachAction.

www.colygon.com Page 4 of 6
 SetFieldAction Set a field value on the current workflow item.

ModifyItemAction Modify any currently existing list item.

ModifyUpdatableAction Modify an object that implements the IUpdatable interface.

ModifyWorkspaceAction Modify the properties of a specified workspace.

SendMailAction Send a mail to a group of users or users in a given role.

SetFieldAction Set the value of a field on the item on which the workflow is executed.

SetPermissionsAction Set permissions on the workflow item.

SetTagsAction Set tags on the workflow item.

SetVariableAction Set a workflow instance variable: The SetVariableAction can be

used to define a value that can be accessed from the
WorkflowInstance.Variables expression.

SwitchAction Use this action to call different actions depending on a certain

condition. Similar to an if-else action in C#. The switch-action contains
case-blocks which have an expression which serves as a condition.
Each case has several “sub” actions.

Custom Actions Custom actions can easily be implemented…

If you need to implement functionality that cannot be covered with these actions, you can either use a
custom expression variable and access it from the "EvaluateAction", or you can easily implement
custom actions that can be used directly within the workflow configuration. For more information
please refer to session 10 (“API and Custom Code”) of this course.

Expression Variables
Within the configuration file, you can use the MatchPoint expression engine in a number of
configuration parameters, for instance to specify permissions for a transition. Also, there are some
context-specific expression variables in addition to the standard MatchPoint expression variables:

 The Updatable expression variable can be used to access the item on which the workflow is
running.
 The WorkflowInstance expression variable provides access to the current workflow instance,
including the workflow configuration, the current state etc.
o Workflow (Definition/Configuration)
o WorkflowVersion
o CurrentState
o Variables (see below)
 Very important is the "Variables" property. It allows access to variables that are defined on the
workflow, for instance the values of a user input form.
o Usage: WorkflowInstance.Variables.<VariableName>

You can access both the Updatable and the WorkflowInstance expression variable in any
expression within the workflow configuration.

www.colygon.com Page 5 of 6
Hints
 A common mistake when working with the MatchPoint workflow kit is
forgetting to enable tags on SharePoint list on which the workflow is executed.

 When using a data grid with a TitleColumn which should show the workflow
context menus, ShowCustomContextMenu needs to be enabled.

Thank you for attending the MatchPoint Self-Paced Training.

Please feel free to send us your feedback, regarding questions,

experiences, comments, concerns or improvements.

You can contact us under following e-mail address: training@colygon.com

www.colygon.com Page 6 of 6