GetUserAvailability Operation
Last modified: September 14, 2011
Applies to: Exchange Server 2007 | Exchange Server 2010
In this article
Using the GetUserAvailability Operation
SOAP Headers
Request Format
Successful GetUserAvailability Response
The GetUserAvailability operation provides detailed information about the availability of a set of users, rooms, and resources within a specified time period.
Using the GetUserAvailability Operation
The GetUserAvailability operation provides current user availability information at a specified level of detail. Client applications such as MicrosoftOfficeOutlook, MicrosoftOutlook Web Access, Microsoft Outlook Mobile Access, and other applications use SMTP addresses to identify the requested user information.
The Availability service expands distribution lists to retrieve the free/busy status for each member of the list, as long as the number of mailboxes in the distribution list is less than 100 identities, which is the maximum number of identities that the GetUserAvailability operation can request. The free/busy statuses of the members of the distribution list are merged to a single free/busy status for the whole distribution list.
Client application requests specify the time period of the availability query. The default time period for the requested information is 42 days. If the user's calendar contains appointments or meetings that are both within and outside the defined time period for the query, the appointment is returned.
The appointment and meeting times that are returned are in the same time zone as the client application that is requesting the meeting.
The Availability service processes the request for each client. The service expands all the recurring appointments and returns the maximum number of calendar details that the requesting client has permission to receive.
Note
If the target mailbox is unavailable or cannot be found, a MailRecipientNotFoundException exception is thrown. The client receives an error message that states that the mail recipient is not found in the Active Directory directory service.
SOAP Headers
The GetUserAvailability operation can use the SOAP headers that are listed and described in the following table.
Header |
Element |
Description |
|---|---|---|
Impersonation |
Identifies the user whom the client is impersonating. |
|
RequestVersion |
Identifies the schema version for the operation request. |
|
ServerVersion |
Identifies the version of the server that responded to the request. |
|
TimeZoneContext |
Specifies a SOAP header that identifies the time zone to be used for all responses from the server. All times that are returned from the server will be converted to the specified time zone. |
Request Format
Description
The following example of a GetUserAvailability operation request shows how to get detailed availability information for two users in the Pacific Time Zone.
Code
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<GetUserAvailabilityRequest xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<t:TimeZone xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</t:TimeZone>
<MailboxDataArray>
<t:MailboxData>
<t:Email>
<t:Address>user1@example.com</t:Address>
</t:Email>
<t:AttendeeType>Required</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
<t:MailboxData>
<t:Email>
<t:Address>user2@example.com</t:Address>
</t:Email>
<t:AttendeeType>Required</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
</MailboxDataArray>
<t:FreeBusyViewOptions>
<t:TimeWindow>
<t:StartTime>2006-10-16T00:00:00</t:StartTime>
<t:EndTime>2006-10-16T23:59:59</t:EndTime>
</t:TimeWindow>
<t:MergedFreeBusyIntervalInMinutes>60</t:MergedFreeBusyIntervalInMinutes>
<t:RequestedView>DetailedMerged</t:RequestedView>
</t:FreeBusyViewOptions>
</GetUserAvailabilityRequest>
</soap:Body>
</soap:Envelope>
Comments
For more information about retrieving suggested meetings by using the SuggestionsViewOptions element, see the schema in the virtual directory named EWS on your Client Access server (CAS).
Request Elements
The following elements are used in the request:
Successful GetUserAvailability Response
Description
The following example shows a successful response to the GetUserAvailability operation request.
Note
The calendar event identifiers have been shortened to preserve readability.
Code
<?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="0" MajorBuildNumber="665" MinorBuildNumber="7"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<GetUserAvailabilityResponse xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<FreeBusyResponseArray>
<FreeBusyResponse>
<ResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</ResponseMessage>
<FreeBusyView>
<FreeBusyViewType xmlns="https://schemas.microsoft.com/exchange/services/2006/types">DetailedMerged</FreeBusyViewType>
<MergedFreeBusy xmlns="https://schemas.microsoft.com/exchange/services/2006/types">000002220220000000000000</MergedFreeBusy>
<CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2006-10-16T06:00:00-07:00</StartTime>
<EndTime>2006-10-16T06:30:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>14B6414B0</ID>
<Subject>Meet with Contoso Account Executives</Subject>
<Location />
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
<CalendarEvent>
<StartTime>2006-10-16T07:00:00-07:00</StartTime>
<EndTime>2006-10-16T08:00:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>E14B6414B0B</ID>
<Subject>Pick up my groceries</Subject>
<Location />
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
<CalendarEvent>
<StartTime>2006-10-16T09:40:00-07:00</StartTime>
<EndTime>2006-10-16T10:10:00-07:00</EndTime>
<BusyType>Busy</BusyType>
<CalendarEventDetails>
<ID>14B6414B0B1</ID>
<Subject>Meet with doctor</Subject>
<Location>Kirkland</Location>
<IsMeeting>false</IsMeeting>
<IsRecurring>false</IsRecurring>
<IsException>false</IsException>
<IsReminderSet>false</IsReminderSet>
<IsPrivate>false</IsPrivate>
</CalendarEventDetails>
</CalendarEvent>
</CalendarEventArray>
<WorkingHours xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<TimeZone>
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</TimeZone>
<WorkingPeriodArray>
<WorkingPeriod>
<DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
<StartTimeInMinutes>480</StartTimeInMinutes>
<EndTimeInMinutes>1020</EndTimeInMinutes>
</WorkingPeriod>
</WorkingPeriodArray>
</WorkingHours>
</FreeBusyView>
</FreeBusyResponse>
<FreeBusyResponse>
<ResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</ResponseMessage>
<FreeBusyView>
<FreeBusyViewType xmlns="https://schemas.microsoft.com/exchange/services/2006/types">FreeBusyMerged</FreeBusyViewType>
<MergedFreeBusy xmlns="https://schemas.microsoft.com/exchange/services/2006/types">000000001100000000000000</MergedFreeBusy>
<CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2006-10-16T09:00:00-07:00</StartTime>
<EndTime>2006-10-16T10:00:00-07:00</EndTime>
<BusyType>Tentative</BusyType>
</CalendarEvent>
</CalendarEventArray>
<WorkingHours xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<TimeZone>
<Bias>480</Bias>
<StandardTime>
<Bias>0</Bias>
<Time>02:00:00</Time>
<DayOrder>5</DayOrder>
<Month>10</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>1</DayOrder>
<Month>4</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</TimeZone>
<WorkingPeriodArray>
<WorkingPeriod>
<DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
<StartTimeInMinutes>480</StartTimeInMinutes>
<EndTimeInMinutes>1020</EndTimeInMinutes>
</WorkingPeriod>
</WorkingPeriodArray>
</WorkingHours>
</FreeBusyView>
</FreeBusyResponse>
</FreeBusyResponseArray>
</GetUserAvailabilityResponse>
</soap:Body>
</soap:Envelope>
Comment
The availability information for each user appears in a unique FreeBusyResponse element. The order of users in the GetUserAvailability operation request determines the order of availability data for each user in the response.
An error will be returned to the client if the number of appointments in the time period that is defined in the query is greater than the administrator-specified maximum number. The default maximum number of appointments is 10,000 single instances and expanded recurrence items. This property can be configured only by an administrator.
Response Elements
The following elements are used in the response: