This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers.

Autodiscover is a process by which a Microsoft Exchange Server client can determine the URL of the Microsoft Exchange ActiveSync endpoint by using only a mailbox SMTP address and user credentials. During the Autodiscover process, the client uses the mailbox SMTP address to determine the Autodiscover service endpoint URL and sends a request to the Autodiscover service that includes the mailbox SMTP address. A successful call to the Autodiscover service results in a response that contains the Exchange ActiveSync endpoint URL that the client will use to access the mailbox. This not only simplifies initial client configuration for the end user, but also gives the client a mechanism by which to recover from errors and respond to changes in the Microsoft Exchange environment automatically.

In this blog post, I describe the Autodiscover process from the perspective of an Exchange ActiveSync client developer, including the following:

• The process of finding and calling the Autodiscover service.
• The specific requests and responses that are used during the Autodiscover process.
• When clients should call Autodiscover. 

Finding and calling the Autodiscover service

A client needs only an email address and user credentials to successfully find and call the Autodiscover service. The client should parse the email address to get the domain information, which is everything to the right of the “@” character.

In the following procedure, woodgrovebank.com is the domain from the email address chris@woodgrovebank.com. If the domain information includes a subdomain, such as sales.woodgrovebank.com, the client should use the sales.woodgrovebank.com subdomain first and then, if the procedure fails, try again using the domain woodgrovebank.com. The client uses this domain to construct the Autodiscover service endpoint URLs.

The following procedure describes the Autodiscover process for Exchange ActiveSync clients.

1. The client sends an Autodiscover request to https://woodgrovebank.com/autodiscover/autodiscover.xml and does one of the following:

• If the Autodiscover attempt succeeds, the client proceeds to step 5.
• If the Autodiscover attempt fails, the client proceeds to step 2.

2. The client sends an Autodiscover request to https://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml, and does one of the following:

• If the Autodiscover attempt succeeds, the client proceeds to step 5.
• If the Autodiscover attempt fails, the client proceeds to step 3.

3. The client sends an unauthenticated GET method request to http://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml. (Note that this is a non-SSL endpoint).The client does one of the following:

• If the GET request returns a 302 redirect response, it gets the redirection URL from the Location HTTP header, and validates it as described in the section “Redirect responses”. The client then does one of the following:
  • If the redirection URL is valid, the client tries the URL, and does one of the following:
    • If the attempt succeeds, the client proceeds to step 5.
    • If the attempt fails, the client proceeds to step 4.
  • If the redirection URL is not valid, the client proceeds to step 4.
• If the GET request does not return a 302 redirect response, the client proceeds to step 4.

4. The client performs a DNS query for an SRV record for _autodiscover._tcp.woodgrovebank.com. The query might return multiple records. The client selects only records that point to an SSL endpoint and that have the highest priority and weight. One of the following occurs:

• If no such records are returned, the client proceeds to step 6.
• If records are returned, the application randomly chooses a record in the list, and validates the endpoint that it points to by following the process described in the section “Redirect Response”. The client then does one of the following:
  • If the redirection URL is valid, it tries the URL, and one of the following occurs:
    • If the attempt succeeds, the client proceeds to step 5.
    • If the attempt fails, the client proceeds to step 6.
  • If the redirection URL is not valid, the client proceeds to step 6.

5. When a valid Autodiscover request succeeds, the following takes place:

• If the server responds with an HTTP 302 redirect, the client validates the redirection URL according to the process defined in the section “Redirect responses”, and does one of the following:
  • If the redirection URL is valid, the client tries the URL, and does one of the following:
    • If the attempt succeeds, the client resumes step 5 from the beginning.
    • If the attempt fails, the client proceeds to step 6.
  • If the redirection URL is not valid, the client proceeds to step 6.
• If the server responds with a valid Autodiscover response, the client does one of the following:
  • If the value of the Action element is "Redirect", it gets the redirection email address from the Redirect element, and returns to step 1 using this new email address.
  • If the value of the Action element is "Settings", the client has successfully received the requested configuration settings for the specified user. The client does not need to proceed to step 6.

6. If the client cannot contact the Autodiscover service, the client should ask the user for the Exchange server name and use it to construct an Exchange ActiveSync URL, similar to the following: http://servername/Microsoft-Server-ActiveSync. The client should try to use this URL for future requests.

Autodiscover requests and responses

The preceding procedure mentions Autodiscover requests and responses. Microsoft Exchange publishes a "plain old XML" (POX) endpoint for the Autodiscover service. (For more information, see Autodiscover Reference (POX) on MSDN.) These responses can be quite large. Because Exchange ActiveSync is a mobile protocol, a more concise Autodiscover schema called "mobilesync" is defined specifically for Exchange ActiveSync clients.

The following is an example of an Exchange ActiveSync Autodiscover request.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/requestschema/2006">

     <Request>

            <EMailAddress>chris@woodgrovebank.com</EMailAddress>

            <AcceptableResponseSchema>

             http://schemas.microsoft.com/exchange/autodiscover/mobilesync/

             responseschema/2006

            </AcceptableResponseSchema>

     </Request>

</Autodiscover>

Successful response

A successful Exchange ActiveSync response contains URL settings for Exchange ActiveSync. Settings in the Exchange ActiveSync Autodiscover response can contain two server sections: one with the type “MobileSync”, which is the Exchange ActiveSync endpoint URL, and one with the type “CertEnroll”, which is used to obtain a client certificate for SSL negotiation. (For more information about this response, see [MS-ASCMD] ActiveSync Command Reference Protocol Specification section 4.2.4.)

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

            <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

            <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

            <autodiscover:Settings>

                <autodiscover:Server>

                    <autodiscover:Type>MobileSync</autodiscover:Type>

                    <autodiscover:Url>

                        https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

                    </autodiscover:Url>

                    <autodiscover:Name>

                 https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

             </autodiscover:Name>

                </autodiscover:Server>

                <autodiscover:Server>

                    <autodiscover:Type>CertEnroll</autodiscover:Type>

                    <autodiscover:Url>https://cert.woodgrovebank.com/CertEnroll</autodiscover:Url>

                    <autodiscover:Name />

                   <autodiscover:ServerData>CertEnrollTemplate</autodiscover:ServerData>

                </autodiscover:Server>

            </autodiscover:Settings>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Redirect responses

Redirection to a different URL can be in the form of an HTTP 302 response. In the following example, an Autodiscover request is being redirected to a different URL. The client should try to send an Autodiscover request to the URL in the response. If the request sent to the redirect location fails, the client should stop and inform the user that Autodiscover has failed.

HTTP/1.1 302 Found

Location: https://autodiscover.us.woodgrovebank .com/autodiscover/autodiscover.xml

Redirects can also come from within the details of an Autodiscover response, as shown in the following example. In this case, the client is being directed to start the Autodiscover process over with a new email address.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

           <autodiscover:Redirect>chris@loandept.woodgrovebank.com </autodiscover:Redirect>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

The client should start from step 1 in the procedure with the email address from the redirect response, chris@loandept.woodgrovebank.com.

Error responses

Errors can come in the form of HTTP 403 or 404 error responses, or in the Error section of an Autodiscover response. The client should consider these errors permanent and move on to the next step in the Autodiscover URL location process. An HTTP 401 response indicates that authentication failed. The client can choose to present the user an opportunity to enter credentials again.

Error responses from Autodiscover can indicate a problem with the request the client sent or a problem on the server side. In the following example, there was a problem contacting the directory service on the server side. Because this error is on the server side, the client should continue on to the next step in the Autodiscover URL location process. The client can also choose to retry this request, as the error might be transient.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

       </autodiscover:User>

       <autodiscover:Action>

           <autodiscover:Error>

               <Status>1</Status>

               <Message>The directory service could not be reached</Message>

               <DebugData>MailUser</DebugData>

           </autodiscover:Error>

       </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Error responses can also indicate problems with the Autodiscover request sent by the client. The following example shows an error code 600 response, which indicates an invalid request. A 601 response would indicate that the requested schema version is not supported by the server.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

   <autodiscover:Response>

      <autodiscover:Error Time="16:56:32.6164027" Id="1054084152">

          <autodiscover:ErrorCode>600</autodiscover:ErrorCode>

          <autodiscover:Message>Invalid Request</autodiscover:Message>

          <autodiscover:DebugData />

      </autodiscover:Error>

   </autodiscover:Response>

</Autodiscover>

When should the client perform Autodiscover?

Because Autodiscover requires only an email address and password, using Autodiscover can make the initial configuration of an email account easy for a user. After performing Autodiscover in an initial account configuration, the device should cache the Exchange ActiveSync URL that is returned in the successful response.

Autodiscover is equally important after the initial configuration of the email client as a method for recovering from transient errors. If the client receives HTTP 401, 403, 404, or 500 responses, timeouts, or any response that indicates a DNS lookup failure, it should run Autodiscover to see if it gets a new URL. For more information, see [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.5.2.1.

The client can also receive an HTTP 451 redirect response, as specified in [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.4.2.2. This response indicates that the client sent a request to a URL that is no longer the optimum endpoint URL for the mailbox the client is trying to access. This can occur when a mailbox moves from one Active Directory site to another. For more information, see Understanding Proxying and Redirection on Microsoft TechNet. The client will continue to receive the 451 error until it sends requests to the new endpoint.

Typically, the 451 response contains an X-MS-Location header that indicates the new Exchange ActiveSync URL for the client to use. When this header is present, the client does not need to use Autodiscover to get the new URL; it can use the URL from the header. However, the X-MS-Location header is optional. If the header is not present, the client should perform Autodiscover to get a new Exchange ActiveSync URL. The following example shows a 451 error response.

HTTP/1.1 451

Date: Tue, 08 Dec 2009 19:43:24 GMT

Server: Microsoft-IIS/7.0

X-Powered-By: ASP.NET

X-AspNet-Version: 2.0.50727

X-MS-Location: https://mail.woodgrovebank .com/Microsoft-Server-ActiveSync

Cache-Control: private

Content-Length: 0

A 302 redirect response is expected and should be followed only during the Autodiscover process. If the client receives a 302 redirect in response to a command, such as FolderSync, it should not follow the redirect. Instead, the client should go through the Autodiscover process again to get a new URL.

Related Resources

[MS-ASCMD]: ActiveSync Command Reference Protocol Specification

[MS-ASHTTP]: ActiveSync HTTP Protocol Specification

Understanding Proxying and Redirection

Understanding the Autodiscover Service

Understanding Exchange ActiveSync Autodiscover

Autodiscover and Exchange 2007

Post written by: Matt Stehle, Microsoft Corporation

Network load balancing for Microsoft Exchange Online as part of Microsoft Office 365 ensures that tenant client access loads are properly balanced. Network load balancing also has implications for Client Access server affinity. Some stateful client features require Client Access server affinity. This is because some state information is cached on Client Access servers. Both Exchange Web Services (EWS) and MAPI clients include ways to maintain Client Access server affinity through the network load balancers.

Client Access server affinity and Exchange Web Services

Client Access server affinity is important for EWS. Using the Client Access server that services a mailbox improves both performance and function. Using a Client Access server that does not service the particular mailbox to handle a request can negatively affect performance, and in some cases, the request might fail. Requests for features such as event notification subscriptions require stateful information, and state information is maintained on the Client Access server that services the mailbox. Client Access server affinity is required to maintain state information about which notifications have been delivered to the client. For example, if the notification request is not sent to the correct Client Access server, the server will respond with the ErrorSubscriptionNotFound error.

The key to maintaining Client Access server affinity for EWS is the exchangecookiecookie. The exchangecookie cookie associates a client with a specific Client Access server — specifically, the Client Access server that services the target mailbox. The network load balancer uses the exchangecookiecookie to maintain Client Access server affinity for a client. The first response that the client receives from the server will contain the exchangecookiecookie. For all subsequent EWS client requests for that mailbox, the exchangecookie cookie must persist, in order to maintain Client Access server affinity. The client should preserve the cookie after each response, because in some cases the cookie might change mid-session. The exchangecookie cookie should persist for use in all future requests.

Clients that use the EWS Managed API 1.1 and the EWS Java API 1.1 do not have to manage the exchangecookiecookie as this is done automatically. If you create a custom client, make sure that the exchangecookie cookie persists for each mailbox you are accessing.

Client Access server affinity and MAPI

MAPI Client Access server affinity is maintained through the network load balancer by the OutlookSession session. You can maintain Client Access server affinity for a client by using a single OutlookSession session for the client. The client cannot rely on state information maintained on the Client Access server if subsequent sessions are opened since different sessions are not necessarily handled by the same Client Access server that handled a previous session.

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers. 

In this post, we are using Exchange ActiveSync protocol version 14.1. Where applicable, we note differences between protocol versions.

Meeting requests are important for information workers who use Microsoft Exchange. Meeting requests inform attendees of a meeting, automatically book meeting time on the organizer's and attendees' calendars, provide reminders for meetings, and enable the booking of conference rooms. This post provides information for developers about working with meeting requests, including the following topics:

• How meeting requests are created by using Exchange ActiveSync.
• How invitees' Exchange ActiveSync clients interpret meeting requests.

The following figure shows an overview of the meeting request process and the two key scenarios involved. In this example, Exchange ActiveSync user Alice requests a meeting with Bob from her Exchange ActiveSync client. Bob sees the meeting request on his Exchange ActiveSync device.

Figure 1:   Meeting request process

Scenario 1: Organizer creates meeting request by using an Exchange ActiveSync client

A meeting starts out as a meeting request. The meeting organizer requests that attendees agree to participate in the meeting at a specified date, time, and location. Meeting requests are composed of the following two elements:

1.      A calendar item that reflects the proposed meeting on the organizer's and invitees' calendars.

2.      An invitation email sent by the organizer to invitees to notify them of the proposed meeting and solicit their responses.

In order for a user to create meeting requests, an Exchange ActiveSync client must do the following:

• Add a new calendar event to the organizer's calendar that includes the meeting details.

• Send an email to prospective attendees that includes the meeting details and response options.

After the Exchange ActiveSync client sends an email message that includes the meeting invitation, the Exchange server sends the invitation and saves a copy in the Sent Items folder. The following figure shows the client requests and server responses when a user, Alice, creates a meeting request from her Exchange ActiveSync client. The syncing of the Sent Items folder is optional.

Figure 2:   Sending a meeting request from an Exchange ActiveSync client

Adding meeting details to the organizer's calendar

Request to create the calendar item

When a user organizes a new meeting on the Exchange ActiveSync client, the client must create a meeting item on the organizer's calendar. The client adds the new calendar item to the Calendar collection. The calendar item contains all the meeting details, including meeting attendees. The following example shows an Exchange ActiveSync Sync command XML request that adds a meeting to Alice's calendar when she organizes a meeting and invites Bob.

For a list of and information about the Calendar schema elements for Exchange ActiveSync, see [MS-ASCAL]:  ActiveSync Calendar Class Protocol Specification section 2.2.2.

In the meeting request, the Exchange ActiveSync client must specify the start time and end time of the proposed event; this information is included in the StartTime and EndTime elements. Both dates have to be valid values of the dateTime type, as described in [MS-ASDTYPE]: ActiveSync Data Types section 2.3. All dates must be specified in Coordinated Universal Time (UTC), without any punctuation separators. Optionally, the client can use the DtStamp element to specify when the calendar item was created.

The client should specify the time zone in the request. If the time zone is not specified, the Exchange server uses its current  time zone for the meeting. For more information about the format of the time zone, see [MS-ASDTYPE]section 2.6.4.

Optionally, the client can mark the organizer's calendar by specifying the BusyStatus element. The following are the possible values for the BusyStatus element:

·        0 – Free

·        1 – Tentative

·        2 – Busy

·        3 – Out of office

If the organizer did not explicitly specify his or her attendance status, the client should use a value of 2 for the BusyStatus element to mark the meeting status as busy. If the client does not provide this value, the server uses a busy status by default.

The client should provide a MeetingStatus element for meetings. When the client saves a meeting to the organizer's calendar, it should set the value of this element to 1, which indicates that the item is a meeting.

A meeting must include the Attendees element, which contains a collection of Attendee elements. Each Attendee element must include at least one Email and one Name element; these contain the name and email address of the attendee. Optionally, the Attendee element can include values for the AttendeeStatus and AttendeeType elements. When the meeting is created, the AttendeeStatus element contains a value of 0. This value changes when attendees respond to the meeting request. If present, the AttendeeType element must be set to one of the following values:

·        1 – Required

·        2 – Optional

·        3 – Resource

Server response to the request to create the calendar item

The Exchange server sends a response to the Exchange ActiveSync client's request. The response indicates the status of the Calendar Sync command operation as well as the status of the individual meeting request. If the item was added correctly (as indicated by a Status element value of 1 in the response for both the item and the collection), the server issues a ServerId element value for the item in lieu of the temporary ClientId element value that the client assigned to it, as shown in the following example.

The client has to associate the newly issued ServerId value with this calendar item. For more information about status response values, see [MS-ASCMD]: ActiveSync Command Reference Protocol Specification.

Informing attendees of the meeting details by email notification

The email notification must make it clear to the recipients that its purpose is to inform them of the meeting request. It can also optionally solicit invitee responses to the request, and automatically block the meeting time on prospective attendees' calendars.

Client request to send the meeting email message

Exchange ActiveSync clients use the SendMail command to send MIME-formatted email messages to the server, including calendaring information structured according to a known calendaring format.

The iCalendar format is the most common calendaring format; this format is supported by a variety of clients. The following example shows the Exchange ActiveSync SendMail request that Alice's Exchange ActiveSync client sends.

The email message contains multiple parts. The message may contain a plain text part, which includes the body text of the meeting request. Several different calendar request formats are available for meeting request messages. Microsoft Exchange supports the iCalendar and TNEF formats. Each of these formats are included in a separate MIME part in the meeting request message. (For more information about MIME, see RFC 2045, RFC 2046, and RFC 2047.) Most clients use the iCalendar format for the meeting request, encoded in base64. Meeting requests have a content type of text/calendar with the method parameter set to “REQUEST”. The following section provides more detail about the iCalendar format.

iCalendar format

The iCalendar format is a file format (extension .ics, .ical) that represents calendaring information such as meeting requests, meeting responses, and free/busy information. For more information about this format, see RFC 2445,RFC 5546, and [MS-OXCICAL]: iCalendar to Appointment Object Conversion Protocol Specification.

This standard enables users of different calendaring systems (including clients and servers) to exchange calendaring information. iCalendar information is transported across the Internet in MIME format. The MIME body that contains the iCalendar information has a content type of text/calendar. The following example shows a typical iCalendar meeting request.

Server response to the client request to send the meeting email message

The response to SendMail command has no XML body (Content-Length = 0) if the SendMail command finishes successfully, as shown in the following example.

The server first responds to the SendMail request from the organizer's Exchange ActiveSync client, and then tries to send the message to the attendees. For this reason, a positive response to the SendMail request does not guarantee that the message was sent out successfully. The Exchange ActiveSync client can still receive a non-delivery report notification if the mail recipients are not found. For more information about the SendMail status values, see [MS-ASCMD] section 2.2.3.152.13. Non-delivery report responses should be handled in the same way that email responses are handled.

Before the Exchange server sends the email message, it interprets the iCalendar information and structures the message to the attendees to reflect that it is a meeting request.

Saving the meeting notification in Sent Items

After the Exchange ActiveSync client submits the meeting request email to the server, the Exchange server sends the email message to all the invited attendees. In addition, the Exchange server parses the iCalendar information that is embedded in the email. This way, it adds the email message to the Sent Items folder as the appropriate type; that is, a meeting request. The next time the Exchange ActiveSync client syncs the Sent Items folder, the meeting request email message will be added to the Sent Items folder on the client.

Client request to sync the Sent Items folder

The client syncs the Sent Items folder as shown in the following example.

Server response to the request to sync the Sent Items folder

The server adds a new item with the MessageClass element set to IPM.Schedule.Meeting.Request, as shown in the following example. This item contains all the meeting details.

The meeting request email that is sent to the attendees is of type IPM.Schedule.MeetingRequest and contains a MeetingRequest container. (For more information about the MeetingRequest container, see [MS-ASEMAIL]: ActiveSync E-Mail Class Protocol Specification section 2.2.2.14). This container describes the properties of the meeting. In addition, it now contains the GlobalObjId element value that was assigned to the meeting item by the server.

The GlobalObjId element value identifies the meeting request and allows the client to determine whether it corresponds to an existing object in the Calendar. For more information about the GlobalObjId element, see [MS-ASEMAIL] section 2.2.2.14.15. The UID element value assigned to the calendar item by the Exchange ActiveSync client is included in the GlobalObjId element value that the server returns. The GlobalObjId element value does not change when the meeting is updated. This enables the client to identify which meeting a particular notification corresponds to.

This meeting request message that is added to the organizer's Sent Items folder should not expose any response options to the user because it is in the organizer's mailbox.

Scenario 2: A meeting invitee receives a meeting request on the Exchange ActiveSync client

When an organizer sends a meeting request, the invitees' Exchange ActiveSync client must be able to receive the request, interpret it, and present it to the invitee as a meeting invitation. The meeting request should appear in the invitee's Inbox, and a placeholder Calendar item for the meeting should appear on the invitee's Calendar. The invitee should be able to accept, tentatively accept, or decline the meeting request, either from the meeting invitation or from the Calendar placeholder item, and send his or her response the meeting organizer.

The following figure shows the operations involved in sending a meeting request to an Exchange ActiveSync client. In this example, Bob is the meeting invitee.

Figure 3:   Sending a meeting request to an Exchange ActiveSync client

Adding the meeting request to the invitee's Inbox

When the meeting invitation first arrives in the invitee's mailbox, it is in the form of a meeting request in the Inbox.

Receiving the meeting request

The Exchange ActiveSync client receives the meeting request upon issuing a Sync command request for the invitee's Inbox. We recommend that Exchange ActiveSync clients request body items in HTML format by setting the BodyPreference element to 2. HTML provides rich content formatting that the client can then render. The meeting request is shown in the following example.

Server response to the Sync command request

The organizer's Exchange server converts the item's iCalendar information and parses it into a message class of IPM.Schedule.Meeting.Request, which is then synced to the invitee's Inbox, as shown in the following example.

The MeetingRequest element is an optional container element. The MeetingRequest element is included when the message is a meeting request and the Exchange ActiveSync client's user is an attendee. The MeetingRequest element is not included in the message content of calendar items in the Calendar folder or in regular email messages. If a message contains the MeetingRequest element, the client can respond to the meeting request by using the MeetingResponse command. For more information about this command, see [MS-ASCMD] section2.2.2.9.

The GlobalObjId element is a required child element of the MeetingRequest element. GlobalObjId is defined as an element in the Email namespace. Clients that need to determine whether the GlobalObjId element for a meeting request corresponds to an existing Calendar object in the Calendar folder have to convert the GlobalObjId element value to a UID element value to make the comparison. For information about how this conversion is done, see [MS-ASEMAIL] section 2.2.2.14.15.

MeetingMessageType is a new element that was added in version 14.1 of the Exchange ActiveSync protocol. The MeetingMessageType element further defines the type of the meeting request. For information about this element, see [MS-ASEMAIL] section 2.2.2.14.17.

Client request to sync the Calendar folder

The invitee's (Bob's) Exchange ActiveSync client issues a Sync request for the Calendar folder, similar to the one shown in the following example.

Tentative meeting added to invitee's calendar

In Microsoft Exchange Server 2007 (which corresponds to Exchange ActiveSync protocol version 12.0) and later versions, the server parses the meeting request received in the invitee's Inbox and adds a tentative meeting to the invitee's calendar to mark the time of the proposed meeting. This tentative meeting is synced to the client.

Server response to the request to Sync the Calendar folder

Based on the meeting request that the Exchange server received, the server created a meeting item in Bob's Calendar folder with the UID element value previously specified by the organizer. Syncing the Calendar collection adds the meeting to the invitee's calendar.

The calendar item contains a UID element value that the organizer's client had set, which correlates to the meeting request in the Inbox via the GlobalObjIdelement.

The meeting that is added to the invitee's Calendar collection contains all the properties of the calendar item on the organizer's Calendar, as well as the following additional elements:

·        OrganizerName

·        OrganizerEmail

·        ResponseRequested

·        MeetingStatus

·        ResponseType

The value of the ResponseRequested element comes from the PARTSTATparameter value of "NEEDS-ACTION" in the original iCalendar meeting request.

When the invitee receives the meeting request, the MeetingStatus element is set to 3, which indicates that the meeting was received, and the ResponseType element is set to 5, to indicate that the invitee has not yet responded to the meeting request. After the invitee responds, the server updates these values to reflect the new status. Stay tuned for our next blog post, "Working with meeting responses in Exchange ActiveSync", for more information about meeting responses.

Summary

Creating meeting requests and interpreting them from an Exchange ActiveSync client is critical to ensuring a successful calendaring experience for Exchange ActiveSync client users. It is important to use the correct iCalendar format to create meeting requests and to remember not to try to process incoming iCalendar requests on the client, but instead to allow the Exchange server to process the requests.  

Related Resources

[MS-ASEMAIL]: ActiveSync E-Mail Class Protocol Specification

[MS-ASCAL]: ActiveSync Calendar Class Protocol Specification

[MS-ASCMD]: ActiveSync Email Command Reference Protocol Specification

[MS-ASDTYPE]: ActiveSync Data Types

[MS-OXGLOS]: Exchange Server Protocols Master Glossary

[MS-OXCICAL]: iCalendar to Appointment Object Conversion Protocol Specification

RFC 2045, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"

RFC 2046, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"

RFC 2047, "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text"

RFC 2445, "Internet Calendaring and Scheduling Core Object Specification"

RFC 5546, "iCalendar Transport-Independent Interoperability Protocol (iTIP)"

Post authored by: Katarzyna Puchala, Microsoft Corporation

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers. This post applies to Exchange ActiveSync protocol version 14.1. Where applicable, differences between protocol versions are noted.

The ability to respond to meeting requests is an important aspect of collaboration and communication for Microsoft Exchange users. Responses to meeting requests inform meeting organizers of invitees' attendance status and automatically book the time on attendees' Calendars. This post provides information for developers about working with meeting responses, including the following topics:

• How the Exchange ActiveSync client responds to meeting requests.
• How the Exchange ActiveSync client should interpret responses to meetings organized by the client user.

For information about working with meeting requests, see the blog post Working with Meeting Requests in Exchange ActiveSync.

The following figure shows an overview of the meeting response process and the two key scenarios involved. In this example, Exchange ActiveSync user Bob has received a meeting invitation from the organizer, Alice, on his Exchange ActiveSync client. Bob responds to the meeting request using his Exchange ActiveSync device and Alice can verify his response status using her device.

Figure 1:   Meeting response process

This post does not cover adding the meeting request email message to the invitee's Inbox and a creating tentative placeholder item on the invitee's Calendar. For information about the meeting request process, see Working with Meeting Requests in Exchange ActiveSync.

Scenario 1: Invitee uses an Exchange ActiveSync client to respond to a meeting request

In our example, an invitee, Bob, finds a meeting request from Alice waiting in his Inbox, and a placeholder Calendar item tentatively marking the time of the meeting on his Calendar. Bob can choose to accept, tentatively accept, or decline the meeting and send his response to the organizer from either the meeting invitation in his Inbox or the Calendar placeholder item. Bob accepts the meeting request by using the options provided by the meeting request email displayed on his Exchange ActiveSync client. The Exchange server then deletes the meeting request from his Inbox and changes the status of the placeholder Calendar item from tentative to busy. In addition, the Exchange ActiveSync client sends a meeting acceptance notification to the organizer. A copy of this message appears in Bob's Sent Items folder.

The following figure shows the Exchange ActiveSync client meeting response process.

Figure 2:   Exchange ActiveSync client meeting response process

Responding to meeting requests involves the following steps:

1. The user, in this case Bob, accepts the meeting from his Exchange ActiveSync client by using the options exposed in the meeting request. Upon doing so, the following takes place:
   1. The server deletes the meeting request email message from his Inbox.
   2. The server deletes the tentative meeting from his Calendar and adds an accepted meeting in its place.

Note:   If Bob's Exchange server is not configured to process incoming meeting requests automatically, a tentative meeting placeholder item does not appear on his Calendar. In this case, the server does not delete any Calendar item, and the MeetingResponse command cannot be sent from the Calendar folder; it can be used on the meeting request in the Inbox only.

1. When Bob issues a Sync command on Calendar folder, the tentative meeting is deleted from the Calendar by the Exchange  server, and a new accepted meeting is added.

Note:   If Bob syncs his Deleted Items folder, a copy of the original meeting item is added to that folder. (This step is not shown in Figure 2 and is not described in this blog post.)

1. Bob's client sends an email message to the organizer that indicates his acceptance.
2. The server adds a copy of the meeting acceptance email message in Bob's Sent Items folder. If Bob syncs his Sent Items folder, a copy of the notification will appear there.

 When the ResponseRequested element is set to 1, the Exchange ActiveSync client allows the user to act on the meeting request from both the Inbox and the Calendar item.

Responding to meeting requests from the Inbox

When the client displays a meeting request message in a user's Inbox, the user has the option to accept, tentatively accept, or decline the meeting invitation. After the user selects a response, the client sends a MeetingResponse command to the server.

MeetingResponse command

The following example shows a MeetingResponse command request.

POST /Microsoft-Server-ActiveSync?Cmd=MeetingResponse&User=Bob&DeviceId=ABCDEF&DeviceType=SmartPhone HTTP/1.1

Content-Type: application/vnd.ms-sync.wbxml

MS-ASProtocolVersion: 14.1

User-Agent: ASOM

Host: mail.contoso.com

 

<?xmlversion="1.0"encoding="utf-8"?>

<MeetingResponsexmlns="MeetingResponse:">

  <Request>

    <UserResponse>1</UserResponse>

    <CollectionId>6</CollectionId>

    <RequestId>6:17</RequestId>

  </Request>

</MeetingResponse>

The RequestId element specifies the server ID of the meeting request in the Inbox collection. The UserResponse element can contain one of the values listed in the following table.

Server response to the MeetingResponse command

After the MeetingResponse command has finished, the server automatically deletes the meeting request item from the Inbox. The following example shows the server response.

HTTP/1.1 200 OK

MS-Server-ActiveSync: 14.0

 

<?xmlversion="1.0"encoding="utf-8" ?>

<MeetingResponsexmlns="MeetingResponse:">

  <Result>

    <RequestId>6:17</RequestId>

    <Status>1</Status>

    <CalendarId>2:25</CalendarId>

  </Result>

</MeetingResponse>

The RequestId element specifies the meeting request that the client is responding to. If the meeting invitation is accepted or tentatively accepted, the server adds or updates the corresponding Calendar item and returns the item's server ID in the CalendarId element of the response.

The following table lists the possible values for the Status element.

Note:   The Exchange ActiveSync client should handle the response to the MeetingResponse command in the same way that it handles the status responses to email commands.

When an invitee responds from the Inbox item, the Exchange server deletes the meeting invitation from the Inbox. The invitee can, however, change their response to the meeting request from the Calendar item with new MeetingResponse command. If the user declines the meeting, the server deletes the Calendar item, and it can no longer be used to respond to the meeting request.

The Exchange server automatically deletes the email invitation from the Inbox after the user has responded to the request. When the Exchange ActiveSync client syncs the Deleted Items folder, the deleted item is automatically added to the Deleted Items folder on the client.

Responding to meeting requests from the Calendar folder

Users respond to a meeting request from the Calendar folder in the same way that they respond to the request from the Inbox. The client uses the MeetingResponse command, but in this case, the RequestId element value indicates the Calendar item. This option is only available in Exchange ActiveSync version 14.0 and later versions. Just like when the user responds from the Inbox, the meeting request item in the Inbox is automatically deleted by the server when the user responds from the Calendar item.

Replacing the placeholder Calendar item with a new item

When the user responds to the meeting request, the original tentative Calendar item is deleted. If the user declines the meeting request, the server does not add a new item to the Calendar. If the useraccepts or tentatively accepts the meeting request, the server creates a new Calendar item with the status as indicated by the user. The following example shows the sync process for the Calendar collection, after the user has accepted the meeting request. The original meeting item is deleted, and new item with a status of Accepted is added in its place. The UID element value of the new accepted item is identical to the value of the tentative placeholder item.

HTTP/1.1 200 OK

Content-Type: application/vnd.ms-sync.wbxml

 

<?xmlversion="1.0"encoding="utf-8"?>

<Sync>

  <Collections>

    <Collection>

      <SyncKey>1598194209</SyncKey>

      <CollectionId>2</CollectionId>

      <Status>1</Status>

      <Commands>

        <Add>

          <ServerId>2:25</ServerId>

          <ApplicationData>

            <calendar:TimeZone>4AEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

              AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAsAAAABAA

              IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

              AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMAAAACAAIAAA

              AAAAAAxP///w==</calendar:TimeZone>

            <calendar:DtStamp>20110510T185139Z</calendar:DtStamp>

            <calendar:StartTime>20110510T170000Z</calendar:StartTime>

            <calendar:Subject>Quarterly Planning</calendar:Subject>

            <calendar:UID>A3561BDAAE8E4B30AC255FD3F31A3AD7000000000000000000000

              00000000000</calendar:UID>

            <calendar:OrganizerName>Alice </calendar:OrganizerName>

            <calendar:OrganizerEmail>alice@contoso.com</calendar:OrganizerEmail>

            <calendar:Attendees>

              <calendar:Attendee>

                <calendar:Email>bob@contoso.com</calendar:Email>

                <calendar:Name>Bob </calendar:Name>

                <calendar:AttendeeType>1</calendar:AttendeeType>

              </calendar:Attendee>

            </calendar:Attendees>

            <calendar:Location>Office</calendar:Location>

            <calendar:EndTime>20110510T180000Z</calendar:EndTime>

            <airsyncbase:Body>

              <airsyncbase:Type>1</airsyncbase:Type>

              <airsyncbase:EstimatedDataSize>127</airsyncbase:EstimatedDataSize>

              <airsyncbase:Truncated>1</airsyncbase:Truncated>

            </airsyncbase:Body>

            <calendar:Sensitivity>0</calendar:Sensitivity>

            <calendar:BusyStatus>2</calendar:BusyStatus>

            <calendar:AllDayEvent>0</calendar:AllDayEvent>

            <calendar:Reminder>15</calendar:Reminder>

            <calendar:MeetingStatus>3</calendar:MeetingStatus>

            <airsyncbase:NativeBodyType>3</airsyncbase:NativeBodyType>

            <calendar:ResponseRequested>1</calendar:ResponseRequested>

            <calendar:AppointmentReplyTime>20110506T165252Z</AppointmentReplyTime>

            <calendar:ResponseType>3</calendar:ResponseType>

          </ApplicationData>

        </Add>

        <Delete>

          <ServerId>2:24</ServerId>

        </Delete>

     </Commands>

    </Collection>

  </Collections>

</Sync>

The client has to sync the Calendar folder after the user accepts or tentatively accepts a meeting request in order for the new Calendar item to appear on the user's Calendar.

Deleting the Calendar item when the meeting is declined

If the user declines the meeting, the Exchange server automatically deletes the corresponding Calendar item. The client must not delete the Calendar item on behalf of the user.

When a user declines a meeting request, the response does not contain a meetingresponse:CalendarId element because the server deletes the corresponding Calendar item.

Sending response notifications

The client sends a notification to the meeting organizer if the user chooses to send a response. The client uses the SendMail command to send the notification. The client should send the email notification only after the MeetingResponse command finishes successfully; otherwise, the invitee's Calendar and the status information that the invitee reports to the organizer will be in conflict. If the ResponseRequested element is set to 0 (false) on the meeting request, the client does not expose an option to the user to send a response notification to the organizer.

The client indicates its response in the subject of the email message, as well by using an iCalendar reply command, as shown in the following example.

POST /Microsoft-Server-ActiveSync?Cmd=SendMail&User=Bob&DeviceId=ABCDEF&DeviceType=SmartPhone HTTP/1.1

Content-Type: application/vnd.ms-sync.wbxml

MS-ASProtocolVersion: 14.0

Host: mail.contoso.com

 

<?xmlversion="1.0"encoding="utf-8" ?>

<SendMailxmlns="ComposeMail:">

  <ClientId>13554</ClientId>

  <SaveInSentItems/>

  <Mime>

    Subject: Accepted: Quarterly Planning

    From: Bob@contoso.com

    Content-Type: multipart/alternative;

    boundary=NextPart

    To: Alice  <Alice@contoso.com>

 

--NextPart

Content-Type: text/plain;

                    charset=us-ascii

Sure, I will be there!

 

--NextPart

Content-Type: text/calendar;

                    charset=utf-8;

                    name=meeting.ics;

                    method=REPLY

Content-Transfer-Encoding: quoted-printable

 

BEGIN:VCALENDAR…<more iCalendar content follows>

 

</Mime>

</SendMail>

The following table lists the possible response types.

Meeting updates

If the organizer makes updates to the meeting, the Exchange ActiveSync client might receive multiple meeting notification email messages. All mail items that are related to the same meeting have the same GlobalObjId element value (for the email notification) and the same UID element value (for the Calendar item). If the Exchange ActiveSync client receives multiple updates that share the same ID, it is important for the client to enable the user to respond to the most recent item only based on the DtStamp value.

Scenario 2: Organizer uses an Exchange ActiveSync client to verify the meeting response status

After the invitees have responded to the meeting request, the organizer might want to determine the status of the responses. The organizer can view the responses in the Inbox as they arrive from individual invitees. In addition, the Exchange server automatically parses the invitee responses and updates the Calendar item accordingly. The organizer can view the response status on the Calendar item based on updates from the server to the Exchange ActiveSync client.

Syncing meeting responses in the organizer's Inbox

As invitees respond to the meeting request, the organizer's Exchange ActiveSync client runs a Sync command on the Inbox folder to discover the responses, as shown in the following example.

HTTP/1.1 200 OK

Content-Type: application/vnd.ms-sync.wbxml

 

<?xmlversion="1.0"encoding="utf-8"?>

<Sync>

  <Collections>

    <Collection>

      <SyncKey>378940377</SyncKey>

      <CollectionId>6</CollectionId>

      <Status>1</Status>

      <Commands>

        <Add>

          <ServerId>6:22</ServerId>

          <ApplicationData>

            <email:To>"Alice" &lt;alice@contoso.com&gt;</email:To>

            <email:From>"Bob" &lt;bob@contoso.com&gt;</email:From>

            <email:Subject>Accepted: Quarterly Planning</email:Subject>

            <email:DateReceived>20110506T165454Z</email:DateReceived>

            <email:DisplayTo>Alice </email:DisplayTo>

            <email:ThreadTopic>Quarterly Planning</email:ThreadTopic>

            <email:Importance>1</email:Importance>

            <email:Read>0</email:Read>

            <airsyncbase:Body>

              <airsyncbase:Type>1</airsyncbase:Type>

              <airsyncbase:EstimatedDataSize>0</airsyncbase:EstimatedDataSize>

              <airsyncbase:Truncated>1</airsyncbase:Truncated>

            </airsyncbase:Body>

            <email:MessageClass>IPM.Schedule.Meeting.Resp.Pos</email:MessageClass>

            <email:MeetingRequest>

              <email:AllDayEvent>0</email:AllDayEvent>

              <email:StartTime>20110510T17000000Z</email:StartTime>

              <email:DtStamp>20110506T165252Z </email:DtStamp>

              <email:EndTime>20110510T180000Z</email:EndTime>

              <email:InstanceType>0</email:InstanceType>

              <email:Location>Office</email:Location>

              <email:Organizer>"Bob " &lt;bob@contoso.com&gt;</email:Organizer>

              <email:Sensitivity>0</email:Sensitivity>

              <email:TimeZone>4AEAACgAVQBUAEMALQAwADgAOgAwADAAKQAgAFAAYQBjAGkAZgBpAGM

                 AIABUAGkAbQBlACAAKABVAFMAIAAmACAAQwAAAAsAAAABAAIAAAAAAAAAAAAAACgAV

                 QBUAEMALQAwADgAOgAwADAAKQAgAFAAYQBjAGkAZgBpAGMAIABUAGkAbQBlACAAKABVAF

                 MAIAAmACAAQwAAAAMAAAACAAIAAAAAAAAAxP///w==</email:TimeZone>

              <email:GlobalObjId> BAAAAIIA4AB0xbcQGoLgCAAAAAAAAAAAAAAAAAAAAAAAAAAATQAAAHZD

                 YWwtVWlkAQAAAEEzNTYxQkRBQUU4RTRCMzBBQzI1NUZEM0YzMUEzQUQ3MDAwMDAwMDA

                 wMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAA</email:GlobalObjId>

            </email:MeetingRequest>

            <email:InternetCPID>20127</email:InternetCPID>

            <email:Flag />

            <email:ContentClass>urn:content-classes:calendarmessage</email:ContentClass>

            <airsyncbase:NativeBodyType>1</airsyncbase:NativeBodyType>

            <email2:ConversationId>(Uí©E¯*O»&#x12;F               n                 &#x2;Ô</email2:ConversationId>

            <email2:ConversationIndex>Ì&#x10;1ë¯&#x0;&#x0;&#x1A;4E</email2:ConversationIndex>

            <email:Categories />

          </ApplicationData>

        </Add>

      </Commands>

    </Collection>

  </Collections>

</Sync>