Manual workflows are just that — manual. In other words, you didn't implement any of SharePoint's workflow features. Users are expected to manage the flow of information themselves. It may seem odd to start off a discussion about workflow features by suggesting that you don't use them — and it is. However, it may be a reality in your organization. Workflows are useful for generating highly repeatable processes. This may or may not be necessary for the business need that you're seeking to use workflow for. If the need for consistency doesn't have a strong business driver, it may make sense to use out-of-the-box features such as alerts to alert people that action needs to be taken, rather than creating a more formal workflow.

Obviously, the benefit to this solution is that there's no workflow development time. The downfall is that it doesn't provide much (if any) support for the process.

WSS 3.0 ships with one workflow (Three-State) and MOSS 2007 ships with several more. These workflows are what would be considered data-driven workflows. That is, the way that they work is fundamentally based upon the data that they are provided. In this case, the way that you set up the workflow when it is associated with the list (or document library) controls the people who are involved with the workflow — and, to some limited extent, how the workflow operates.

The opportunity here is to use these out-of-the-box workflows with your custom data (such as who will perform approvals) to solve your workflow needs. This is a great option if you want the power of a workflow, but aren't able to develop (or interested in developing) your own.

The benefit of this approach is that it doesn't require development of your own custom workflow. However, it is severely constrained by the fact that your flexibility is limited to the flexibility specifically designed in the out-of-box workflows that Microsoft shipped with the product. This is definitely the first option to pursue, if you can find a workflow that you can customize to your needs.

With a clear focus on being the information worker's way to customize SharePoint, SharePoint Designer (SPD) takes the best of customizing SharePoint with the FrontPage 2003 product, and rolls in new functionality around the creation of workflows and management of SharePoint in general. From a workflow perspective, SPD provides a simplified "rules-based" workflow editing tool, much like you'll find while working with Outlook rules for your mail. This simplified view makes it ideal for workflows that information workers are creating.

SPD-developed workflows are good solutions in many ways, because information workers can be trained on how to create their own workflows. These workflows generally can be done very quickly by IT professionals. As a result, they require the least amount of time to develop of any custom workflow solution option that SharePoint supports. However, this ease of use comes with two costs.

First, the workflows created with SPD don't have the same options that a complete custom workflow might have. Only workflow activities that are marked as safe for SPD use are available in this context. Though these limits may not be felt with simple workflows, any truly complex workflows that are designed to support a business process may find the restrictions to be limiting.

Second, SPD workflows cannot be reused from one list to another — or one site to another. The one way around this is to template the list on which the workflow is based. Lists created from that template will inherit the workflow. Although this is certainly a workable solution in some situations, the limit that the workflow can't be applied to an existing list may be too restrictive for your organizational needs.

When reading the earlier discussion about what a workflow is, you learned that workflows must be serializable and resumable. They must be able to start and stop, and start again, based on their need for new stimuli. Sometimes, however, workflows can be used when this is not the case. All of the responses from the workflow take place because of the initial start stimuli. Though this is a perfectly acceptable use of the WF that underpins SharePoint, these sorts of workflows are equally suited to be handled by event receivers.

Event receivers (which were present in WSS 2.0) have been radically improved for WSS 3.0. WSS 2.0 supported only asynchronous events — that is, events that occurred after the event had completed. It only supported those events for document libraries. WSS 3.0 supports both synchronous (occurring before the operation is complete) and the asynchronous events supported in WSS 2.0. Furthermore, these events are supported for every list — not just document libraries.

Event receivers are a good option for workflows that don't need to respond to multiple stimuli because there is less you need to know to write an event receiver than you need to know to effectively create custom workflows. Of course, event receivers aren't suitable for situations that require multiple interactions with a single item in the context of one larger workflow because they aren't workflows, but rather simple responses to events.

When the other options won't work and you're willing to make the investment to learn the WF infrastructure and how SharePoint interacts with that infrastructure, you're ready to create custom workflows with Visual Studio (VS) that you can deploy to SharePoint. The advantage of developing workflows with VS is that you have substantially fewer barriers preventing you from creating the precise workflow that the business needs. You have full access to every built-in workflow activity, as well as the ability to add code into the workflow as a separate activity, or to respond to events raised by the workflow activities. In addition, you can purchase third-party activities, or even write your own activities that plug directly into the VS design surface.

The negatives to developing custom workflows with VS are primarily that they are more complicated to get right and require more time to develop. However, the reward for the effort is a reusable workflow that can be attached to any list or library on any site where the workflow has been installed and activated. That means that an approval process that you design in the United States can be applied to your offices in the United Kingdom or wherever the workflow is needed. Custom workflows in VS are, in fact, the way that the out-of-the-box workflows were developed.

Because custom workflows (or, more precisely, custom workflow templates) developed in VS are so powerful, the rest of this chapter is dedicated to getting you what you need to know to develop custom workflows with VS.

Perhaps the most common way to use a workflow is to associate it to a list or library in SharePoint. In fact, all libraries in SharePoint are themselves lists. Thus, the most common way to use workflows in SharePoint is to associate the workflow with a list (even if that list happens to be a library). Workflows can also be associated with content types.

Back in SharePoint Portal Server 2001 (SPS 2001), you had the ability to define different types of documents that were stored in a document library. Each document type had its own fields — metadata about the document. WSS 2.0 and Microsoft Office SharePoint Portal Server 2003 (SPS 2003) removed this functionality from the product because of the effort to re-platform against SQL Server instead of the Web Storage System (essentially the Exchange data store). This brought a great deal of angst from customers as they tried to store different kinds of documents in their document libraries — each document type requiring a few different fields, some of which were required only for certain document types.

WSS 3.0 solves this need by reestablishing the idea that you can store different kinds of data in a list (and, therefore, a library). Each type of data is given a content type. The content type bundles the fields as well as the workflows to be associated with that kind of data. Multiple content types can be bound to a single list and, therefore, it's possible to have different rules for different types of data, both in terms of the fields that are included and the workflows the item goes through.

Content types are essential to understanding how SharePoint implements workflow because when SharePoint creates an item from a workflow, it does so via the content type. In particular, tasks created by SharePoint (whether through the CreateTask or CreateTaskwithContentType activities) are assigned a content type. This is used to control what fields are available and what fields are displayed to users when they display or edit the item.

The SharePoint Universal Logging Service (ULS) is a centralized spot where all of SharePoint's internal operations log their successes and failures. The log files are created on each member of the farm in their local C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12LOGS directory. Each individual log file is created with the format of SERVERNAME-DATE-TIME, where SERVERNAME is the name of the server the log file was created on and for which events were captured. DATE is the date the log file was created in the format of the four-digit year, the two-digit month, and the two-digit day. The final element is TIME in 24-hour format, with a two-digit hour, followed by the two-digit representation of the minutes past the hour.

Because workflows don't interact directly with the user and there is often not a place to surface exceptions to the user interface, you'll find a large number of helpful (and not so helpful) exceptions end up here for you to review. The question isn't whether you'll need to look at the ULS log files while developing a SharePoint workflow; it's a question of when you'll need to do it and how often.

These files are much like most other log files you've seen in your career — with one exception. The individual entries may be split across multiple lines. Longer messages, particularly those containing exception details, get split into multiple lines within the file after just shy of 1,000 characters.

There's actually a mechanism in SharePoint called a Feature. That is, you create features that are deployed as a Feature to SharePoint. Are you confused yet? The key to this concept is understanding that there's a specific thing in SharePoint called a Feature, and it's used to "light up" new functionality within a site, site collection, Web application, or SharePoint farm. Chapter 4 provides more information about Features.

As mentioned previously, every piece of information in SharePoint has a content type. The content type defines the fields that are associated with the content. It is possible, as is the case in lists, to add additional fields beyond the base content type. However, the best way to ensure that a field is present is to define a content type and activate it in the list you want your content in.

A content type can also inherit from other content types. For example, the default workflow task, which is used by default to create tasks from a workflow, derives from the standard task content type. In this example, I derive from the workflow content type for the content types.

The definition of content types consists of three basic pieces: field definitions, field references, and the Feature that you deploy them in. Let's start by defining two fields in XML. These will go into a file used in the Feature that I discuss later in this chapter.

<Field ID="{0116A5FF-6FB7-43e1-B3E3-30A58B40349C}"
     Name="GradingScore" Group="Grading" DisplayName="Score"
     Type="Number" Sealed="FALSE" ReadOnly="FALSE" Hidden="FALSE"
     DisplaceOnUpgrade="TRUE"/>
<Field ID="{81792580-6F97-4960-84C2-7A8A926D1DCE}"
     Name="GradingNotes" Group="Grading" DisplayName="Notes"
     Type="Text" Sealed="FALSE" ReadOnly="FALSE" Hidden="FALSE"
      DisplaceOnUpgrade="TRUE"/>

Let's walk through each of the attributes:

With the fields created, the next step is to create the content type and add references to the fields. To add the content types, you must know how to derive from an existing content type. There's a base content type hierarchy in MSDN at http://msdn2.microsoft.com/en-us/library/ms452896.aspx. This shows us the content IDs for existing types. Unlike other IDs in SharePoint (which are either an integer or a GUID), the content type ID is a special hexadecimal string that represents not only the content type itself, but also its parent — sort of like a human's surname, except in more detail.

There are two mechanisms for creating a content type. The first mechanism is appending a two-digit ID after the existing content type. The two-digit ID can be anything except 00. This is generally reserved for content types derived from your own content types because the potential for collision is so high.

The other mechanism (which is recommended) is to use 00 followed by a GUID that has had all of its punctuation removed. This creates a longer content type ID, so it's recommended only for the first level that you derive from a system type. Thereafter, you should use the two-digit mechanism described previously in order to minimize the overall length of the content type, which is capped at 512 bytes (in other words, 1,024 hexadecimal characters). You can learn more about content type IDs in the Content Type IDs entry in MSDN available at http://msdn2.microsoft.com/en-us/library/aa543822.aspx.

The content type for the Grades workflow task looks like this:

<ContentType ID="0x01080100B7336179CFFE43e59B86E241C767010E"
     Name="GradingTask" Group="Grading" Description="Grading Task"
     Version="0" Hidden="FALSE" >
      <FieldRefs>
     <FieldRef ID="{0116A5FF-6FB7-43e1-B3E3-30A58B40349C}"
           Name="GradingScore" DisplayName="Score" />
     <FieldRef ID="{81792580-6F97-4960-84C2-7A8A926D1DCE}"
           Name="GradingNotes" DisplayName="Notes"/>
     </FieldRefs>
</ContentType>

Here, the "00+Guid" method of creating the content type was used because it's the first level from a system content type. The workflow task content type is 0x010801, thus that is how this content type begins. The XML fragment also contains <FieldRef> nodes that correspond to the fields defined earlier — both the ID and the Name fields match exactly.

The next content type is the content type for the document that will have the same score and notes fields, but this time they won't be editable. The document content type is as follows:

<ContentType ID="0x010100ADEC125AC3C74c1bA7E3A50731525809"
     Name="GradingDocument" Group="Grading" Description="Grading Document"
     Version="0" Hidden="FALSE" >
      <FieldRefs>
     <FieldRef ID="{0116A5FF-6FB7-43e1-B3E3-30A58B40349C}"
           Name="GradingScore" DisplayName="Score" ShowInDisplayForm="TRUE"
          ShowInFileDlg="FALSE" ShowInListSettings="TRUE" ShowInEditForm="FALSE"
          ShowInNewForm="FALSE" ReadOnlyClient="TRUE" />
     <FieldRef ID="{81792580-6F97-4960-84C2-7A8A926D1DCE}"
          Name="GradingNotes" DisplayName="Notes" ShowInDisplayForm="TRUE"
          ShowInFileDlg="FALSE" ShowInListSettings="TRUE" ShowInEditForm="FALSE"
          ShowInNewForm="FALSE" ReadOnlyClient="TRUE" />
     </FieldRefs>
</ContentType>

This document type is derived from a document (0x0101) with the same GUID method used earlier — but not the same GUID. The content type also includes the same fields as the task by creating <FieldRef> nodes that match ID and Name attributes to the <Field> nodes created earlier. In this case, however, the fields should not be able to be written to. There is a ReadOnly attribute for the <FieldRef>, but it causes the field to become hidden as well, so you can't use it. Instead, the field is prevented from displaying on the new and edit forms. Following are descriptions of the new attributes:

The content types are done. To deploy them, a SharePoint Feature is needed. Because the workflow will automatically create a Feature, let's use the workflow Feature to deploy content types at the same time.

As mentioned previously, you must install a few components to develop workflows with SharePoint and WF. Once those pieces are installed, an option to create a SharePoint Sequential workflow will appear, as shown in Figure 8-1. The Grades workflow will perform a few basic steps. It will create a task, wait for the task to change, change the document with some code, and delete the task.

Figure 8.1. The SharePoint Sequential Workflow selection

To create the outline for the Grades workflow, follow these steps:

You may notice that there are little red exclamation points next to each of the four activities that you added to the design surface. That is because they all failed validation. The design interface is warning you that it knows, based on the current settings on the activities, that they won't work. Let's fix those errors and complete the workflow.

Figure 8.3. The "completed" workflow on screen

To get a CreateTask activity working, three things are needed: a correlation token, a task properties object, and a task guide. The easiest of these to take care of is the correlation token, which can be created with the following process:

For the onTaskChanged1 activity, you have essentially the same properties to set. However, because they are already created, the process is much easier. In this case, the correlation token must be set, as well as the TaskId property. In addition, taskProperties is bound to AfterProperties so that the taskItemId value will be set.

The onTaskChanged activity is done. The red exclamation point should be gone for this activity, too.

The final activity is the code activity where you will copy the fields from the task back to the document.

Double-click the codeActivity1 activity to create a handler for ExecuteCode. In this method, add these five lines:

SPListItem item = workflowProperties.Item;
SPListItem task =
workflowProperties.TaskList.GetItemById(taskProperties.TaskItemId);
item["GradingScore"] = task["GradingScore"];
item["GradingNotes"] = task["GradingNotes"];
item.SystemUpdate(false);

These five lines get the item for which the workflow was started, the task that was created, and then copy two fields from the task into the item. Finally, the code performs a system update to update the fields without changing the modified information for the item.

Completing the Delete Task activity is the same as completing the OnTaskChanged activity. You must set the CorrelationToken and the TaskId properties of the deleteTask1 activity so that the workflow will compile, and so that the task will be deleted. You can refer to the earlier section, "Completing OnTaskChanged," for the steps to bind these two properties.

The workflow is done. It should now build successfully. It's time to move on to deploying the workflow.

Upon opening feature.xml, you'll notice that there isn't much there besides a note telling you to use the snippets functionality with VS to add the nodes necessary in the feature.xml file. To create the feature.xml for the Grades workflow, follow these steps:

Because workflow.xml is the correct name of the element manifest that you want to create, you are finished with feature.xml. Save it and let's move on to workflow.xml.

When workflow.xml is opened, you'll find the situation very similar to the feature.xml. workflow.xml is a mostly empty file with a few instructions on how to add the content to the file. Let's follow a similar procedure as you did with the feature.xml file. To customize workflow.xml for the Grades workflow, follow these steps:

With workflow.xml finished, there's only one more file to finish: the install.bat file.

When you double-click it in the Solution Explorer, the install.bat file opens to reveal quite a few commands and instructions. It's a nice change from the feature.xml and workflow.xml files that you saw before. The changes you need to make to the install.bat file are basically two global searches and replaces. To customize the install.bat file, follow these steps:

Once you've made all of the replacements, select Save All in Visual Studio (File

One of the key techniques for making the workflow debugging process easier is to add a fault handler to your workflow that logs the exception that caused the error to the history log for the workflow. This gives you a way to capture exceptions in your code wherever they occur.

Adding a fault handler isn't that complicated. To demonstrate how easy it is, the following procedure shows how to add a fault handler to the Grades workflow created earlier:

With the fault handler in place, you can create an intentional error in the Grades workflow to cause the fault handler to execute. When I changed the codeActivity1_Execute code to the code in the following box, and ran the workflow again, the workflow history showed the Null Reference Exception, as seen in Figure 8-14.

private void codeActivity1_ExecuteCode(object sender, EventArgs e)
{
    SPListItem item = workflowProperties.Item;
    SPListItem task = null;/* =
    workflowProperties.TaskList.GetItemById(taskProperties.TaskItemId);
    */
    item["GradingScore"] = task["GradingScore"];
    item["GradingNotes"] = task["GradingNotes"];
    item.SystemUpdate(false);
}

That's a great start on the exception, but in reality, the entire text of the exception didn't fit. To see the entire text of the exception, including the full call stack, you'll need to view the Workflow History list directly. The Workflow History list was created as a hidden list, so you won't find it by navigating the user interface. However, you can directly enter the URL by appending Lists/Workflow%20History to the end of the site name. Thus, if the site name is http://w2k3server/grades, the full URL is http://w2k3server/grades/Lists/Workflow%20History. Figure 8-15 shows the extra data that you stored into OtherData — that wasn't displayed in the Description field.

Figure 8.14. The fault handler logged the exception

Figure 8.15. The Description and OtherData columns of the History list, respectively

Perhaps logging messages isn't the most glamorous way to debug something — but it's effective. Ever since the first programmers started adding PRINT statements to their code to dump out important variables at key times, we've been using the PRINT statement (or its updated equivalent) to gain insight to the inner workings of the code we write. SharePoint is no different. The PRINT statement in SharePoint workflow land is a LogToHistoryList activity. You've already seen it in use in the fault handler. You can just as easily add it to the mainline part of the workflow to drop yourself notes about where the workflow is — and what the values of key variables are.

Interactive debugging has made the need for logging statements nearly obsolete for most technology platforms. Though you can use interactive debugging with SharePoint, the process is still somewhat painful and, in some cases, inserting LogToHistoryList activities may be a simpler way to understand what is going on with your workflow.

Interactive debugging with SharePoint and workflows must be done by attaching to the IIS worker process (W3WP). Once attached to the process, you can set breakpoints, step through code, and inspect variables, with the following caveats:

Other than these caveats, debugging SharePoint workflows in VS isn't much different than debugging managed code. The Visual Studio Extensions for .NET 3.0 (Windows WF) does add a new code type that you can attach to — Workflow — as shown in Figure 8-16. By selecting this code type for debugging, you can set breakpoints on the activities in a workflow. Unlike other code types, the Workflow code type is mutually exclusive with the Managed code type. This isn't a problem in practice, however, because the Workflow code type allows you to debug managed code as well.

Figure 8.16. The Workflow code type to debug workflows

Knowing what the status codes, exceptions, and messages in the log file typically mean can certainly be enlightening on the problems. As mentioned earlier, the SharePoint log files, called Universal Logging Service (ULS) files, are located in C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12LOGS. They are the primary place that SharePoint will log internal exceptions to — particularly the workflow area of the product.

Table 8-1 shows a set of workflow statuses, messages, and resolutions that may help you locate your problem.