Reservations Plugin for Microsoft Outlook: Configuration

After installing the Archibus Plugin for Microsoft Outlook, the next step is to configure it. For more details about the installation process, see Reservations Plugin for Microsoft Outlook: Installation.

To configure the plugin:

Set the deployment option. In the reservations.properties configuration file, you set the reservations.configurationFile property to enable the Outlook Plugin Web Services, and to determine whether Web Central uses the Archibus Extension for Microsoft Exchange. See Specifying the deployment option.
If needed, edit OutlookPlugin.dll.config. If not already done by the Admin, edit OutlookPlugin.dll.config file in the installation directory:
Set DefaultAppServerLocation to your Archibus server address, set DefaultProject to the Archibus Project you want to connect to.
Email path: Set the Path for the Link to Reservation Details in Emails by setting the absoluteAppPath preference in
/WEB-INF/config/context/compatibility/afm-config.xml. See Setting the Path for the Link to Reservation Details in Email Notifications.
Note: This setting is also required for the Web Central Reservations Application when the Outlook Plugin is not used.
Database Configuration: For each employee, the email of the Outlook user must match exactly the email address in the Archibus Users table (afm_users) and the Employees (em) table. See Database Configuration.
Configure the activity parameters (optional). If needed, from the Web Central application, modify activity parameters for the Outlook Plugin:
- PlugInFullReservationView - View loaded by the plugin when the user loads the full My Reservations Web Central View
- PlugInRoomInformationView - View loaded by the plugin when the user presses the "I" button to get room’s information
- PlugInOptionalLocationFilters – List of location filters shown in the plugin. Building is always shown, the optional ones are country, state, city, site, and floor.
Set the following application parameters to prevent performance issues (optional):
- MaxRecurrencesToCreate: This number sets the maximum number of occurrences to process when creating a recurring reservation. Default value is set to 250.
Note: Because of performance and technical limitations, it is not recommended to enter a numeric value higher than 500.

Database Configuration

For each employee, the email address of the Microsoft Outlook user must match exactly, including case, the email address in the Archibus Users table (afm_users) and the Employees (em) table. Since Oracle is case-sensitive, the case used in the email address must match the database; for Sybase and MS-SQL it does not matter.

Also, in the Employees (em) table, each Employee record must have a value for Site and Building.

The Outlook Plugin detects the language of the operating system and presents it as default. When installed, the Outlook Plugin will load the .dll corresponding to that language. The user in Archibus must be set with the same Locale.

Specifying the Deployment Option

You perform the following server-side configurations in the reservations.properties file to set your deployment option.

You can set the reservations.configurationFile property to enable the Outlook Plugin Web Services, and to determine whether Web Central uses Exchange integration.

In order for the client plugin to communicate with the Web Central server, you need to enable the Reservations Web Services. The configuration options are described below.

When using Exchange integration, there are additional properties to set. See Installing and Configuring the Archibus Extension for Microsoft Exchange.

To set the reservations.configurationFile property:

Locate the
[application directory]\WEB-INF\config\context\applications\reservations.properties file
Set “reservations.configurationFile” to one of the following options that includes the Outlook Plugin:

Option	Description	Entry for reservations.configuration File
The following option does not include Exchange integration (the Archibus Extension for Microsoft Exchange)
Reservations application with no Exchange integration, but with the Outlook Plugin	Reservations are created from Web Central or from the Microsoft Outlook Plugin. Updates in Web Central are not propagated to the plugin.	reservations.configurationFile=classpath:com/archibus/app/reservation/no-integration-context-remoting.xml
The following option includes Exchange integration. With Exchange integration, a listener can be enabled or disabled . If the listener is enabled, changes done in Exchange calendars are propagated to Web Central.
Reservations application with Exchange and the Outlook Plugin	Reservations are created either from Web Central or from the Microsoft Outlook Plugin. Attendee availability is retrieved from the Exchange calendar. Exchange is in charge of notifications. If the listener is enabled, changes done in Exchange are also applied in Web Central, and thus are also visible in the Outlook Plugin.	reservations.configurationFile=classpath:com/archibus/app/reservation/exchange-integration-context-remoting.xml

Setting the Path for the Link to Reservation Details in Email Notifications

Note: This setting is also required for the Web Central Reservations application when the Outlook Plugin is not used.

When the application sends email notification for reservations, the email includes a link to the reservation's details. The path for the link is determined by the absoluteAppPath preference set in the afm-config.xml file. The EventHandlerBase.getWebCentralPath(context) builds the URL from this property.

By default, this property is set to

absoluteAppPath="http://localhost:8080/#Attribute%//@webAppDirectory%"”

To change this to reflect the location for your deployment, update the following to match the location where Web Central is running.

absoluteAppPath preference in /WEB-INF/config/context/compatibility/afm-config.xml

Configuring Messages for the Outlook Plugin using the Messages table

The following can be customized using the Messages table in the Archibus database:

All pop-up texts configured in the Outlook Plugin can now be customized via the Messages table.
Note: Simple error messages like 'Could not retrieve list of available rooms' are not included.
The Room Finder label and screen-tip shown on the ribbon of the Appointment window.

Other labels and titles cannot be customized.

The messages are retrieved from the server and cached in the Outlook Plugin for 12 hours (along with all activity parameters). Therefore, if you change a message in the database, you should either restart Outlook, or wait 12 hours to see the modified message in the Outlook Plugin.

Note: If a message is not defined or is empty in the database, or if the custom message cannot be retrieved because the server does not support the functionality, then the Outlook Plugin shows the default message defined locally in the Outlook Plugin.

Notes for Using the Plugin

Once you install the plugin, users will work with the Reservations panel in Microsoft Outlook. They will use the dialog boxes for any guidance; user documentation is not required.

However, Archibus Administrators may wish to be aware of the following corner cases so that they can field questions that might arise:

You cannot make reservations when not connected to Web Central.

You can edit existing ones without changing the room, but in fact this is only editing the meeting in Outlook.
While not connected to Web Central, you can also schedule new meetings in Outlook without linking to a room reservation.
Then, when the connection is restored, you can reopen the meeting and create a reservation for it.

If the Web Central application is not started or the Outlook Plugin is not connected to Web Central, the Room Finder image shows an alert icon, but no error message is displayed. To retry the connection, click the alert icon in the Room Finder option.

If you are creating a reservation using the Outlook Plugin and the Archibus Web Central application stops, or the plugin is no longer connected to the Web Central application, then the plugin presents the message below :

“Could not retrieve list of available rooms. Exception of type ‘Archibus.SmartClient.WebServicesProxy.ConnectionFailedException’ was thrown.”

If the connection is resumed, you can choose to Retry and can continue creating the reservation. This means that users cannot create reservations if the plugin is not connected to Web Central, and no syncing is done or messages displayed.

The communication works only one way

The communication works only one way: from the plugin to Web Central and not vice versa. Therefore, if you change a reservation using Web Central and not the plugin, the records are out of sync. The attendees and requestors are notified via email so that they can make the updates manually in their calendars. No synching is done or message displayed.

However, if you have both the plugin and Exchange integration, when you create a meeting using the pluginand update it in Web Central, Exchange will propagate the change, so, in this case, the change is also visible in the plugin.

Canceling future reservations

To cancel future reservations, you must consider both the current date and the cancellation window associated with each room. For example, suppose a room requires three days notification in order to cancel a reservation, and the reservation is scheduled to occur two days in the future; in this case, you cannot cancel this room’s reservation through Microsoft Outlook. Archibus users who are members of the Reservation Service Desk or Reservation Manager security groups are not subject to this restriction.

Recurrence exceptions

The plugin does not support Outlook’s recurrence exceptions. If you want to modify a recurring pattern that has exceptions, the plugin prompts you to confirm that it must first cancel the exceptions. However, if restrictions exist in Archibus, some exception dates may not be able to be canceled. In this case, the system prompts the user to ignore these dates or abort the cancellation altogether. If the user chooses to ignore these items, the plugin disconnects them from Outlook, but retains them in Archibus.

Changing the time zone

For single appointments, you can use Outlook's time zone control to change the time zone of the appointment. For recurring appointments, Outlook hides the time zone controls as well as the date and time controls. For recurring appointments, you modify the date, time, and time zone via Outlook’s recurrence pattern dialog.

Changing the room only

If you change only the room in Web Central, not the date and time, then the reservation remains in sync with the meeting in Outlook. However, the Location for the meeting in Outlook still refers to the previously selected room, and you will not get a warning about this when opening the meeting in Outlook.

The Outlook Plugin supports Shared Calendars - Exchange

The Outlook Plugin supports shared calendars that enable assistants to book room reservations on their managers’ calendars, and on any calendar they are allowed to edit, according to the permissions configured in Exchange.

Anytime a user opens a meeting from the organizer’s calendar that the user has permission to change, the Room Reservation Panel is enabled.

Note that these requirements must be met:

For each email account, shared calendar, or shared mailbox used to create reservations, an employee must exist in Web Central with that email address. The primary email address defined in Outlook is used for the initial connectivity check in the Outlook Plugin.
A user and employee must exist in Web Central with the Outlook Plugin user’s Windows user name. The Web Central user’s email usually corresponds to the primary email configured in Outlook, but it isn't required that this be so.

Creating reservations on shared calendars

When the Outlook Plugin submits a request to the Reservations Web Service to create a room reservation, the following are set:

The reserve.email is set to the email address of the user whose calendar contains the meeting.
The user_requested_for and user_requested_by fields are set to the Employee ID of the user whose calendar contains the meeting. The em_id is determined by searching for the calendar owner’s email address in the em table.
The reserve.user_created_by is set to the employee signed in to Archibus (via SSO based on the user's Windows user name).

Editing reservations on shared calendars.

When the Outlook Plugin submits a request to edit a room reservation, it sets the reserve.user_last_modified_by to the employee signed in to Archibus. The reserve.email, reserve.user_requested_by and reserve.user_requested_for fields are not modified.