Archibus Extension for Microsoft Exchange

Configure the Archibus Extension for Microsoft Exchange for Use with Reservations

This topic includes the following sections:

Exchange Listener

You can optionally enable a Listener by setting the exchange.enableListener option in . \WEB-INF\config\context\applications\reservations.properties configuration file

If the Listener is enabled, changes made in Exchange calendars are propagated to Web Central. Web Central receives a notification of meeting updates from Exchange. Web Central compares the meeting in Exchange with the reservation in Web Central. If the reservation was created with the Outlook Plug-in, the two meetings should match. If they do not match (for example, because the meeting has been modified via Outlook Web Access after creating it), the reservation in Web Central is updated.

The Exchange listener should be used only for Exchange 2013 and later.

If the listener is not enabled, changes made in Exchange calendars are not applied to Web Central.

Listener Account Notifications

When the meeting in Exchange is created and notifications are sent to the attendees, the listener account also receives the invitation. The listener account is an email address that is required for automated processing of meeting updates from Exchange with the Exchange listener. This account will be added to all meetings created in Exchange via Web Central and the Archibus Outlook Plug-In.

When any update is done to the meeting via OWA, the Plug-In, Web Central, or any other client, the Exchange listener verifies that the reservation is in sync, receives the updated invitation, and accepts it. The response from the listener means that the listener account has verified that the reservation and meeting are in sync.

Note: When a reservation is updated from Web Central, the change is immediately applied to the requestor's calendar. The requestor does not receive email saying his meeting was updated; only when the listener is enabled, they do get a notification that the listener account has accepted the change. On the other hand, the requestor does receive a separate notification email when his reservation is canceled.

Exchange Listener and Licensing

The Exchange Listener does not sign out a license; if the meeting organizer updates a meeting, or if an attendee responds to a meeting from Outlook Web Access, this action does not sign out a license.

Deployment Requirements

The following restrictions apply only for enabling Exchange integration in the Web Central Reservations application. The Outlook Plug-In does not require a specific Exchange version.

For deployment requirements for the Reservation Outlook Plug-In, see Reservations Plug-In for Microsoft Outlook: Installation.

Connecting to Exchange using Office 365

When configuring the application with Exchange integration, if you are connecting using Office 365, note the following options in \WEB-INF\config\context\applications\reservations.properties:

Using Exchange Autodiscover to Connect to Exchange Mailboxes

If your Exchange environment includes different Exchange versions, you can use the Web Central Reservations application with Exchange Integration for all users, regardless of the Exchange version of the server hosting their mailbox. This is done using Exchange Autodiscover, a web service that helps Microsoft Exchange administrators configure user profile settings for clients running Outlook

You enable Autodiscover by leaving the exchange.url property in reservations.properties empty.

When Autodiscover is enabled, for each mailbox, the Archibus Extension for Microsoft Exchange:

Note: The impersonation credentials specified in reservations.properties must be accepted by all Exchange servers having one of the mailboxes to impersonate.

Speeding up Retrieval of Free / Busy Times

The Autodiscover process imposes long delays when retrieving free/busy information for attendees that cannot be impersonated. For example, if the email addresses are invalid, or for external people, then the Autodiscover process takes a long time to finally decide that no endpoints are available.

When using Exchange integration, the exchange.linkedDomains property is used to speed up retrieval of free/busy information by listing the specific domains the application should try to impersonate. Entering domains for this property is recommended for Exchange integration, and can be used whether or not you are using Autodiscover. See exchange.linkedDomains.

If Autodiscover is enabled, and the linkedDomains property is null, then Autodiscover is initiated for all email addresses. If the linkedDomains property has values entered, then Autodiscover is initiated for only the entered domains.

The application caches the results, so after the initial delay, the attendee Timeline loads faster, similar to the time it takes without Autodiscover enabled. However, the first time you try to load free/busy times for an invalid email address, this takes about 50 seconds. The second time, with caching, it takes only 3 seconds. The Timeline gives a "loading..." message while the processing occurs.

Most of the delay in processing comes from external users, which could take about 50 seconds to process. For internal people, processing time could be between 2 and 10 seconds. Adding the exchange.linkedDomains property would ensure that the application does not try to impersonate the external users, which would significantly reduce the processing time.

Editing the reservations.properties Configuration File

To configure Exchange integration:

  1. Set your deployment option.
    1. Locate the file:

      [application directory]\WEB-INF\config\context\applications\reservations.properties

    2. Set one of the following deployment option in the reservations.properties configuration file.
      • For Exchange integration without the Archibus Outlook Plug-In, set

        reservations.configurationFile=classpath:com/archibus/app/reservation/exchange-integration-context.xml

      • For Exchange integration that includes the Archibus Outlook Plug-In, set

        reservations.configurationFile=classpath:com/archibus/app/reservation/exchange-integration-context-remoting.xml

  2. Set the properties required for Exchange integration.
    1. In the \WEB-INF\config\context\applications\reservations.properties configuration file, set the following properties for Exchange integration:.
      PropertyDescription
      exchange.versionRequired for Exchange integration
      exchange.organizerAccount Property Email address of the reservations organizer account. Required for supporting non-Exchange users of the Reservations Application. This account will be the meeting organizer in Exchange for reservation requestors that do not have a mailbox on the connected Exchange
      exchange.resourceAccount

      Email address for the Reservations listener account. Required for automated processing of meeting updates from Exchange with the Exchange listener. This account will be added to all meetings created in Exchange via Web Central and the Archibus Outlook Plug-In.

      Note: With the listener enabled, requestors will be receiving email notifications from the listener account. For this reason, it is recommended that you give this account a descriptive name that clarifies the reason for the emails. For example, you could name the account 'Room Reservations Service.'

      Note: By having two different properties (the organizerAccount and resourceAccount), the administrator can control whether the resourceAccount is added to all meetings (for the Exchange listener), and whether non-Exchange users can create reservations without the one decision influencing the other.

      Note: The resource account is automatically added to all reservations when having the listener enabled. The listener uses the resource account for automatic updates from Exchange to Web Central. For this reason, this account mailbox can be configured to automatically archive old meetings, as well as to automatically remove attachments from the meetings.

      Note:If the listener is not used, the exchange.resourceAccount property should be empty. If not empty, it will be added to all meetings regardless of whether the listener is enabled (to support a clustered environment). For clustered environments, each instance needs this property

      exchange.url

      Exchange Web Services URL. This is required for Exchange integration when not using Autodiscover. If using Autodiscover, leave this property empty. Use Autodiscover if your Exchange environment uses different versions of the Exchange server. See Using Exchange Autodiscover to connect to Exchange mailboxes.

      An example of this property when it is set:

      exchange.url=https://server.domainname.local/EWS/Exchange.asmx

      exchange.userName

      exchange.password

      		These are the user name and password for the Exchange Impersonation service account. Required for Exchange integration. See Creating the Service Account
      exchange.enableListenerFlag to enable/disable the listener that processes meeting updates from Exchange. The Exchange Listener runs as a scheduled workflow rule. For clustered environments, only one instance should have the listener enabled.
      exchange.ProjectId

      Used for automated processing of meeting updates from Exchange with the Exchange Listener. Required for Exchange integration. For example:

      exchange.projectId=HQ-Sybase

      Note: The exchange.enableTracing property is no longer needed, as the Reservation application now traces all connection issues between Web Central and Exchange to the archibus.log file, instead of the standard output. See Enabling Exchange tracing through log4j2.xml.

      exchange.linkedDomains=comma-separated list of email domains on the connected Exchange server.

      When using Exchange integration, this property is used to speed up retrieving free/busy information by listing the domains the application should try to impersonate. When this property is empty, connecting to Exchange is attempted for all email addresses, including external attendees. The property is recommended for Exchange integration, and can be used whether or not you are using Autodiscover.

      exchange.linkedDomains=: tgd.com,sub.tgd.net

      Note: Listing all subdomains is not required. For example, if you have sub1.tgd.com and sub2.tgd.com, adding tgd.com to the list would be sufficient.

      exchange.domainExchange Impersonation domain (not required)

      exchange.proxyServer

      exchange.proxyPort:

      		 Proxy settings for connecting to the Exchange Server (not required)
  3. If needed, configure the following application parameters:
    Application ParameterDescription

    MaxRecurrencesToCheckFreeBusy

    This number sets the maximum number of occurrences to check attendee availability when creating or editing a recurring reservation. A lower number increases performance. A higher number yields more accurate free/busy information. Default value is set to 10

    Note: This application parameter applies to the Web Central Reservations application with or without Exchange integration. It is not applicable to the Outlook Plug-In.

Enabling Exchange Tracing through log4j2.xml

To enable the tracing of all connection issues between Web Central and Exchange to the archibus.log file, edit \WEB-INF\config\context\logging/log4j2.xml and add:

<Logger name="com.archibus.app.reservation.exchange" level="debug" additivity="false"> <AppenderRef ref="archibusLog" /> </Logger>

This enables the debugging of Exchange integration so that you can see any errors that might be occurring.

Setting up Account Mailboxes

Note: For information on how Exchange monitors room mailboxes (mailboxes in Exchange that are associated with reservable rooms), see Monitoring Room Mailboxes.

You can create two mailboxes:

Account Mailbox Description
organizerAccount The organizer mailbox is required only if you want users without a mailbox on the connected Exchange to be able to create reservations
resourceAccount The resource mailbox is required only if the Exchange listener is used

No special permissions are required for these mailboxes, although the service account should be allowed to impersonate them. Typically, the organizerAccount would be a shared mailbox, and the resourceAccount would be a resource mailbox, but any type of mailbox will work. Although using the same mailbox for both organizerAccount and resourceAccount is an option, this is not recommended for performance reasons.

On Exchange, using a resource mailbox allows additional configurations, such as:

Note: Automatic processing of requests should not be enabled, as this is handled by the Archibus Reservations application.

In addition to the special options for resource mailboxes, both mailboxes can be hidden from Exchange address lists, and their Free/Busy information can be hidden. These options can be set from the command line, or by using the Exchange Management Console. See the Exchange documentation for more information on these configurations.

Example PowerShell commands for creating the resource mailbox

The Resource account can be an equipment mailbox, such as archibus.reservation@...

  1. To create a new resource mailbox, enter the following command:

New-Mailbox -Name ‘archibus.reservation’ –DisplayName ‘Archibus Reservation’ –Equipment -Password (ConvertTo-SecureString -String 'gd&YH5486' -AsPlainText -Force) -ResetPasswordOnNextLogon $false

  1. Disable automatic processing of requests:

Set-CalendarProcessing –Identity ‘archibus.reservation’ -AutomateProcessing:None –AllowConflicts:$true

  1. Hide the free-busy information:

Set-MailboxFolderPermission -identity "archibus.reservation:\Calendar" -User Default -AccessRights None

Example PowerShell command for creating an organizer account

The Organizer account can be a shared mailbox, such as archibus.organizer@...

Note: The Organizer account is required only if employees without an Exchange mailbox create meetings.

To create an organizer account, enter the following command:

New-Mailbox -Shared -Name "archibus.organizer" -DisplayName "Archibus Organizer"

Configuring Exchange Web Services

When using Exchange 2013 and up, you can configure access restrictions for Exchange Web Services (EWS) for the entire organization, per user, and per application via HTTP User Agent. By default, no restrictions are applied. However, if access to EWS has been disabled or limited, then it must be enabled.

Enabling access to Exchange Web Services

Exchange Web Services are enabled by default on Exchange Servers with the Client Access Server Role installed. By default, no access restrictions are applied.

Using Exchange Impersonation

Exchange Impersonation is a mechanism that allows a single Windows Active Directory account to act on behalf of other users on a Microsoft Exchange mailbox, as if they were performing the action themselves.

See: