SharePoint Document Workspaces for Developers
Office 2003 is being released this month, and a cast of supporting applications is already available. One of these is Windows SharePoint Services 2.0, the free team add-on for Windows Server 2003. If you're not familiar with SharePoint Services basics, take a look at What Developers Need to Know About Windows SharePoint Services. In this article, I'm going to drill into one key place where SharePoint and Office 2003 overlap: document workspaces
Introducing Document Workspaces
Figure 1 shows a typical document workspace, in this case using Excel 2003 (the document workspace feature works with Word, Excel, and PowerPoint in this version of Office). The workspace is built around an Excel document. The task pane at the right hand side of the screen contains the collaborative content, including members, tasks, files, and hyperlinks.
The Shared Workspace task pane lets users interact with all of the shared content. For example, they can add new tasks, schedule meetings, or link additional documents to the workspace. But as a developer, you'd probably prefer a more programmatic way to control workspaces. For example, suppose you could automatically generate a list of the open tasks in a workspace? Fortunately, this being Office, that's entirely possible. Like nearly every other part of Office, workspaces are available through an object model.
The Shared Workspace Object Model
Figure 2 shows the object model for shared workspaces. This object model is consistent across all of the workspace hosts (Word, Excel, and PowerPoint). As you can see, it's fairly simple: there's a top-level SharedWorkspace object that can be reached from the object representing each individual application. Below that top-level object are other collections and objects that represent the contents of the workspace.
If you understand VBA, using these objects is easy. For example, here's a tiny piece of code that you can run as a macro to list out some information about shared workspace tasks in the current document:
Public Sub ListTasks() ' Retrieve the object root Dim sws As SharedWorkspace Set sws = Me.SharedWorkspace ' Iterate through all tasks Dim swt As SharedWorkspaceTask For Each swt In sws.Tasks ' Print out some information Debug.Print swt.Title Debug.Print swt.DueDate Debug.Print swt.AssignedTo Next swt End Sub
If you run this code as a macro, and there are actually shared tasks, you'll get information on each one:
Order Louisiana Hot Spiced Okra 10/29/2003 Mike Gunderloy Customer Followup Call 10/2/2004 Nancy Davolio Pack and ship order 9/27/2003 Margaret Peacock
Of course, in a production application you'd also want to avoid errors. One way to see whether the current document is part of a shared workspace is to check the value of the SharedWorkspace.Connected property. If this property returns True, then the rest of the shared workspace objects will be available.
Creating Objects in a Workspace
One good use for the shared workspace object model is to inject new objects into a workspace programmatically. For example, you might want to automatically add updated files to a file library from a batch process that runs overnight, or assign tasks based on some external input. Here's a bit of code to add a new task to a workspace:
Public Sub AddNewTask() ' Retrieve the object root Dim sws As SharedWorkspace Set sws = Me.SharedWorkspace ' Add a new task sws.Tasks.Add "Check Receipt", _ msoSharedWorkspaceTaskStatusNotStarted, _ msoSharedWorkspaceTaskPriorityNormal End Sub
Each of the collections in the shared workspace has its own Add method, though each takes different parameters. For example, when adding a task, you can specify any of these parameters (only the task name is required):
- Task Name
- Date due
Note that the object model supplies constants for arguments such as Status and Priority, which are limited to a fixed number of values.
The Collection Interface
Each of the collections in the shared workspace (SharedWorkspaceTasks, SharedWorkspaceLinks, and so on) supports five members. You've already seen the Add method. Two other members are standards that you probably expect on any Office VBA collection: Count (to retrieve the number of items in the collection) and Item (the enumerator for the collection). Each collection also has a Parent property that points to the containing SharedWorkspace object.
The last property of each collection is the ItemCountExceeded property. It turns out that there's a user interface limitation to the Document Workspace task pane: it can only display 99 members, tasks, documents, or links. When one of the collections grows so large that it cannot be displayed, the ItemCountExceeded property will return True.
What about removing an item? This is a method, not of the collection, but of the individual item. For example, you could remove the first task in a workspace with this bit of code:
Public Sub RemoveFirstTask() ' Retrieve the object root Dim sws As SharedWorkspace Set sws = Me.SharedWorkspace ' Remove the first task sws.Tasks(1).Delete End Sub
Note that the collections in the shared workspace object model are one-based.
With this bit of basic knowledge, you should be able to start seeing how to leverage document workspaces in your own custom Office 2003 applications. For example, do you work with Office documents as part of a workflow application? Perhaps right now your application e-mails people with a list of jobs that they need to perform in order to move things along. With the new capabilities, you could instead create a document workspace containing the document, add the jobs as custom tasks, and send a simple link to the document. As soon as they open it up in Word or Excel, they'll see their assigned tasks right there.
This is just one facet of a major push in Office 2003, which I think of as programmable collaboration. The major applications within Office have been suitable for serious work with standalone documents for several versions now. Office 2003 adds tighter integration with SharePoint, Outlook, and Exchange, as well as other products like Communications Server, to move us forward to a vision of working with a complexly-interlinked network of documents and users. It will be interesting to see how well this can be exploited by developers to build new applications on top of Office.
Mike Gunderloy is the author of over 20 books and numerous articles on development topics, and the lead developer for Larkware. Check out his MCAD 70-305, MCAD 70-306, and MCAD 70-310 Training Guides from Que Publishing. When he's not writing code, Mike putters in the garden on his farm in eastern Washington state.