Using Smart Clients to Communicate with Workflows in Windows SharePoint Services 3.0
Summary: Smart clients communicate remotely with Office SharePoint Server 2007 via a series of Web services. Learn how to harness this power within custom-built clients.
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. 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. 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= "http://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="http://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. Dim nsmgr As New XmlNamespaceManager(assocNode.OwnerDocument.NameTable) nsmgr.AddNamespace _ ("wf", "http://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. 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="http://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= "http://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. 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:
|
Watch the Video (9:37)
|
