Using Smart Clients to Communicate with Workflows in Windows SharePoint Services 3.0

Applies to:  Microsoft Office SharePoint Server 2007

Patrick Tisseghem, U2U

February 2008

Smart clients communicate remotely with Microsoft Office SharePoint Server 2007 via a series of Web services. One of these is workflow.asmx, which enables interaction with the workflow at the level of Office SharePoint Server 2007. Smart clients, such as those of the 2007 Microsoft Office system, use this Web service, but you can also use the service within custom-built clients.

The following sections demonstrate how to enable smart clients to retrieve workflow information, use this information for local processing, and manage workflows and their associated tasks.

Adding the Web Reference

In Microsoft Visual Studio 2005, you get access to the various methods exposed by workflow.asmx by adding a Web reference to your project. You must set the URL of the Web service proxy class to the SharePoint site that stores the items with which you want your smart client to work.

Workflow ws = new Workflow();
ws.Url = textBoxSite.Text + "/_vti_bin/workflow.asmx";
ws.Credentials = CredentialCache.DefaultCredentials;

Dim ws As New Workflow
ws.Url = (textBoxSite.Text & "/_vti_bin/workflow.asmx")
ws.Credentials = CredentialCache.DefaultCredentials

Retrieving the Candidate Workflows for a Document

A call to the GetTemplatesForItem Web method returns all workflow templates that are associated at the level of the document library. The required parameter is the full URL to the document.

XmlNode wfTemplatesXML = ws.GetTemplatesForItem
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx");

Dim wfTemplatesXML As XmlNode = ws.GetTemplatesForItem _
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx")

The return value is an XMLNode object that contains all the details of the workflow templates and the data that was entered in the association form when the association was established. Here is an extract of the returned XML.

<TemplateData xmlns=
    "https://schemas.microsoft.com/sharepoint/soap/workflow/">
  <Web Title="MSDN" Url="http://moss/sitedirectory/msdn" /> 
  <List Title="Shared Documents" 
    Url="http://moss/sitedirectory/msdn/Shared Documents" /> 
  <WorkflowTemplates>
  <WorkflowTemplate Name="MSDN Approval" Description=
    "Routes a document for approval. Approvers can approve or reject 
    the document, reassign the approval task, or request changes 
    to the document." InstantiationUrl=
    "http://moss/sitedirectory/msdn/_layouts/IniWrkflIP.aspx?
    List=545dc556-b8ba-4628-886a-00fc2ce6bd02&ID=1&TemplateID=
    {4ee560ed-01f8-4466-a9d6-9d4a53068eec}">
  <WorkflowTemplateIdSet 
    TemplateId="4ee560ed-01f8-4466-a9d6-9d4a53068eec" 
    BaseId="c6964bff-bf8d-41ac-ad5e-b61ec111731c" />
  <AssociationData>
  <string>
    <my:myFields xml:lang="en-us" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:my="https://schemas.microsoft.com/office/infopath/2003/myXSD"> 
    <my:Reviewers> 
      <my:Person> 
        <my:DisplayName>LitwareInc Administrator</my:DisplayName>
        <my:AccountId>LITWAREINC\administrator</my:AccountId> 
        <my:AccountType>User</my:AccountType> 
      </my:Person> 
     </my:Reviewers> 
     <my:CC></my:CC> 
     <my:DueDate xsi:nil="true"></my:DueDate> 
     <my:Description></my:Description> 
     <my:Title></my:Title> 
     <my:DefaultTaskType>1</my:DefaultTaskType>
     <my:CreateTasksInSerial>true</my:CreateTasksInSerial> 
     <my:AllowDelegation>true</my:AllowDelegation> 
     <my:AllowChangeRequests>true</my:AllowChangeRequests>
     <my:StopOnAnyReject xsi:nil="true"></my:StopOnAnyReject>
     <my:WantedTasks xsi:nil="true"></my:WantedTasks> 
     <my:SetMetadataOnSuccess>false</my:SetMetadataOnSuccess>
     <my:MetadataSuccessField></my:MetadataSuccessField>
     <my:MetadataSuccessValue></my:MetadataSuccessValue>
     <my:ApproveWhenComplete>false</my:ApproveWhenComplete>
     <my:TimePerTaskVal xsi:nil="true"></my:TimePerTaskVal>
     <my:TimePerTaskType xsi:nil="true"></my:TimePerTaskType>
     <my:Voting>false</my:Voting>
     <my:MetadataTriggerField></my:MetadataTriggerField>
     <my:MetadataTriggerValue></my:MetadataTriggerValue>
     <my:InitLock>false</my:InitLock>
     <my:MetadataStop>false</my:MetadataStop>
     <my:ItemChangeStop>false</my:ItemChangeStop>
     <my:GroupTasks>false</my:GroupTasks>
    </my:myFields></string> 
  </AssociationData>
<Metadata>
  <Instantiation_FormURN>
  <string>urn:schemas-microsoft-com:office:infopath:workflow:
    ReviewRouting-Init:$Subst:LCID;</string> 
  </Instantiation_FormURN>
  </Metadata>
  </WorkflowTemplate>
  </WorkflowTemplates>
</TemplateData>

Starting a Workflow

To create and start a workflow instance, you call the StartWorkflow Web method. This method requires three parameter values. The first one is the full URL to the document in the SharePoint document library, the second one is the GUID of the workflow template, and the third one is the XML that contains the workflow parameters. The last two values can be pulled from the XML returned by the previously discussed Web method. In the code below, the assocNode variable of type XMLNode contains the XML of the selected workflow template.

XmlNamespaceManager nsmgr = 
  new XmlNamespaceManager(assocNode.OwnerDocument.NameTable);
nsmgr.AddNamespace("wf",
  "https://schemas.microsoft.com/sharepoint/soap/workflow/");
XmlNode dataNode = assocNode.SelectSingleNode
  ("//wf:AssociationData/wf:string",nsmgr);
XmlDocument doc = new XmlDocument();
doc.LoadXml(dataNode.InnerText);
XmlNode idNode = assocNode.SelectSingleNode
  ("//wf:WorkflowTemplateIdSet", nsmgr);
Guid templateID = new Guid
  (idNode.Attributes.GetNamedItem("TemplateId").Value);
ws.StartWorkflow
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx", 
  templateID, doc.DocumentElement);

Dim nsmgr As New XmlNamespaceManager(assocNode.OwnerDocument.NameTable)
nsmgr.AddNamespace _
    ("wf", "https://schemas.microsoft.com/sharepoint/soap/workflow/")
Dim dataNode As XmlNode = _
    assocNode.SelectSingleNode("//wf:AssociationData/wf:string", nsmgr)
Dim doc As New XmlDocument
doc.LoadXml(dataNode.InnerText)
Dim idNode As XmlNode = _
    assocNode.SelectSingleNode("//wf:WorkflowTemplateIdSet", nsmgr)
Dim templateID As New _
    Guid(idNode.Attributes.GetNamedItem("TemplateId").Value)
ws.StartWorkflow _
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx", _
  templateID, doc.DocumentElement)

Retrieving the To Do Items

During a workflow, tasks are created, stored in a task list, and assigned to people. In the smart client, you can retrieve the list of tasks by calling the GetToDosForItem Web method. The method requires the full URL to the document as the only parameter.

XmlNode todosNode = ws.GetToDosForItem
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx");

Dim todosNode As XmlNode = ws.GetToDosForItem _
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx")

The return value contains all of the details of the tasks created. Here is an extract that represents one of the tasks.

<ToDoData xmlns="https://schemas.microsoft.com/sharepoint/soap/workflow/">
  <xml xmlns:s="uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882" 
  xmlns:dt="uuid:
    C2F41010-65B3-11d1-A29F-00AA00C14882" 
    xmlns:rs="urn:schemas-microsoft-com:rowset" 
    xmlns:z="#RowsetSchema">
  <rs:data ItemCount="1">
  <z:row ows_ContentTypeId="0x01080100C9C9515DE4E2400190507
    4F980F93160000652C2C5B8FFB84CAA3A043A99027F31" 
    ows_Title="Please approve Workflow Demo" 
    ows_Priority="(2) Normal" 
    ows_Status="Not Started" 
    ows_AssignedTo="1;#LitwareInc Administrator"
    ows_Body="Please approve Workflow Demo" 
    ows_StartDate="2007-07-22 02:47:02" 
    ows_WorkflowLink="http://moss/SiteDirectory/msdn/Shared 
      Documents/doc1.docx, Workflow Demo" 
    ows_WorkflowName="MSDN Approval" ows_TaskType="1"
    ows_FormURN="urn:schemas-microsoft-
      com:office:infopath:workflow:ReviewRouting-
    Review:$Subst:LCID;"
    ows_HasCustomEmailBody="0" ows_SendEmailNotification="1"
    ows_Completed="0" 
    ows_WorkflowListId="{545DC556-B8BA-4628-886A-00FC2CE6BD02}"
    ows_WorkflowItemId="1" ows_AllowChangeRequests="True"
    ows_AllowDelegation="True"
    ows_BodyText="Please approve Workflow Demo" 
    ows_ContentType="Office SharePoint Server Workflow Task"
    ows_ID="5" ows_Modified="2007-07-22 02:47:02"
    ows_Created="2007-07-22 02:47:02"
    ows_Author="1;#LitwareInc Administrator" 
    ows_Editor="1073741823;#System Account"
    ows_owshiddenversion="1" ows_WorkflowVersion="1" 
    ows__UIVersion="512" ows__UIVersionString="1.0"
    ows_Attachments="0" ows__ModerationStatus="0"
    ows_LinkTitleNoMenu="Please approve Workflow Demo"
    ows_LinkTitle="Please approve Workflow Demo" 
    ows_SelectTitle="5" ows_Order="500.000000000000"
    ows_GUID="{258EB59E-E68F-48B3-AE56-B4D4416AA213}"
    ows_WorkflowInstanceID=
      "{621227F3-6AF3-4977-B12F-7512BDCAD1A1}"
    ows_FileRef="5;#SiteDirectory/msdn/Lists/Tasks/5_.000"
    ows_FileDirRef="5;#SiteDirectory/msdn/Lists/Tasks"
    ows_Last_x0020_Modified="5;#2007-07-22 02:47:03" 
    ows_Created_x0020_Date="5;#2007-07-22 02:47:03"
    ows_FSObjType="5;#0" ows_PermMask="0x7fffffffffffffff"
    ows_FileLeafRef="5;#5_.000"
    ows_UniqueId="5;#{DAB815E4-7D42-4E4B-80C0-3B69050729E1}"
    ows_ProgId="5;#"
    ows_ScopeId="5;#{3B1257E3-14A9-437D-9FA2-DC7308BD1CAA}"
    ows__EditMenuTableStart="5_.000" ows__EditMenuTableEnd="5"
    ows_LinkFilenameNoMenu="5_.000" ows_LinkFilename="5_.000"
    ows_ServerUrl="/SiteDirectory/msdn/Lists/Tasks/5_.000"
    ows_EncodedAbsUrl=
      "http://moss/SiteDirectory/msdn/Lists/Tasks/5_.000"
    ows_BaseName="5_" ows__Level="1" ows__IsCurrentVersion="1"
    ows_MetaInfo_vti_versionhistory=
      "50c00a06c6b745bb8779f8c02692ad16:1"
    ows_MetaInfo_WorkflowCreationPath=
      "4ee560ed-01f8-4466-a9d6-9d4a53068eec;"
    ows_TaskListId="50c00a06-c6b7-45bb-8779-f8c02692ad16"
    ows_EditFormURL=
    "http://moss/SiteDirectory/msdn/_layouts/WrkTaskIP.aspx?ID=
    5&List=50c00a06-c6b7-45bb-8779-f8c02692ad16" /> 
  </rs:data>
  </xml>
</ToDoData>

Completing a Task

The final call is to the AlterToDo Web method, which enables the smart client to complete one of the workflow tasks. Four parameter values are required. The first one is again the full URL to the document. The second and third values are retrieved from the XML returned by the previously discussed Web method. (The sample code contains the todoNode representing a single task.) The second value is the ID of the task; the third value is the GUID of the task list where the task is stored. The final value is an XML node that contains the values for the task. In the sample, the XML is the following.

<my:myFields xmlns:my=
  "https://schemas.microsoft.com/office/infopath/2003/myXSD" >
 <my:TaskStatus>#</my:TaskStatus>
 <my:Comments />
 <my:DelegateTo />
 <my:NewDescription>Please approve Workflow Demo</my:NewDescription>
 <my:NewDueDate />
 <my:RequestTo />
 <my:Decline>0</my:Decline>
 <my:dcr>0</my:dcr>
 <my:Status>Completed</my:Status>
</my:myFields>

The following code remotely completes a workflow task.

int todoID = 
  int.Parse(todoNode.Attributes.GetNamedItem("ows_ID").Value);
Guid tasklistID = new 
  Guid(todoNode.Attributes.GetNamedItem("ows_TaskListId").Value);
XmlDocument doc = new XmlDocument();
doc.Load(@"..\..\TaskData.xml");
XmlNode node = ws.AlterToDo
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx", 
  todoID,tasklistID, doc.DocumentElement);

Dim todoID As Integer = _
  Integer.Parse(todoNode.Attributes.GetNamedItem("ows_ID").Value)
Dim tasklistID As New _
  Guid(todoNode.Attributes.GetNamedItem("ows_TaskListId").Value)
Dim doc As New XmlDocument
doc.Load("..\..\TaskData.xml")
Dim node As XmlNode = Me.ws.AlterToDo _
  ("http://moss/sitedirectory/msdn/shared documents/doc1.docx", _
  todoID, tasklistID, doc.DocumentElement)

The support for workflows within SharePoint Server 2007 is exposed in the object model by a series of classes that are also remotely accessible through workflow.asmx. This Visual How To discussed the following methods that enable smart clients to retrieve workflow information, use this information for local processing, and manage workflows and the tasks involved:

• GetTemplatesForItem   Retrieves all of the workflow templates that are associated at the level of the container that stores the item or the content-type definition for the item.

• StartWorkflow   Starts a workflow instance based on a workflow template for a specific item and passes to the workflow engine data that must be used during the initiation of the workflow.

• GetToDosForItem   Retrieves the tasks that are created for the item in the workflow.

• AlterToDo   Enables the modification (such as reassignment or completion) of a task.

Watch the Video (9:37)

• SharePoint Developer Center

• Office Developer Center