IN THIS CHAPTER
Microsoft Office SharePoint Server (MOSS) provides a powerful foundation that provides for collaboration around the concept of meetings. Meeting Workspaces provide websites dedicated to supporting and maintaining meetings, meeting information, attendee lists, minutes, meeting-related documents, and much more.
Meetings themselves take place within Meeting Workspaces and can either be recurring or stored as single-instance events. As developers themselves, the authors of this book obviously think that the most important aspect of SharePoint meetings is that you can control every aspect of meetings programmatically using the SharePoint object model and web services (web services and meetings are discussed in Chapter 23, “Using the Meeting Workspace Web Service”).
A Meeting Workspace is just a special web template that comes with all default SharePoint installations. With that knowledge in hand, you can use your knowledge of manipulating sites and webs (SPSite
and SPWeb
classes, respectively) to manipulate Meeting Workspaces. The following two sections show how to create and delete Meeting Workspaces.
As discussed in Chapter 4, “Working with Sites and Webs,” you can create a Meeting Workspace by adding a new website to a parent SPWebCollection
instance. For example, to add a Meeting Workspace to a site collection, you would add it to the site’s AllWebs
property. To add a Meeting Workspace as a subweb beneath another website (SPWeb
instance), you just need to add the new workspace to the website’s Webs
property, which is of type SPWebCollection
.
Listing 9.1 shows a simple console application that creates a new Meeting Workspace web.
Listing 9.1. Creating a New Meeting Workspace
You should notice a couple of interesting things about this code. The first is that you must obtain a reference to an SPWebTemplate
to create a new website based on that template. Second, the uniform resource locator (URL) of a new website is site-relative, and as such does not use a preceding forward slash.
The preceding sample creates a new Meeting Workspace to manage meetings related to the FY 2006 budget status and makes the new Meeting Workspace a subweb of the budget Team Site, as shown in Figure 9.1.
Figure 9.1. The new meeting workspace.
If you plan to follow along with the code throughout the rest of the chapter, you should execute the code from Listing 9.1 (modified for your environment, of course) so that you will have a Meeting Workspace with which to experiment for the rest of the chapter.
Deleting a Meeting Workspace follows the same pattern as deleting any other instance of the SPWeb
class. You can delete a web in two different ways. The first method is to call the Delete
method on the SPWeb
object itself. The second method is to call Delete
on an instance of SPWebCollection
and pass in the URL of the web to delete.
It might be extremely tempting to use the SPMeeting
class in the Microsoft.SharePoint.Meetings
namespace to gain access to the properties of a meeting instance or meeting recurrence, but, unfortunately, that doesn’t work. As you will see later in the chapter, the primary use for the SPMeeting
class is to provide a shortcut to creating new meeting instances on existing Meeting Workspace sites.
To get at the real data that supports a Meeting Workspace and all meeting instances within that workspace, you need to dig down into the lists on the Meeting Workspace site, some of which are hidden and only directly accessible programmatically.
Table 9.1 provides a description of the lists that are automatically created as a part of every new Meeting Workspace. Some types of Meeting Workspaces come with more information, but Table 9.1 represents the basic set of lists that comes with each Meeting Workspace.
Table 9.1. Default Lists in a Meeting Workspace
Meetings themselves, whether individual meetings or recurring meetings, are stored in the Meeting Series list on the Meeting Workspace.
Keep in mind that the Meeting Series list is hidden, and you cannot see it from within SharePoint—even if you are an administrator and click the View All Site Content button on the navigation bar. Table 9.2 provides a detailed list of some of the more commonly used columns in the Meeting Series list.
Table 9.2. Useful Columns in the Meeting Series List
Meetings appear in the Meeting Series list in two different styles. When the meeting isn’t recurring, each list item in the list represents a distinct occurrence of the meeting with a unique date and time. When the meeting is recurring, the first item in the list contains information on how often and on what day and time the meeting occurs. As users navigate through the Meeting Workspace and click on new instances, items are created in the list for that particular occurrence. Individual meetings have simple, auto-incremented instance IDs, such as 1, 2, 3, and so on. Recurring meetings have numeric instance IDs that correspond to the date on which the meeting is to occur, such as 20061012 or 20061013.
Obtaining data from recurring meetings can be tricky. You might encounter situations in which your code attempts to access a list item for a meeting occurrence that has not yet been provisioned in the Meeting Series list. To ensure that the individual instance has been created, you can make a dummy web request to the instance’s home page, for example:
http://server/sites/mymeeting/default.aspx?InstanceID=20061012
Meeting management involves the creation, cancellation, and updating of meetings. Some of these tasks are pretty straightforward and other tasks, such as updating an existing meeting, might not be immediately obvious. This section shows you how to create, update, and cancel meetings.
Creating a new meeting involves calling the Add
method on the SPMeeting
class. Given experience with the SharePoint application programming interface (API), you might be tempted to try to create a new instance of the SPMeeting
class with a default constructor. Unfortunately, this doesn’t work. To obtain a reference to an SPMeeting
object, you need to call the GetMeetingInformation
method on an instance of a Meeting Workspace site.
The code in Listing 9.2 illustrates how to obtain a reference to a Meeting Workspace’s SPWeb
instance and how to use that reference to get an SPMeeting
object, which can then be used to create a new meeting.
Listing 9.2. Creating a New Meeting Instance Within a Meeting Workspace
The Add
method can either take the text version of an iCalendar format file, or it can take the individual arguments, as shown in Listing 9.2. The version illustrated takes the following arguments:
organizer
—The email address of the person organizing the meeting. If this email address does not match the email of the security context of the user making the method call, that user must be a valid scheduling delegate or SharePoint will throw an exception.uid
—A unique ID (GUID) string to be used for the new meeting.sequence
—A numeric sequence number used for ordering multiple updates.dateStamp
—A specially formatted string indicating the time stamp for when the meeting was created.title
—The title of the meeting.location
—The location of the meeting.dateStart
—The time stamp for when the meeting starts.dateEnd
—The time stamp for when the meeting ends.nonGregorian
—A Boolean value indicating whether the meeting time stamps are in a non-Gregorian calendar.[out] nMeetingCount
—The meeting count for the workspace.When looking at the code in Listing 9.2, take note of the format of the parameters for the meeting’s start and end time. First, the times are in the Greenwich mean time (GMT) time zone, and they use a format where the date comes first in the format YYYYMMDD, followed by a T, followed by the time in the format HHMMDD, followed by a Z. If you do not use this time stamp format, SharePoint will throw an exception and reject the attempt to create the new meeting.
For more complex meeting occurrences such as recurring meetings, you might find it easier to supply the iCalendar format text instead of discrete parameters, as shown in Listing 9.2.
Modifying an instance of a meeting can be done in a number of ways. You could always try the brute force method and modify the Meeting Series list itself. However, you can use the SPMeeting.Update
method to make changes to a meeting.
The following is a list of parameters to the SPMeeting.Update
method:
uid
—This is the persistent GUID for the calendar entrysequence
—A sequence number used for organizing multiple updatesdateStamp
—A time stamp indicating the date and time that the change was madetitle
—The title (or subject) of the meetinglocation
—The location of the meetingdateStart
—The date/time the meeting startsdateEnd
—The date/time the meeting endsnonGregorian
—A Boolean value indicating whether the time stamps are in a non-Gregorian calendarAfter a meeting has been created using the Add
method, you can use the GUID for the meeting to make changes to the start time, end time, meeting location, and subject.
Deleting a meeting is accomplished using the Cancel
method on the SPMeeting
class. Meetings are canceled on a per-recurrence basis, so you will need to know the instance ID you are canceling. For recurring meetings, the instance ID is a number that represents the date of the meeting such as 20061115
for a meeting that occurs on November 15, 2006. For individual meetings, the instance ID is simply a sequential number starting with 1. The Cancel
method has the following arguments:
uid
—The GUID of the meetingrecurrenceID
—The recurrence ID of the meeting to be canceledsequence
—A number used for sequencing multiple updatesdateStamp
—A date stamp used for when the deletion occurredcancelMeeting
—A Boolean value indicating whether the meeting should be deletedEven if the meeting is associated with a calendar event, and you remove the calendar event, the meeting instance will still exist on the Meeting Workspace site.
As with most other meeting-related data, you can either access the lists directly (which some people find far easier than using the SPMeeting
class) or you can utilize the appropriate methods on the SPMeeting
class. The preferred method is to use the SetAttendeeResponse
method on the SPMeeting
class. This method takes the following arguments:
attendeeId
—The email address of the attendee in questionuid
—The persistent GUID for the calendar componentrecurrenceId
—The recurrence ID for the meetingsequence
—A number used to arrange multiple updatesdateStamp
—The date and time stamp for the modification of the calendar componentresponse
—The response from the user (Accepted, Tentative, or Declined)You might have noticed that calendar events can be linked directly with instances of a meeting within a Meeting Workspace site. This can be accomplished by calling the LinkWithEvent
method on the SPMeeting
class. To make this method call, you need to have an instance of the SPWeb
class representing the website containing the calendar, and you need an SPWeb
instance representing the Meeting Workspace site to get a reference to the SPMeeting
class via the GetMeetingInformation
method.
The LinkWithEvent
method takes the following arguments:
eventWeb
—The SPWeb
instance of the website containing the calendar that will have an item linked to the meetingstrEventListId
—The list ID of the calendar list within the event webeventItemId
—The item ID that will be linked to the meetingstrEventWorkspaceLinkField
—The field on the Meeting Workspace site with which the event will be linkedstrEventWorkspaceLinkURLField
—The URL of the field on the Meeting Workspace site with which the event will be associatedAfter calling this method, you will see a link from the calendar item to the Meeting Workspace. In addition, there will be a Back to Calendar (or whatever the list name is called) link in the header display for the Meeting Workspace.
Meetings and Meeting Workspaces are a powerful feature of SharePoint and can add a tremendous amount of productivity to any enterprise or custom application. This chapter covered how to use the object model to access and manipulate Meeting Workspaces and meetings. After having read this chapter, you should feel comfortable using the meeting and Meeting Workspace components of SharePoint within your custom applications and within SharePoint itself.