Developing Workflows in VS: Part 3 - Five Steps for Developing Your Workflow

 

 

Okay, the moment you’ve all been waiting for: how do you write a custom SharePoint workflow?  In this section, we will break it down into five steps:

1)      Model your workflow in Visual Studio

2)      Create and bind your forms

3)      Code your workflow

4)      Deploy your workflow to the server

5)      Debug

(Note that these are only suggested steps; you can do this any way that fits best for you.)

Step 1: Model Your Workflow

The first step is to model your workflow using the Visual Studio Extensions for Windows Workflow Foundation designer, i.e. create a new workflow project, drag and drop activities into your workflow surface, and set the properties that you need.  Having a skeleton of your “flow” will help you see what needs to be done and where you will need to bind your form data in later steps.  Also, initializing the properties on your activities up front may save you some time having to switch back and forth between designer and code-behind file when you start writing your code.

FAQ: The workflow template can’t open in Visual Studio
When using the SharePoint workflow VS templates, you may encounter an error opening your .csproj.  This usually means that you do not have the Visual Studio Extensions for Windows Workflow Foundation installed.  Check to see if you have anything under the “Workflow” node before you worry about the “SharePoint” node.

SharePoint Activities

SharePoint comes with a set of activities.  Many of them wrap the service methods mentioned in the mechanics section above, or rather, they are the service APIs in activity form.  The method activities are blue, and the events handler activities are green.  The methods derive from the WF CallExternalMethod activity (see Item Activities sample in the ECM Starter Kit), and the functions you write for the Method Invoking property are executed right before the service method executes.  The handlers derive from the HandleExternalEvent activity, and the functions you write for the Invoked property are executed after the service handler executes and wakes up the workflow. 

Add an event handler activity whenever you want the workflow to commit the method actions or go to sleep, then wake up when an event fires. 

To create and bind variables to your activity properties, use the activity property dialog by clicking on the blue icon next to the property.  If instead of clicking on the blue button, you type in a value directly, for example, typing 1 for an int property, the property will be set to that constant value. (It’s less expensive for performance to do this if you know a value won’t change)

Pitfall: Using CreateTask or OnTaskChanged’s SPWorkflowTaskProperties objects as a real time representations of the SharePoint task item
When using CreateTask, the object that you bind to the TaskProperties property to set initial data for the task is only initial data; it’s not synchronized with the task, so it will not reflect any changes to the task, or vice versa.   The same concept applies to OnTaskChanged’s AfterProperties property.

The Importance of Correlation Tokens

A common mistake when initializing properties is not setting the correlation token correctly to map different activities to the same object.  If not done correctly, the workflow will not wake up or respond to events. 

Think of a correlation token as an identifier that WF uses to identify and respond to the corresponding objects in SharePoint.  For example, if you have in a sequence the activities CreateTask, OnTaskChanged (to wait for the user to edit his task), then CompleteTask, you want these three activities to map to the same task in SharePoint; you do this by specifying the same correlation token in all three. 

You will need a token for activities that relate to the workflow itself, a token for activities related to a particular task or item, and a token for each modification.  Here is a grouping of activities that need the same correlation token (each group should have its own token):

“Workflow” token: OnWorkflowActivated OnWorkflowItemChanged OhWorkflowItemDeleted SetState SendEmail UpdateAllTasks

Task token: CreateTask CreateTaskWithContentType UpdateTask DeleteTask CompleteTask RollbackTask OnTaskChanged OnTaskDeleted OnTaskCreated

Modification token: EnableWorkflowModification OnWorkflowModified

 

Missing from this table are the list item service APIs, which don’t have activities around them in the box.  But if you use wrapper activities for them (such as those included in the ECM Starter Kit item activities sample), you would treat them similarly to tasks: every related item activity should use the same correlation token.

Pitfall: Using the workflow token as the task token
Sometimes developers use the workflow token as their task token; now all tasks map to the same thing, right?  This isn’t quite correct. Make sure each group and object has its own token.  For example, don’t use the overall workflow token for your tasks.  Also, create a separate token for each distinct task.  Note: if you have a task in a sequence inside the replicator activity, changing the “Owner Activity Name” to the sequence will automatically create a new token for every instance of the sequence.

 

Next on Developing Workflows in VS: Design and Bind Your Forms