Chapter 9
Working with Meetings

IN THIS CHAPTER

• Managing Meeting Workspace Sites
• Accessing Existing Meetings
• Managing Meetings
• Working with Events

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”).

Managing Meeting Workspace Sites

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.

Creating a Meeting Workspace

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

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.

Accessing Existing Meetings

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.

Caution

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

Managing Meetings

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 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 Meetings

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 entry
• sequence—A sequence number used for organizing multiple updates
• dateStamp—A time stamp indicating the date and time that the change was made
• title—The title (or subject) of the meeting
• location—The location of the meeting
• dateStart—The date/time the meeting starts
• dateEnd—The date/time the meeting ends
• nonGregorian—A Boolean value indicating whether the time stamps are in a non-Gregorian calendar

After 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 Meetings

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 meeting
• recurrenceID—The recurrence ID of the meeting to be canceled
• sequence—A number used for sequencing multiple updates
• dateStamp—A date stamp used for when the deletion occurred
• cancelMeeting—A Boolean value indicating whether the meeting should be deleted

Even 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.

Handling Attendee Responses

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 question
• uid—The persistent GUID for the calendar component
• recurrenceId—The recurrence ID for the meeting
• sequence—A number used to arrange multiple updates
• dateStamp—The date and time stamp for the modification of the calendar component
• response—The response from the user (Accepted, Tentative, or Declined)

Working with Events

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 meeting
• strEventListId—The list ID of the calendar list within the event web
• eventItemId—The item ID that will be linked to the meeting
• strEventWorkspaceLinkField—The field on the Meeting Workspace site with which the event will be linked
• strEventWorkspaceLinkURLField—The URL of the field on the Meeting Workspace site with which the event will be associated

After 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.

Summary

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.