Planning

In preparation for the installation of Events2HVAC, the following items must be considered:

Connection Type:

The Exchange Event Provider can use either of the following APIs to get room calendar data.

•      Exchange Web Service (EWS) API Connection

•      Microsoft Graph API Connection

EWS is an older API and has been deprecated.  It is still in service, but no longer maintained.  MS Graph API is the newest and recommended connection method.

Resource Mailboxes

The Exchange Event Provider can only pull schedules for meetings (not appointments) generated in Outlook that include a reserved space with a corresponding resource mailbox. Thus, before installing Events2HVAC, it is recommended that you review the list of rooms designated for use with Events2HVAC and ensure that each one has a resource mailbox and address.

Resource mailboxes can be created using the Exchange user interface or with PowerShell commands.

Room List Distribution Groups

As explained above, room list distribution groups in Outlook/Exchange allow users to group spaces together and find rooms more easily. Events2HVAC uses these distribution groups to locate rooms in Exchange. It is recommended that users create a room list distribution group for each building containing a room to be controlled by Events2HVAC, or at least a distribution group of just the rooms which will be controlled by Events2HVAC.

Room list distribution groups can only be created using PowerShell commands.

Permissions

Events2HVAC retrieves event information from the Exchange server over the local network connection or the Internet using the Exchange Web Service (EWS), a separate component provided by Microsoft, which allows 3^rd party systems to access exchange data.  This EWS client component is included in the Events2HVAC installation.

The login account for EWS ideally is a service account with the role/permission of ApplicationImpersonation.  This will allow the login user to impersonate each calendar mailbox to gather room calendar event data.

If the login account does not have a mailbox, then you will also need to specify an email account that does have a mailbox so the login account can impersonate that account to retrieve the room distribution lists and room calendar resources.

Alternatively, you could also give the login user full delegate access permissions to each room mailbox, but this is not recommended in most cases.

Best Practices for Connection (EWS ONLY):

1.  Create a service account for Events2HVAC in Exchange with no mailbox and give it “ApplicationImpersonation” permissions.  Make sure this account’s password does not expire.  You can also limit the scope of the permissions to certain areas in Exchange.

2.  Use another account email that does have a mailbox and impersonate that account for room list discovery.

See also:

•      https://blogs.msdn.microsoft.com/exchangedev/2009/06/15/exchange-impersonation-vs-delegate-access/

•      https://blogs.msdn.microsoft.com/webdav_101/2012/06/27/the-importance-of-ews-impersonation-while-using-an-application-account/

Performance (EWS)

Each resource mailbox has a separate calendar that is used to keep track of requested and booked meetings. The Microsoft Exchange Event Provider uses Exchange Web Service (EWS) to impersonate each resource calendar, one at a time, to retrieve schedule data.  Because of this behavior, querying schedules for multiple rooms on demand in real-time may be slow. However, the speed of regular background queries for daily polling should not be an issue.

A future version of the Microsoft Exchange Event Provider will implement caching to a local database to speed up on demand, real-time processing. 

If your organization has a lot a resource mailboxes, poll periods may need to be adjusted accordingly to allow for these delays.

Exchange Connection (EWS)

To allow Events2HVAC to successfully connect, you will need to know the URL for the Exchange Web Services component; and the Exchange server administrator may need to create a dedicated user for the Events2HVAC login. 

There are two ways to authenticate with EWS:  basic and OAuth2.  After 10/13/2020, basic authentication will no longer be supported on O365.

See instructions below.

EWS API Settings Needed (Basic Authentication)

EWS API Settings Needed (OAuth Authentication)

MS Graph API Settings Needed (OAuth Authentication)