GetUserAvailability Operation
Topic Last Modified: 2008-09-05
The GetUserAvailability operation provides detailed information about the availability of a set of users, rooms, and resources within a specified time window.
Using the GetUserAvailability Operation
The GetUserAvailability operation provides current user availability information at a specified level of detail. Client applications such as Microsoft Office Outlook, Microsoft Outlook 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 Web service method can request.
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.
Request Format
Description
The following example of a GetUserAvailability request shows how to get detailed availability information for two users in the Pacific ime 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
Refer to the schema for more information about retrieving suggested meetings by using the SuggestionsViewOptions element.
Request Elements
The following elements are used in this GetUserAvailability request:
Successful GetUserAvailability Response
Description
The following example shows a successful response to the GetUserAvailability 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 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 by an administrator.
Response Elements
The following elements are used in the response:
- ServerVersionInfo
- GetUserAvailabilityResponse
- FreeBusyResponseArray
- FreeBusyResponse
- ResponseMessage
- ResponseCode
- FreeBusyView
- FreeBusyViewType
- MergedFreeBusy
- CalendarEventArray
- CalendarEvent
- StartTime
- EndTime
- BusyType
- CalendarEventDetails
- ID
- Subject (CalendarEventDetails)
- Location (CalendarEventDetails)
- IsMeeting (CalendarEventDetails)
- IsRecurring (CalendarEventDetails)
- IsException
- IsReminderSet
- IsPrivate
- WorkingHours
- TimeZone (Availability)
- Bias (UTC)
- StandardTime
- Bias
- Time
- DayOrder
- Month
- DayOfWeek (TimeZone)
- DaylightTime
- WorkingPeriodArray
- WorkingPeriod
- DayOfWeek (WorkingPeriod)
- StartTimeInMinutes
- EndTimeInMinutes