Chapter 20
Using the Document Workspace Web Service
IN THIS CHAPTER
- Overview of Document Workspaces
- Managing Document Workspace Sites
- Managing Document Workspace Data
- Working with Folders
- Locating Documents in a Workspace
- Managing Workspace Users
Document Workspace sites are Windows SharePoint sites that facilitate team collaboration around one or more documents. This chapter provides you with an overview of Document Workspace sites and how to query and manipulate them using the Document Workspace Web Service. This chapter provides coverage of how to manage the Document Workspace (DWS) sites themselves, as well as how to manipulate DWS data, work with folders, find documents, and even manage DWS users.
Overview of Document Workspaces
Document Workspace sites (often just called Document Workspaces) are collaborative Windows SharePoint Services (WSS) sites that revolve around one or more documents. The purpose of these sites is to facilitate collaboration in the creation and revision of the document or documents. For example, you might have a team that has been tasked with creating a project plan for a project, or a team that must create a budget document for FY 2007. Document Workspaces provide document libraries and other relevant SharePoint lists that teams might need to collaborate on these documents. After the collaboration is complete and an artifact has been produced, teams often publish the artifacts to other SharePoint sites or to the central portal.
Document Workspaces are also used heavily within Microsoft Office Outlook when users exchange shared attachments. For more information on Document Workspaces from a user and administrator perspective, the Microsoft Office SharePoint Server (MOSS) 2007 online help is a great place to start.
Managing Document Workspace Sites
There are three main management tasks when dealing with Document Workspaces. The first task is to validate a potential DWS uniform resource locator (URL) to ensure that it doesn’t contain any invalid characters, and the second and third tasks are to create and delete a Document Workspace. This section shows you how to perform these tasks using the DWS Web Service that can be found at the URL [server]/_vti_bin/dws.asmx.
Validating Document Workspace Site URLs
Before you create a new Document Workspace, you should first check to see if the URL you intend to use is valid. The CanCreateDwsUrl method performs several operations. First, it checks to see if the calling user has permissions to create the site. Next, it validates the URL and trims it to the appropriate size and replaces any special characters with URL-safe equivalents. This method returns the modified and validated URL in a simple Extensible Markup Language (XML) string that can then be used to create a Document Workspace site.
The format of the return value for this method is
<Result>(altered and validated URL)</Result>
Creating and Deleting Document Workspace Sites
After you know the name of the DWS you plan to create, and you have validated that name using the CanCreateDwsUrl method, you can create the new site. To create a new DWS, use the CreateDws method with the following parameters:
name—This is the URL of the new DWS. This argument is optional, and calls to this method often work much more reliably without sending this parameter.users—This is an XML string containing a list of users to add to the site after it is created. This XML has the following format:<UserInfo>
<Item Name="display name" Email="e-mail address of user"/>
</UserInfo>title—This is the title of the new DWS site. If thenameparameter is left blank, this parameter is validated using the same process as inCanCreateDwsUrland then used as the new site’s URL.documents—This is an optional list of documents that will be retained as potential results for calls to theFindDwsDoc(discussed later in this chapter) method. This parameter is primarily used by Outlook.
The following code validates a new URL, displays the validated result, and then proceeds to create and delete a new DWS. The localhost reference was created by obtaining a web reference from http://localhost/_vti_bin/dws.asmx. When creating this sample, you should obviously obtain a web reference from your own server.20.1
Listing 20.1. Creating and Deleting Document Workspace Sites
One important thing to note about the preceding code is that the DWS was created using the web service at the root of the portal, but the code had to attach to the DWS itself to delete it. This model is used throughout the MOSS 2007 web services. The parent site to which the web reference is made will be the parent site for a new DWS when created.
If all went well when running this application, your console output should be as follows:
<Result>FY 2006_2007 Budget</Result>
DWS Created. Doclib URL: Shared Documents
DWS @ FY 2006_2007 Budget Deleted.
Note how the ampersand from the original title has been replaced with an underscore because the ampersand is not a URL-safe character.
Managing Document Workspace Data
The Document Workspace Web Service exposes several methods for dealing with data and metadata related to the DWS and to the documents contained within it. This section provides an overview of how to utilize those methods: GetDwsData and GetDwsMetaData.
Getting DWS Data
The GetDwsData method provides detailed information about a given document within the DWS as well as information about the DWS itself such as its title, member list, and list of potential assignees for a document. Listing 20.2 illustrates a console application that executes this method and displays the results. The results of this method call are an XML format string with the following top-level elements: Title, User, LastUpdate, Members, Assignees, and multiple elements called List containing the IDs of all lists in the DWS. You can use these IDs in conjunction with the Lists Web Service (see Chapter 22, “Using the Lists Web Service”) to find out more detail about each list.
Listing 20.2. Using the GetDwsData Method
On a file uploaded to a sample Document Workspace (in this case it is “Budget Committee”, but you should feel free to create your own) called Budget.docx, the output of the console application will be similar to the following text:
Getting DWS MetaData
The GetDwsMetaData method returns extended information about a Document Workspace above and beyond what is returned by GetDwsData. This method returns an XML string that contains the following top-level elements:
SubscribeUrl—The URL to create a new alert on the DWS.MtgInstance—If the workspace is a Meeting Workspace, the node that contains the meeting instance ID.SettingUrl—The node that contains the URL to the Site Settings page for the workspace.PermsUrl—The URL for site permissions configuration.UserInfoUrl—The URL for managing user information and security settings for the site.Roles—A list of site roles.Schema—If theGetDwsMetaDatamethod is invoked with theMinimalparameter set tofalse, one or more Schema nodes is returned describing the DWS schemas.ListInfo—As with Schema, when theMinimalparameter is set tofalse, one or more of these nodes is returned containing detailed information on the site lists.Permissions—A list of site permissions.HasUniquePerm—A true/false node indicating whether the site has unique permissions or if they are inherited from the parent.WorkspaceType—A string indicating the type of workspace: DWS (Document Workspace), MWS (Meeting Workspace), SPS, or blank.IsADMode—A value indicating whether the site is in Active Directory mode.DocUrl—The URL of the document (note that this doesn’t include the URL of the server itself, just the relative path of the document).Minimal—A value indicating if the method call was requested with Minimal information.Results—The entire set of results returned by theGetDwsDatamethod for the same document.
The following code illustrates taking the XML string returned by GetDwsMetaData and populating a List view with the XML nodes and their contents. This can be a helpful tool for examining the data before writing production code against the DWS service.
The output of the preceding code is shown in Figure 20.1.
Figure 20.1. Results of a call to GetDwsMetaData.
Working with Folders
The Document Workspace Web Service allows developers to add and remove folders from document libraries contained within a Document Workspace through the CreateFolder and DeleteFolder methods. This can be an extremely powerful feature that adds a lot of flexibility for the code developers who write against this web service. If you need to work with content types in regard to the folders, you need to use the Lists Web Service (discussed in Chapter 22).
The following code creates a folder and then pauses—allowing you to see that the change has taken place. Pressing Enter again deletes the folder.
localhost.Dws docService = new localhost.Dws();
docService.Credentials = System.Net.CredentialCache.DefaultCredentials;
docService.Url = "http://localhost/budget/_vti_bin/dws.asmx";
string result = docService.CreateFolder("Shared Documents/Rough Drafts");
Console.WriteLine(result);
Console.WriteLine("Folder created. Press enter to delete.");
Console.ReadLine();
result = docService.DeleteFolder("Shared Documents/Rough Drafts");
Console.WriteLine(result);
Console.WriteLine("Folder deleted. Press enter to quit.");
Console.ReadLine();
As with most of the DWS Service data manipulation methods, if no errors occurred, the string result contains the <Result/> element. If an error occurred, an <Error> node is returned. The code in Listing 20.3 contains some helper methods for parsing the output of many of the DWS methods, including detecting error conditions and parsing the actual error details. You can also find this code in some of the Software Development Kit (SDK) samples provided by Microsoft.
Listing 20.3. SDK Sample DWS Utility Methods
Figure 20.2 shows the newly created folder in the Shared Documents folder of the Budget Committee DWS.
Figure 20.2. A programmatically created folder on a Document Workspace.
Locating Documents in a Workspace
Document Workspaces provide a special feature where you can associate a unique identifier with a document so that the URL of the document can be easily retrieved later. Outlook makes extensive use of this feature when creating Document Workspaces around shared attachments.
Using this feature requires two steps. First, when creating the DWS site, you need to supply a list of documents and their associated identifiers. Second, you then need to query the DWS for the URL of a stored document based on the document’s unique ID using the FindDwsDoc method.
The code in Listing 20.4 creates a new Document Workspace site and stores a document ID on the new site, and then retrieves the absolute URL of the document using the ID and the FindDwsDoc method.
Listing 20.4. Creating a Site with Document ID Storage
The preceding code creates a new DWS site with the CreateDws method and supplies the following string for the documents parameter:
<Documents>
<item ID="{guid}" Name="BudgetDocument.docx"/>
</Documents>
This associates a unique identifier with the filename BudgetDocument.docx. When the console application is executed, it produces the following output:
<Result>Budget Test Site</Result>
DWS Created. Doclib URL: Shared Documents
Document with ID 68b02155-c9b2-44cc-82fc-50feeb871310 can be found at
http://win2k3r2lab/Budget Test Site/Shared Documents/BudgetDocument.docx
If you look closely at the preceding code sample, you might notice something missing. The code never actually uploaded a file into the document library! You can think of this document storage and location feature as a persistent dictionary designed specifically for storing and retrieving a fixed set of documents. It is not designed to be used when you don’t know what you’re looking for. However, if the code knows ahead of time the unique ID of a document it needs, this feature can be extremely useful, such as in the case of Outlook and shared attachment Document Workspaces.
Managing Workspace Users
You saw earlier in this chapter that when you create a DWS site you can use an XML fragment to specify a list of users that you want to add to the site upon creation.
There is also a function that you can use to remove users from the site: RemoveDwsUser. This method takes the ID of the user and removes that user from the DWS. Unfortunately, there are no methods within the Document Workspace Web Service that provide access to a list of user IDs. To gain access to user information such as profile data, security information, group membership, and IDs, you need to use the Users and Groups Web Service, which is covered in Chapter 24, “Working with User Profiles and Security.”
To remove a user from a DWS site, simply invoke the RemoveDwsUser method, as shown here with an ID retrieved from the Users and Groups Web Service:
dwsService.RemoveDwsUser(userIdString);
Summary
Document Workspaces are one of Microsoft Office SharePoint Server’s most powerful collaboration tools. Tightly integrated into Microsoft Office, they enable users to collaborate on one or more related documents quickly, easily, and with tons of additional features and tools. This chapter introduced you to the Document Workspace Web Service, which can be used to create and delete workspaces, retrieve metadata and detailed information about workspaces, remove users, and even retrieve URLs for documents quickly based on unique identifiers. The DWS Web Service is yet another extremely powerful web service that you can now add to your list of available tools for programming with MOSS.