Get free/busy information by using EWS in Exchange
Learn how to get free/busy information and suggested meeting times by using the EWS Managed API or EWS in Exchange.
Using the EWS Managed API or EWS to programmatically create a meeting and send out meeting requests is great, but finding a time that works for all your attendees is often a challenge. If you have to manually check to see when everyone is available, it defeats the purpose of automating the task. Fortunately, the ExchangeService.GetUserAvailability EWS Managed API method and the GetUserAvailability EWS operation come to your rescue. You can use this method or operation to query an Exchange server to find the best time to schedule a meeting or just get free/busy information for attendees. You can get the free/busy information for a list of attendees, or have your Exchange server find a meeting time for you, or both
Figure 1 illustrates the problem and the solution.
Figure 1. Requesting availability information from an Exchange server
Get suggested meeting times and free/busy information by using the EWS Managed API
You can get both a list of suggested meeting times and all the scheduled event times for your attendees when you use an AvailabilityData enumeration value of FreeBusyAndSuggestions in your ExchangeService.GetUserAvailability method call, as shown in the following example.
This example assumes that you have authenticated to an Exchange server and have acquired an ExchangeService object named service.
private static void GetSuggestedMeetingTimesAndFreeBusyInfo(ExchangeService service)
{
// Create a collection of attendees.
List<AttendeeInfo> attendees = new List<AttendeeInfo>();
attendees.Add(new AttendeeInfo()
{
SmtpAddress = "mack@contoso.com",
AttendeeType = MeetingAttendeeType.Organizer
});
attendees.Add(new AttendeeInfo()
{
SmtpAddress = "sadie@contoso.com",
AttendeeType = MeetingAttendeeType.Required
});
// Specify options to request free/busy information and suggested meeting times.
AvailabilityOptions availabilityOptions = new AvailabilityOptions();
availabilityOptions.GoodSuggestionThreshold = 49;
availabilityOptions.MaximumNonWorkHoursSuggestionsPerDay = 0;
availabilityOptions.MaximumSuggestionsPerDay = 2;
// Note that 60 minutes is the default value for MeetingDuration, but setting it explicitly for demonstration purposes.
availabilityOptions.MeetingDuration = 60;
availabilityOptions.MinimumSuggestionQuality = SuggestionQuality.Good;
availabilityOptions.DetailedSuggestionsWindow = new TimeWindow(DateTime.Now.AddDays(1), DateTime.Now.AddDays(2));
availabilityOptions.RequestedFreeBusyView = FreeBusyViewType.FreeBusy;
// Return free/busy information and a set of suggested meeting times.
// This method results in a GetUserAvailabilityRequest call to EWS.
GetUserAvailabilityResults results = service.GetUserAvailability(attendees,
availabilityOptions.DetailedSuggestionsWindow,
AvailabilityData.FreeBusyAndSuggestions,
availabilityOptions);
// Display suggested meeting times.
Console.WriteLine("Availability for {0} and {1}", attendees[0].SmtpAddress, attendees[1].SmtpAddress);
Console.WriteLine();
foreach (Suggestion suggestion in results.Suggestions)
{
Console.WriteLine("Suggested date: {0}\n", suggestion.Date.ToShortDateString());
Console.WriteLine("Suggested meeting times:\n");
foreach (TimeSuggestion timeSuggestion in suggestion.TimeSuggestions)
{
Console.WriteLine("\t{0} - {1}\n",
timeSuggestion.MeetingTime.ToShortTimeString(),
timeSuggestion.MeetingTime.Add(TimeSpan.FromMinutes(availabilityOptions.MeetingDuration)).ToShortTimeString());
}
}
int i = 0;
// Display free/busy times.
foreach (AttendeeAvailability availability in results.AttendeesAvailability)
{
Console.WriteLine("Availability information for {0}:\n", attendees[i].SmtpAddress);
foreach (CalendarEvent calEvent in availability.CalendarEvents)
{
Console.WriteLine("\tBusy from {0} to {1} \n", calEvent.StartTime.ToString(), calEvent.EndTime.ToString());
}
i++;
}
}
Get suggested meeting times and free/busy information by using EWS
You can get both a list of suggested meeting times and all the scheduled event times for your attendees by using the GetUserAvailability operation, as shown in the following example. This is also the XML request that the EWS Managed API sends when you use the EWS Managed API to get suggested meeting times.
<?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" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Name="(UTC-08:00) Pacific Time (US &amp; Canada)" Id="Pacific Standard Time">
<t:Periods>
<t:Period Bias="P0DT8H0M0.0S" Name="Standard" Id="Std" />
<t:Period Bias="P0DT7H0M0.0S" Name="Daylight" Id="Dlt/1" />
<t:Period Bias="P0DT7H0M0.0S" Name="Daylight" Id="Dlt/2007" />
</t:Periods>
<t:TransitionsGroups>
<t:TransitionsGroup Id="0">
<t:RecurringDayTransition>
<t:To Kind="Period">Dlt/1</t:To>
<t:TimeOffset>P0DT2H0M0.0S</t:TimeOffset>
<t:Month>4</t:Month>
<t:DayOfWeek>Sunday</t:DayOfWeek>
<t:Occurrence>1</t:Occurrence>
</t:RecurringDayTransition>
<t:RecurringDayTransition>
<t:To Kind="Period">Std</t:To>
<t:TimeOffset>P0DT2H0M0.0S</t:TimeOffset>
<t:Month>10</t:Month>
<t:DayOfWeek>Sunday</t:DayOfWeek>
<t:Occurrence>-1</t:Occurrence>
</t:RecurringDayTransition>
</t:TransitionsGroup>
<t:TransitionsGroup Id="1">
<t:RecurringDayTransition>
<t:To Kind="Period">Dlt/2007</t:To>
<t:TimeOffset>P0DT2H0M0.0S</t:TimeOffset>
<t:Month>3</t:Month>
<t:DayOfWeek>Sunday</t:DayOfWeek>
<t:Occurrence>2</t:Occurrence>
</t:RecurringDayTransition>
<t:RecurringDayTransition>
<t:To Kind="Period">Std</t:To>
<t:TimeOffset>P0DT2H0M0.0S</t:TimeOffset>
<t:Month>11</t:Month>
<t:DayOfWeek>Sunday</t:DayOfWeek>
<t:Occurrence>1</t:Occurrence>
</t:RecurringDayTransition>
</t:TransitionsGroup>
</t:TransitionsGroups>
<t:Transitions>
<t:Transition>
<t:To Kind="Group">0</t:To>
</t:Transition>
<t:AbsoluteDateTransition>
<t:To Kind="Group">1</t:To>
<t:DateTime>2007-01-01T08:00:00.000Z</t:DateTime>
</t:AbsoluteDateTransition>
</t:Transitions>
</t:TimeZoneDefinition>
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:GetUserAvailabilityRequest>
<m:MailboxDataArray>
<t:MailboxData>
<t:Email>
<t:Address>mack@contoso.com</t:Address>
</t:Email>
<t:AttendeeType>Organizer</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
<t:MailboxData>
<t:Email>
<t:Address>sadie@contoso.com</t:Address>
</t:Email>
<t:AttendeeType>Required</t:AttendeeType>
<t:ExcludeConflicts>false</t:ExcludeConflicts>
</t:MailboxData>
</m:MailboxDataArray>
<t:FreeBusyViewOptions>
<t:TimeWindow>
<t:StartTime>2014-02-13T00:00:00</t:StartTime>
<t:EndTime>2014-02-14T00:00:00</t:EndTime>
</t:TimeWindow>
<t:MergedFreeBusyIntervalInMinutes>30</t:MergedFreeBusyIntervalInMinutes>
<t:RequestedView>FreeBusy</t:RequestedView>
</t:FreeBusyViewOptions>
<t:SuggestionsViewOptions>
<t:GoodThreshold>49</t:GoodThreshold>
<t:MaximumResultsByDay>2</t:MaximumResultsByDay>
<t:MaximumNonWorkHourResultsByDay>0</t:MaximumNonWorkHourResultsByDay>
<t:MeetingDurationInMinutes>60</t:MeetingDurationInMinutes>
<t:MinimumSuggestionQuality>Good</t:MinimumSuggestionQuality>
<t:DetailedSuggestionsWindow>
<t:StartTime>2014-02-13T00:00:00</t:StartTime>
<t:EndTime>2014-02-14T00:00:00</t:EndTime>
</t:DetailedSuggestionsWindow>
</t:SuggestionsViewOptions>
</m:GetUserAvailabilityRequest>
</soap:Body>
</soap:Envelope>
The server responds to the GetUserAvailability request with a GetUserAvailability response message, as shown in the following example.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="873" MinorBuildNumber="9" Version="V2_9"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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">FreeBusy</FreeBusyViewType>
<CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2014-02-13T08:00:00</StartTime>
<EndTime>2014-02-13T10:00:00</EndTime>
<BusyType>Free</BusyType>
</CalendarEvent>
<CalendarEvent>
<StartTime>2014-02-13T11:00:00</StartTime>
<EndTime>2014-02-13T12:00:00</EndTime>
<BusyType>Busy</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>1</DayOrder>
<Month>11</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>2</DayOrder>
<Month>3</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">FreeBusy</FreeBusyViewType>
<CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<CalendarEvent>
<StartTime>2014-02-12T00:00:00</StartTime>
<EndTime>2014-02-13T00:00:00</EndTime>
<BusyType>Free</BusyType>
</CalendarEvent>
<CalendarEvent>
<StartTime>2014-02-13T08:00:00</StartTime>
<EndTime>2014-02-13T10:00:00</EndTime>
<BusyType>Free</BusyType>
</CalendarEvent>
<CalendarEvent>
<StartTime>2014-02-13T11:00:00</StartTime>
<EndTime>2014-02-13T12:00:00</EndTime>
<BusyType>Busy</BusyType>
</CalendarEvent>
<CalendarEvent>
<StartTime>2014-02-13T15:00:00</StartTime>
<EndTime>2014-02-13T16:00: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>1</DayOrder>
<Month>11</Month>
<DayOfWeek>Sunday</DayOfWeek>
</StandardTime>
<DaylightTime>
<Bias>-60</Bias>
<Time>02:00:00</Time>
<DayOrder>2</DayOrder>
<Month>3</Month>
<DayOfWeek>Sunday</DayOfWeek>
</DaylightTime>
</TimeZone>
<WorkingPeriodArray>
<WorkingPeriod>
<DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
<StartTimeInMinutes>540</StartTimeInMinutes>
<EndTimeInMinutes>1020</EndTimeInMinutes>
</WorkingPeriod>
</WorkingPeriodArray>
</WorkingHours>
</FreeBusyView>
</FreeBusyResponse>
</FreeBusyResponseArray>
<SuggestionsResponse>
<ResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</ResponseMessage>
<SuggestionDayResultArray>
<SuggestionDayResult xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<Date>2014-02-13T00:00:00</Date>
<DayQuality>Excellent</DayQuality>
<SuggestionArray>
<Suggestion>
<MeetingTime>2014-02-13T09:00:00</MeetingTime>
<IsWorkTime>true</IsWorkTime>
<SuggestionQuality>Excellent</SuggestionQuality>
<AttendeeConflictDataArray>
<IndividualAttendeeConflictData>
<BusyType>Free</BusyType>
</IndividualAttendeeConflictData>
<IndividualAttendeeConflictData>
<BusyType>Free</BusyType>
</IndividualAttendeeConflictData>
</AttendeeConflictDataArray>
</Suggestion>
<Suggestion>
<MeetingTime>2014-02-13T09:30:00</MeetingTime>
<IsWorkTime>true</IsWorkTime>
<SuggestionQuality>Excellent</SuggestionQuality>
<AttendeeConflictDataArray>
<IndividualAttendeeConflictData>
<BusyType>Free</BusyType>
</IndividualAttendeeConflictData>
<IndividualAttendeeConflictData>
<BusyType>Free</BusyType>
</IndividualAttendeeConflictData>
</AttendeeConflictDataArray>
</Suggestion>
</SuggestionArray>
</SuggestionDayResult>
</SuggestionDayResultArray>
</SuggestionsResponse>
</GetUserAvailabilityResponse>
</s:Body>
</s:Envelope>
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for