Chapter 28
Using the Workflow Web Service

IN THIS CHAPTER

• Overview of Workflows in SharePoint 2007
• Introduction to the Workflow Web Service
• Performing Workflow Tasks with the Web Service

With the release of Microsoft Office SharePoint Server (MOSS) 2007 comes the integration of the Windows Workflow Foundation into the product. This chapter provides you with an overview of how the Workflow Foundation has been integrated into SharePoint and, more important, how to utilize a subset of SharePoint’s workflow functionality remotely via the Workflow Web Service.

This chapter contains an overview of how the Workflow Foundation is integrated within SharePoint, an introduction to the Workflow Web Service, and extensive code samples illustrating how to remotely access and manipulate workflows via the web service.

Overview of Workflows in SharePoint 2007

The Windows Workflow Foundation (WF) was released as part of the .NET Framework 3.0 distribution, which also included the Windows Communication Foundation and the Windows Presentation Foundation. The .NET Framework 3.0 works on Windows XP SP2, Windows Server 2003, and Windows Vista. The workflow capabilities of MOSS 2007 are provided by the .NET Framework 3.0 running on Windows Server 2003.

The WF is a powerful runtime that provides applications with the ability to dynamically model workflows. This modeling ability extends from design time to runtime by providing a facility for applications to instantiate and manage WF programs as well as store and retrieve workflow state. The true power of the WF lies in its bookmarking nature. A WF program is a tree of activities that, by and large, execute asynchronously. WF programs are resumable and reentrant. This means that any given workflow can last for a few minutes or a few months. The lifetime of a workflow is unrelated to the lifetime of the process managing it. This key fact is essential to understanding how to properly deal with SharePoint workflows whether you’re working with them using the object model or the web service.

Introduction to the Workflow Web Service

The Workflow Web Service allows client applications not residing on a SharePoint server to integrate with SharePoint workflows. This web service publishes methods that allow for the querying and manipulation of tasks/to-dos for a given item, as well as the ability to query the list of open workflows for an item and even to start a new workflow for an item.

This web service is used by Microsoft Office 2007 clients to determine whether a document being opened has any workflow tasks associated with it, as well as allowing individuals to move the workflow forward by altering the tasks.

Table 28.1. Workflow Web Service Methods

The rest of this chapter provides an overview of each of the web service methods as well as some code examples that illustrate how to invoke the various methods.

Performing Workflow Tasks with the Web Service

Many of SharePoint’s web services are notorious for reading and writing seemingly unformatted blocks of Extensible Markup Language (XML) without much help as far as determining the format of the data. Unfortunately, the Workflow Web Service is just as difficult—with good reason. Many of the tasks associated with a workflow require the transmission of data specific to that workflow. In other words, the format of the parameters to several method calls change depending on whether you are working on an Approval workflow, a Feedback workflow, or a custom workflow created in Visual Studio 2005 or Microsoft Office SharePoint Designer.

Getting Workflow Data for an Item

If you want to retrieve every bit of possible information related to an item in a list, you can use the GetWorkflowDataForItem method on the Workflow Web Service. This method returns an XML node containing an enormous amount of information. You should note two important things about this method:

• The information returned varies depending on the credentials of the caller.
• You must refer to the item by its full uniform resource locator (URL), not by its item ID.

The code in the following sample illustrates how to invoke this method and save the resulting XML in a file on disk. Note that the URL of the web service is going to be the workflow.asmx file beneath the _vti_bin directory of the site in question.

Figure 28.1 shows the XML produced by the preceding code as viewed by Microsoft Internet Explorer.

Figure 28.1. Output XML after obtaining workflow data for an item.

Getting To-Dos for an Item

When someone opens a document in Microsoft Word (or Microsoft Excel, or any other Office 2007 product) from a SharePoint server, the Office client performs a check to see if the user opening the document has any tasks associated with that item. If they do have tasks, those tasks are displayed below the Ribbon. The method used by the Office client to determine the tasks associated with a given item is GetToDosForItem and is illustrated in the console application shown in Listing 28.1.

Listing 28.1. Obtaining a List of To-Dos for an Item

It is important to note that this method returns only those to-do items that are assigned to the calling user. In the preceding example, the calling user was a local user named “Juser” with a password of “joe”. The following output shows that “Joe User” has a single to-do item assigned to him for the item Test  document.docx.

Modifying To-Do Items

To modify task items, you must use the AlterToDo method. If you have had any experience with the SharePoint object model, it might help to know that this web service method is essentially a front end for the AlterTask method on the SPWorkflow class. This method takes the following parameters:

• item—A string containing the full URL to the item that is the source of the workflow, for example, the document list item (not the task item!)
• todoId—The integer ID of the task item
• todoListId—The globally unique identifier (GUID) of the list in which the task item resides
• taskData—The XML node indicating the task data to be sent to the web service

It is important to note that the taskData parameter is actually an XML serialization of a hash table in the following format:

<Data>
     <Name>Value</Name>
     <Name>Value</Name>
   ...
</Data>

The XML submitted to the web service is converted into a hash table and then passed to the AlterTask method of the SPWorkflowTask class. For more information on that method, consult the SharePoint Software Development Kit (SDK).

Claiming or Releasing Tasks

Occasionally, client applications might want to provide the ability for users to assume responsibility for workflow tasks, or they might want to be able to release responsibility for a workflow tasks. To do this, a single method has been provided for both actions: ClaimReleaseTask. You must supply the full URL of the item that spawned the workflow, as well as the numeric ID of the task item and the GUID of the task list. Finally, by supplying a value of false for the bClaimRelease parameter, the task will be released. Supplying a value of true will claim the task for the user whose credentials were supplied to the web service.

Getting Templates for an Item

If your code needs to know what templates are available to start new workflows for a given item, you can use the GetTemplatesForItem method. When you supply the full URL of the item as the parameter to this method, you will receive an XML node in return that contains the list of templates that can be used to start a workflow for the item.

The following code snippet shows how to invoke this method:

When this code is executed, it produces a rather large XML node, some of which is shown in Figure 28.2.

Figure 28.2. XML template data for an item.

Getting Workflow Task Data

This method works like the other methods that retrieve information related to an individual task and an item for which an active workflow exists. To get the resulting XML node for this method, you need to supply the full URL to the source item (for example, http://server/site/library/document.docx), the numeric ID of the task item, and the GUID of the list in which the task item exists.

Starting a Workflow

After you know the full URL of the item, and the GUID of the workflow template you want to start (possibly obtained through a method call to GetTemplatesForItem), you just need to supply the parameters to the workflow and call StartWorkflow to create a new workflow for the item.

Like many other methods, the final parameter to the StartWorkflow method (workflowParameters) is an XML node that contains a hash table of name/value pairs that seed the workflow with the input parameters. You can determine these parameters by looking at the workflow files, which should be especially easy if you were the author of the workflow you are activating.

Summary

The Workflow Web Service provides client applications on remote machines with the ability to access workflow template information, workflow task data, workflow instance information, and even to remotely start workflows. The format of the web service is designed such that it can be used by any workflow, which also makes the web service a little difficult to use.

One alternative to accessing the web service directly using generic methods might be to create your own web service that is tailored specifically to the workflow you are accessing, which might make the task of consuming the service from a client easier.