Here's a step-by-step approach to the basics for creating and deploying a Visual Studio 2010 project and workflow in SharePoint 2010.
The most recent versions of SharePoint -- Microsoft SharePoint 2010 and SharePoint Foundation 2010 -- are based on the workflow and concepts of the .NET Framework 3.5. In my previous article, "Workflows in SharePoint 2010," I provided an overview of these workflows.
Now, in this series of articles, I will provide a step-by-step approach to building workflows in SharePoint 2010, using Microsoft Visual Studio (VS) 2010, SharePoint Designer (SPD) 2010, and Visio 2010.
In this first article, I will cover the basics: creating a VS 2010 project and SharePoint 2010 workflow, deploying the workflow, and understanding some basic concepts. The code we will create in this article will be upgraded in future articles. (To download the beginning code and site template that we'll use in this article, click the hotlink at the beginning of the article.)
You'll also need a virtual machine (VM) for this tutorial. I use the free 2010 Information Worker Demonstration and Evaluation VM, which you can download from Microsoft; if you prefer, you can get an instance of the same VM running in the cloud from www.cloudshare.com.
The Scenario: Submitting an Expense Report
The workflow that we are going to create is an application that allows users to submit expense reports. As soon as an expense report is submitted, a workflow will be activated and will
- generate a globally unique identifier (GUID) for the expense report
- determine whether the report must be submitted for approval (for amounts less than $1,000, the expense report is automatically approved and the process is completed with a status of "autoapproved")
- find the user's manager
- create tasks for the manager to approve or reject the expense report
- update the expense report status to "approved," "rejected," or "autoapproved"
Before starting this tutorial, you need to create a site (based on the template that you can download from the hotlink at the beginning of this article) that has the following lists:
- Expense Reports, with columns such as those in Figure 1
- Managers, with columns such as those in Figure 2
Fill the Managers list with the accounts that Figure 3 shows (I've used accounts that Microsoft provides in its VM, but you can use your own accounts.) Make sure that the users in this list are at least contributors in the site (a setting that is not provided in the site template).
Creating the Workflow
Before creating the workflow, make sure that VS 2010 and SharePoint 2010 are running on the same computer. Start VS 2010 and create a new SharePoint 2010 project that is based on the Empty SharePoint Project template, as Figure 4 shows. Name the project Litware.ExpenseReport.
In the SharePoint Customization Wizard, when prompted to provide your web site URL for debugging, enter the URL and select the Deploy as a farm solution option, as Figure 5 shows. Workflows that are generated with VS cannot run in the sandbox.
Add a new SharePoint item, based on the Sequential Workflow template, to your project, as Figure 6 shows. Name the item ExpenseReportWorkflow.
Because workflows communicate with users by assigning tasks (I'll provide more details about this topic in another article), we usually need a task list (although it isn't mandatory). For this tutorial, the site template creates the task list. If you don't provide any task list, the SharePoint Customization Wizard generates an error message that begins "The SharePoint Site at xxxxx is missing a target, task, or history list..." (as Figure 7 shows). Don't worry too much about this for the moment, but keep it in mind.
In the next window, you need to specify whether you want your workflow to be associated with a SharePoint list item. If so, select the List Workflow option; if not, select the Site Workflow option, which is new in SharePoint 2010.
Because our expense report will be stored in the Expense Reports SharePoint list, select List Workflow, as Figure 8 shows. Click Next.
In the next window, select the list that you want your workflow to be associated with: in our case, Expense Reports, as Figure 9 shows. (Note that the Workflow History list is a hidden list that contains key information about each workflow event, including date, status, participant, and description. The wizard creates this list for you. By default, the workflow history is visible for only 60 days after a workflow completes or is cancelled. I'll provide more information about the Workflow Auto Cleanup job in a future article.)
The next window allows you to specify how you want the workflow to start.
When you associate a workflow to a list (which you can do manually, as I will illustrate later, or by using the SharePoint Customization Wizard), you can specify whether you want the workflow to start manually (i.e., the user will manually start the workflow) or automatically when a new list item is created or when an existing item is changed. (You can change these parameters later if you want.)
Let's keep the options that Figure 10 shows. Click Finish.
The workflow now shows up in the Workflow Designer, which Figure 11 shows. The first activity (or step) of a VS SharePoint workflow must be an onWorkflowActivated activity.
Open the Solution Explorer, which Figure 12 shows. You will see that a new SharePoint project item (of type Workflow) has been generated. The associated .NET code can be found in the ExpenseReportWorkflow.cs file, which is also a .NET class; we usually call this class a workflow template.
Building and Deploying
Go to the Build menu and select Deploy Solution. This generated code is called a workflow template; several instances of the same workflow template can be associated to the same list or to a different list in the site collection.
Go to your site, click the Expense Reports list, go to the list settings, and click the Workflow Settings button on the SharePoint Ribbon, as Figure 13 shows.
The Workflow Settings window appears. This window shows a list of available workflow templates. Our workflow template is available because it is encapsulated in a SharePoint feature with a scope of Site (a site collection); more about this later.
In this window, you can associate your workflow template with the current list.
We already have one association (performed by VS 2010), named Litware, as Figure 14 shows.ExpenseReports-ExpenseReportWorkflow, but you can create other workflow associations by clicking the Add a workflow hyperlink. (You can display the list of available workflow templates by clicking the drop-down arrow.)
Click the Litware.ExpenseReports-ExpenseReportWorkflow association link to view the workflow association settings, which Figure 15 shows. Note that the option is selected to start the workflow when a new item is created. Click OK.
Go to the Expense Report list and add a new item, as Figure 16 shows. Save this item. Because the workflow is configured to start when a new item is created, saving the item will cause a workflow instance to be created from our workflow template.
Indeed, if you go back to the list view, which Figure 17 shows, you will notice a new column that has the workflow association as a name. If you click the Completed hyperlink, you will visualize the workflow status, history, and tasks in the Workflow Information window, which Figure 18 shows.
Using Workflow Activities
A workflow is a set of steps; each step is an activity. Activities are .NET classes. We can reuse existing activities or create custom activities, as I will illustrate later.
The Workflow Foundation (WF) infrastructure is a set of assemblies that can be visualized in the References folder of our VS 2010 project (see Figure 19).
As part of the .NET Framework 3.5, WF provides several interesting activities that can be used in SharePoint. (Not all WF activities can be used in SharePoint, however.)
These activities are provided in the System.Workflow.Activities assembly, as Figure 19 shows. For more information about WF see the sidebar "For Workflow Foundation Aficionados."
The SharePoint team also provided more specific SharePoint activities, which you can find in the Microsoft.SharePoint.WorkflowActions assembly. This assembly can be found in the 14\ISAPI folder and is referenced by default in our VS 2010 project.
These activities can be dragged and dropped into the VS workflow design surface from the toolbox (select the SharePoint Workflow panel), which Figure 20 shows.
Just to make sure that our basic workflow can at least say "Hello World," we will drag and drop LogToHistoryListActivity to the workflow surface. Figure 21 shows the addition of an activity.
Now, in Workflow Designer, select logToHistoryActivity, go to its property page, and type "Hello World" in the HistoryOutcome property, as Figure 22 shows. Deploy the solution as you did previously (selecting Deploy Solution from the Build menu).
Go to the Expense Reports list. Select the expense report that you created earlier, and then click the Workflows button on the SharePoint Ribbon, as Figure 23 shows. The Start a New Workflow window, which Figure 24 shows, appears.
Click the Workflow button to start our workflow. Go to the workflow status, and you should see the Hello World message, as Figure 25 shows.
Workflows that are generated from VS 2010 are logically packaged as site collection features. If the feature is not activated, then the workflow template cannot be used.
Workflows that are generated by VS 2010 are compiled as .dll files that must be installed into the global assembly cache (GAC). Therefore, these kinds of workflows cannot run in the sandbox environment, even if we create custom sandbox activities (as I will illustrate in another article).
If you look at the elements.xml file that describes the workflow feature (Figure 26), you will find the <Workflow> element, which points to the workflow class Name, as well as the placeholder for the assembly name.
New in SharePoint 2010 is the <AssociationCategories> element, which can contain List (if the workflow must be associated with a SharePoint list), Site (if the workflow must be associated with a SharePoint site), or Content Type (if the workflow is associated with a content type, which is an excellent practice).
The <StatusPageUrl> element specifies the .aspx page that is used to display the workflow status. I usually keep the default _layouts/WrkStat.aspx, but you can replace it with a custom page if needed.
Wizard Setting Configuration
If you want to modify the settings that the VS 2010 SharePoint Configuration Wizard provides, then you can select the workflow SharePoint project item, display its property page (which Figure 27 shows), and change the settings. For instance, you can change the Task List, or you can cancel the automatic association of the workflow with the list (via the Auto Associate property).
If you try to modify the task list, a new SharePoint Customization Wizard window will appear, as Figure 28 shows.
Reviewing the Code
If you open the file ExpenseReportWorkflow.cs, you will see a class that is derived from SequentialWorkflowActivity (see Figure 29), which is the root class for Sequential workflows. (There are two kinds of workflows: Sequential and State Machine, which I will illustrate in another article.)
If you open the Designer code, you will see that each activity is a member of this class, which Figure 30 shows.
In the next article of this series, we will enhance this workflow.