Updating appointments and meetings by using the EWS Managed API 2.0
Last modified: October 13, 2012
Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010
Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.
You can use the Microsoft Exchange Web Services (EWS) Managed API to update appointments and meeting requests.
Note
This topic covers the basic scenarios for updating appointments and meeting requests. Some advanced scenarios might require that you update the time zone of appointments and meeting requests. For information about working with time zones in the EWS Managed API, see Time zones in the EWS Managed API 2.0 and Working with time zones by using the EWS Managed API 2.0.
To update an appointment or meeting request
Bind to an existing appointment or meeting request by using its unique identifier. The following code shows how to bind to an existing appointment or meeting request and provide it with connection configuration information by using an ExchangeService object named service. The ItemId has been shortened to preserve readability.
Appointment appointment = Appointment.Bind(service, new ItemId("AAMkA="));Update properties on the appointment or meeting request. The following code shows how to update the subject, the start time, and the end time on an appointment or meeting request.
appointment.Subject = "Urgent Status Update"; appointment.Start = new DateTime(2009, 3, 5, 9, 0, 0); appointment.End = appointment.Start.AddHours(1);A meeting request is just an appointment that has attendees. You can convert an appointment into a meeting request by adding required attendees, optional attendees, or resources to the appointment, as shown in the following example.
appointment.RequiredAttendees.Add("user1@contoso.com"); appointment.OptionalAttendees.Add("user2@contoso.com"); appointment.Resources.Add("resource1@contoso.com");Save the updated appointment or meeting request. The following code shows how to save an updated appointment or meeting request.
appointment.Update(ConflictResolutionMode.AlwaysOverwrite);The following table lists methods that you can use to save or to save and send updated appointments or meeting requests.
Method name
Description
Update(ConflictResolutionMode.AlwaysOverwrite)
Use to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode.AutoResolve)
Use to apply local property changes only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.NeverOverwrite)
Use to discard local property changes if server-side property changes are more recent than local property changes.
Update(ConflictResolutionMode.AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendOnlyToAll)
Use to send the updated meeting invitation to all attendees, without saving a copy, and to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode. AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendOnlyToChanged)
Use to send the updated meeting invitation only to attendees that have been added or modified, without saving a copy, and to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode. AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendToAllAndSaveCopy)
Use to send the updated meeting invitation to all attendees, to save a copy of the updated meeting request in the Sent Items folder, and to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode.AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendToChangedAndSaveCopy)
Use to send the updated meeting invitation only to attendees that have been added or modified, to save a copy of the updated meeting request in the Sent Items folder, and to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode.AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendToNone)
Use to save the updated meeting request to a default folder without sending updated meeting requests to attendees, and to always overwrite server-side property changes with local property changes.
Update(ConflictResolutionMode.AutoResolve, SendInvitationsOrCancellationsMode.SendOnlyToAll)
Use to send the updated meeting invitation to all attendees, without saving a copy, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.AutoResolve, SendInvitationsOrCancellationsMode.SendOnlyToChanged)
Use to send the updated meeting invitation to attendees that have been added or modified, without saving a copy, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.AutoResolve, SendInvitationsOrCancellationsMode.SendToAllAndSaveCopy)
Use to send the updated meeting invitation to all attendees, and to save a copy of the updated meeting request in the Sent Items folder, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.AutoResolve, SendInvitationsOrCancellationsMode.SendToChangedAndSaveCopy)
Use to send the updated meeting invitation to attendees that have been added or modified, and to save a copy of the updated meeting request in the Sent Items folder, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.AutoResolve, SendInvitationsOrCancellationsMode.SendToNone)
Use to save the updated meeting request to a default folder, without sending updated meeting requests to attendees, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.NeverOverwrite, SendInvitationsOrCancellationsMode.SendOnlyToAll)
Use to send the updated meeting invitation to all attendees, without saving a copy, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.NeverOverwrite, SendInvitationsOrCancellationsMode.SendOnlyToChanged)
Use to send the updated meeting invitation to attendees that have been added or modified, without saving a copy, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.NeverOverwrite, SendInvitationsOrCancellationsMode.SendToAllAndSaveCopy)
Use to send the updated meeting invitation to all attendees and to save a copy of the updated meeting request in the Sent Items folder, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode.NeverOverwrite, SendInvitationsOrCancellationsMode.SendToChangedAndSaveCopy)
Use to send the updated meeting invitation to attendees that have been added or modified and to save a copy of the updated meeting request in the Sent Items folder, only if server-side property changes are less recent than local property changes.
Update(ConflictResolutionMode. NeverOverwrite, SendInvitationsOrCancellationsMode.SendToNone)
Use to save the updated meeting request to a default folder, without sending updated meeting requests to attendees, only if server-side property changes are more recent than local property changes.
Note
If the meeting organizer updates a meeting, changes to the meeting will be reflected on his or her calendar and an updated meeting request will be sent to attendees as specified by the Update method that is used to update the meeting. If a non-organizer (attendee) updates a meeting, changes to the meeting will only be reflected on that user’s calendar and those changes will be lost if the meeting organizer subsequently sends an updated meeting request.
Example
The following code example shows how to update the subject, the location, the start time, and the end time of a meeting request, and add a user2@contoso.com as a new required attendee to the meeting request (user1@contoso.com was previously the only attendee). The updated meeting request is sent to all attendees and a copy is saved in the organizer's Sent Items folder. This example assumes that service is a valid ExchangeService binding. The ItemId has been shortened to preserve readability.
// Bind to an existing meeting request by using its unique identifier.
Appointment appointment = Appointment.Bind(service, new ItemId("AAMkA ="));
// Update properties on the meeting request.
appointment.Subject = "Status Meeting – Rescheduled/Moved";
appointment.Location = "Conf Room 34";
appointment.Start = new DateTime(2009, 3, 5, 9, 0, 0);
appointment.End = appointment.Start.AddHours(1);
// Add a new required attendee to the meeting request.
appointment.RequiredAttendees.Add("user2@contoso.com");
// Save the updated meeting request and send the updated meeting request to all attendees.
appointment.Update(ConflictResolutionMode.AlwaysOverwrite, SendInvitationsOrCancellationsMode.SendToAllAndSaveCopy);
The following example shows the XML that is sent by using the Update method. The ItemId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010" />
</soap:Header>
<soap:Body>
<m:UpdateItem ConflictResolution="AlwaysOverwrite" SendMeetingInvitationsOrCancellations="SendToAllAndSaveCopy">
<m:ItemChanges>
<t:ItemChange>
<t:ItemId Id="AAMkA=" ChangeKey="DwAAA" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="item:Subject" />
<t:CalendarItem>
<t:Subject>Status Meeting - Rescheduled/Moved</t:Subject>
</t:CalendarItem>
</t:SetItemField>
<t:SetItemField>
<t:FieldURI FieldURI="calendar:Location" />
<t:CalendarItem>
<t:Location>Conf Room 34</t:Location>
</t:CalendarItem>
</t:SetItemField>
<t:SetItemField>
<t:FieldURI FieldURI="calendar:Start" />
<t:CalendarItem>
<t:Start>2009-03-05T17:00:00Z</t:Start>
</t:CalendarItem>
</t:SetItemField>
<t:SetItemField>
<t:FieldURI FieldURI="calendar:End" />
<t:CalendarItem>
<t:End>2009-03-05T18:00:00Z</t:End>
</t:CalendarItem>
</t:SetItemField>
<t:SetItemField>
<t:FieldURI FieldURI="calendar:RequiredAttendees" />
<t:CalendarItem>
<t:RequiredAttendees>
<t:Attendee>
<t:Mailbox>
<t:Name>user1@contoso.com</t:Name>
<t:EmailAddress>user1@contoso.com</t:EmailAddress>
<t:RoutingType>SMTP</t:RoutingType>
</t:Mailbox>
</t:Attendee>
<t:Attendee>
<t:Mailbox>
<t:EmailAddress>user2@contoso.com</t:EmailAddress>
</t:Mailbox>
</t:Attendee>
</t:RequiredAttendees>
</t:CalendarItem>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
</m:ItemChanges>
</m:UpdateItem>
</soap:Body>
</soap:Envelope>
Note
Although user2@contoso.com is the only newly added attendee, user1@contoso.com also appears in the RequiredAttendees collection in the XML request. This is because user1@contoso.com was the attendee on the original meeting request. Original attendees will always appear in the UpdateItem XML request unless they are explicitly removed from the meeting request as part of the update.
The following example shows the XML that is returned by using the Update method. The ItemId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<t:ServerVersionInfo MajorVersion="8" MinorVersion="1" MajorBuildNumber="344" MinorBuildNumber="0" Version="Exchange2007_SP1" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<m:UpdateItemResponse xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:UpdateItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Items>
<t:CalendarItem>
<t:ItemId Id="AAMkA=" ChangeKey="DwAAA" />
</t:CalendarItem>
</m:Items>
<m:ConflictResults>
<t:Count>0</t:Count>
</m:ConflictResults>
</m:UpdateItemResponseMessage>
</m:ResponseMessages>
</m:UpdateItemResponse>
</soap:Body>
</soap:Envelope>
Compiling the code
For information about compiling this code, see Getting started with the EWS Managed API 2.0.
Robust programming
Write appropriate error handling code for common search errors.
Review the client request XML that is sent to the Exchange server.
Review the server response XML that is sent from the Exchange server.
Set the service binding as shown in Setting the Exchange service URL by using the EWS Managed API 2.0. Do not hard code URLs because if mailboxes move, they might be serviced by a different Client Access server. If the client cannot connect to the service, retry setting the binding by using the AutodiscoverUrl(String) method.
Set the target Exchange Web Services schema version by setting the requestedServerVersion parameter of the ExchangeService constructor. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.
Security
Use HTTP with SSL for all communication between client and server.
Always validate the server certificate that is used for establishing the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.
Do not include user names and passwords in trace files.
Verify that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.