Preparing your Visual Studio 2008 Workflow Project

This is the 3rd part of our Beginners Guide to SharePoint 2007 Workflow Development.   You understand the workflow development scenario and how to create an InfoPath web-based form.  Now in this part of the series, we will be Preparing your Visual Studio 2008 Workflow Project for workflow development.  Although, Visual Studio 2008 is part of the workflow development series, Visual Studio 2005 can also be used to develop workflows.  If there is a request, I can update the series to include instructions for Visual Studio 2005.    

Workflow Series for Beginners

This series has 6 steps that will help you follow the workflow development process from start to finish.

1. Workflow Development Scenario
2. Create an InfoPath Web-Based Form
3. Preparing your Visual Studio 2008 Workflow Project
4. Creating Workflow approval tasks
5. Create and Integrate an InfoPath Web-Based workflow task forms
6. How to deploy a SharePoint workflow solution

 

Agenda for Preparing your Visual Studio 2008 Workflow Project

Here is the step-by-step process we plan on taking in this article:

1. Prerequisites for Workflow Development
2. Create Your Workflow Project
3. Workflow Correlation Tokens and How They Help
4. Setup Your onWorkflowActivated Task

Let's go ahead and start off with planning our workflow development with the right tools.

1. Prerequisites for Workflow Development

Visual Studio 2008 has become the new standard for workflow development.  It simplifies much of the tasks that developers found difficult.  Besides installing Visual Studio 2008, you will also need to download and install the following:

• SharePoint Server 2007 and Windows SharePoint Services 3.0 SDKs - The Windows SharePoint Services 3.0 software development kit (SDK) contains conceptual overviews, programming tasks, samples, and references to guide you in developing solutions based on Microsoft Windows SharePoint Services 3.0.
• Visual Studio Extensions for SharePoint 1.2 - this addin provides developers with support for building workflow-enabled applications using Windows Workflow Foundation. Compatible with the released versions of the 2007 Microsoft Office system, Microsoft Windows Vista, and the .NET Framework 3.0 Runtime Components

After installing the above, go ahead and install the latest Windows Updates.  Restart your server.  I recommend this, as it's always important to have your server updated and secure.  NOTE:  Service Pack 2 is soon to be released and would highly recommend (at the time of this writing) that you upgrade to the SharePoint 2007 December 2008 Cumulative updates. top

2. Create Your Workflow Project

Now we can finally begin creating our workflow.

1. Launch Visual Studio 2008
2. Select File -> New -> Project (Ctrl + Shift + N) NOTE: The New Project dialog box launches
3. Select Workflow under Project Types
4. Select SharePoint 2007 Sequential Workflow under Templates
5. Click Ok in the New Project dialog box
6. In the New Office SharePoint Workflow wizard, click Next NOTE:  Pay attention to where the project is being created (i.e. Location)
7. Click Next when you are requested to select the debugging lists  
8. In the next screen, click Next.

Your workflow skeleton has been created and before we get into the development, let's help you understand one key element of workflow development. top

3. Workflow Correlation Tokens and How They Help

Think of a correlation token as an identifier that Windows Workflow Foundation (WF) workflow runtime uses to identify and respond to the corresponding objects in SharePoint.   In WF, a workflow is one object and a task is one object.   For example, if you have in a sequence of activities in the following order:

1. CreateTask - creates a Windows SharePoint Services task for your workflow, with the task properties that you specify
2. OnTaskChanged - responds to the event Windows SharePoint Services raises when a task associated with the workflow is modified
3. CompleteTask - marks a Windows SharePoint Services task as completed

You want these three activities to be correlated and be able to reference the same task in each of these three (CreateTask, CompleteTask, and OnTaskChanged) activities, you would do this by specifying the same correlation token in all three activities.  What this correlation token helps with is allowing WF to communicate and manage the incoming and outgoing messages that is receives.  By associating a correlation token to each object, you allow WF to know exactly what object each messages relates to.  If you mistakenly associate each of these tasks to different correlation tokens, then WF will not know which task has been completed and which task has changed.   For a simple workflow such as ours, we need one correlation token for the workflow object and one correlation token for each of the task objects that we are creating.   Visual Studio 2008 makes the process of assigning correlation tokens easier.  If you would like to read more, check out Correlation Tokens in SharePoint 2007 Workflows.  I hope that answers any questions you might have had regarding correlation tokens, lets continue forward with configuring our onWorkflowActivated Task. top

4. Setup Your onWorkflowActivated Task

Every time a SharePoint workflow is initiated and/or activated, no surprise here, the onWorkflowActivated activity gets executed; responds to the ISharePointService.OnWorkflowActivated event.  MSDN defines the onWorkflowActivated class is defined as:

Responds to the event Windows SharePoint Services raises when a new workflow instance is initiated for an item

 NOTES:  The onWorkflowActivated activity must be the first activity and can not be placed in any other position in the workflow.   This activity initializes the correlation between the workflow id and the correlation token. Before we can actually add code to this function let's first define some variables.         private String employee = default(String);         private String manager = default(String);         private String historyOutcome = default(String);         private String historyMessage = default(String);         private String workflowName = "IT Request"; Now add helper functions to assist us in our workflow development.  One of the first functions that we will use is the CustomFieldValue method.  This function will assist us in retrieving any field value from the list that our InfoPath web based forms are being submitted to.         private string CustomFieldValue(string fieldName)         {             try             {                 object item = this.workflowProperties.Item[fieldName];                 string s = this.workflowProperties.Item.Fields[fieldName].GetFieldValueAsText(item);                 return s;             }             catch (Exception ex)             {                 return String.Empty;             }         } The CustomFieldValue function returns a string and can be placed above our onWorkflowActivated funtion.  I always like to add a helper function to store information in the workflow history event list, such as the one found in post titlted "How To Create a SharePoint Workflow History Event".         public void CreateWorkflowHistoryEntry(SPWorkflowHistoryEventType HistoryEventType, string Outcome, string Description, string OtherData)         {             SPWorkflow.CreateHistoryEvent(workflowProperties.Web, workflowProperties.WorkflowId, (int)HistoryEventType, this.workflowProperties.OriginatorUser, new TimeSpan(1), Outcome, Description, OtherData);         }  The onWorkflowActivated function will look like this:         private void onWorkflowActivated(object sender, ExternalDataEventArgs e)         {             workflowId = workflowProperties.WorkflowId;             employee = CustomFieldValue("Employee"); // retrieve the employee who will be assigned the workflow tasks             manager = workflowProperties.Originator;  //  retreive workflow originator; which should be the manager of above employee            //  Store short description of what was accomplished in this function            historyMessage = string.Format("Workflow ({0}) has been initiated by {1} for {2}", workflowName, manager, employee);             historyOutcome = "Workflow Activated";             CreateWorkflowHistoryEntry(SPWorkflowHistoryEventType.WorkflowComment, historyOutcome, historyMessage, string.Empty);         } After the onWorkflowActivated, we should now have the following capabilities:

1. Ability to retreive workflow properties using the workflowId variable
2. Know who the workflow is assigned to
3. Know who assigned the workflow
4. Add a new entry to the workflow history list

In the rest of the series, we will focus on creating our workflow tasks as outlined in our workflow development scenario.  Look forward to more posts in this workflow series now that the base foundation is setup.    top

Additional Resources 

• MSDN Correlation Tokens in Workflows
• MSDN CreateTask 
• MSDN OnTaskChanged
• MSDN CompleteTask
• MSDN Creating Custom Workflow Activities for SharePoint Server 2007 Using Visual Studio 2008