Installing the Room Search add-in in Microsoft Outlook

How do you install the Room Search add-in for Outlook? Our Room Search add-in for Microsoft Outlook is a user-friendly Perceptive app. But this app is displayed within the Outlook application as a side-panel interface. You can install the add-in in two ways: (1) Deploy it as an Exchange administrator, or (2) Install it as an Outlook user.

Note: To resolve display issues or find authentication details, see Additional Q & A. For more information, see Managing reservations and reservable resources.

Contents

  • I. How do you install the Room Search add-in for Outlook?
  • II. Deploy the add-in as an Exchange Administrator
  • III. Install the add-in as an Outlook User
  • IV. Additional Q & A
Parent topic: Integrating IBM TRIRIGA with Microsoft Exchange

I. How do you install the Room Search add-in for Outlook?

You can install the add-in in two ways: (1) Deploy it as an Exchange administrator, or (2) Install it as an Outlook user.

Important: To ensure that the Room Search add-in works correctly on desktop Outlook clients on Windows, you must use the Microsoft WebView2 embedded browsers. For more information, see Browsers used by Office Add-ins.

II. Deploy the add-in as an Exchange Administrator

Note: The following steps are based on the Office 365 web version of Outlook. Other native or client versions may follow slightly different but similar steps.

Here are the basic steps to deploy the add-in to multiple users as an Exchange Administrator:

  1. Verify that the EXTERNAL_FRONT_END_SERVER property is set in your TRIRIGAWEB.properties file.
    • If this property is not yet set, then do so, and restart the server.
    • The provided URL must use the HTTPS protocol.
  2. Save the URL address of the add-in manifest XML file.
    • Go to the URL: https://[hostname:port][/context_path]/p/web/outlook/manifest/roomSearch, where [hostname:port] and [/context_path] are the values for your TRIRIGA environment. The [hostname:port] comes from your EXTERNAL_FRONT_END_SERVER property, or any normally used TRIRIGA environment.
    • Copy the URL or save the XML file.
  3. Open your Exchange Admin Center.
  4. Add the custom add-in.
    • Select Organization > Add-ins.
    • Click + (plus sign). Select Add from URL or Add from file.
    • Paste the URL or select the XML add-in manifest file. Click Next. Click Install.
  5. Open the custom add-in as an Outlook User.
    • Click New event. Select ....
    • The ... menu displays a new option for Room Search.
    • Click Room Search to open the add-in.

III. Install the add-in as an Outlook User

Note: The following steps are based on the Office 365 web version of Outlook. Other native or client versions may follow slightly different but similar steps.

Here are the basic steps to install the add-in as an Outlook User:

  1. Verify that the EXTERNAL_FRONT_END_SERVER property is set in your TRIRIGAWEB.properties file.
    • If this property is not yet set, then do so, and restart the server.
    • The provided URL must use the HTTPS protocol.
  2. Save the URL address of the add-in manifest XML file.
    • Go to the URL: https://[hostname:port][/context_path]/p/web/outlook/manifest/roomSearch, where [hostname:port] and [/context_path] are the values for your TRIRIGA environment. The [hostname:port] comes from your EXTERNAL_FRONT_END_SERVER property, or any normally used TRIRIGA environment.
    • Copy the URL or save the XML file.
  3. Open your Outlook calendar.
  4. Add the custom add-in.
    • Click New event. Select ... > Get Add-ins.
    • Select My add-ins. Scroll down to the Custom add-ins section.
    • Select Add a custom add-in > Add from URL or Add from file.
    • Paste the URL or select the XML add-in manifest file. Click OK. Click Install.
  5. Open the custom add-in.
    • Click New event. Select ....
    • The ... menu displays a new option for Room Search.
    • Click Room Search to open the add-in.

IV. Additional Q & A

Q. How do I avoid or resolve issues with displaying or loading the add-in?

A. To avoid add-in display issues, go to your Outlook Preferences > Privacy settings, and select Enable optional connected experiences.

Important: To ensure that the Room Search add-in works correctly on desktop Outlook clients on Windows, you must use the Microsoft WebView2 embedded browsers. For more information, see Browsers used by Office Add-ins.
Google Chrome or Microsoft Edge. If your Room Search add-in users are using the Google Chrome or Microsoft Edge browser, then the SameSite=None;Secure cookie value must be explicitly set in your environment. To mitigate the risks around SameSite=None, (1) set the Content-Security-Policy to frame-ancestors 'self' *.office.com *.office365.com, and (2) set SameSite=None for the JSESSIONID and LTPA cookies only. These values can be configured on the HTTP server or web server.
Tip: As a TAS license user, to resolve the loading issue of the Room Search add-in, add the following to the server.xml file:

<httpSession cookieSameSite="None"/> <webAppSecurity sameSiteCookie="None"/>
<headers id="CSP1">
<set>Content-Security-Policy: frame-ancestors 'self' *.office.com *.office365.com;</set>
</headers>
Also, add the following property to TRIRIGAWEB.properties: 
COOKIE_SAME_SITE=None
Currently, httpSession within server.xml is already set, so make the cookieSameSite configurable by setting the default value to Disabled. For more information, see Server.xml extensions.

Apple Safari. If your Room Search add-in users are using the Apple Safari browser, Safari uses Intelligent Tracking Prevention to block third-party tracking cookies. Because of the way Intelligent Tracking Prevention categorizes cookies, your TRIRIGA server URL may get lumped into this category and that will prevent the add-in from opening when using Outlook Web on Safari. To use the Room Search add-in on Safari, open Safari, go to Preferences > Privacy, and clear the Prevent cross-site tracking setting. Then close your browser, navigate back to Outlook Web, and open the add-in.

Mozilla Firefox. If your Room Search add-in users are using the Mozilla Firefox browser, then certain settings will prevent the floor-plan view from properly rendering. To use the Room Search add-in on Firefox, open Firefox, go to Preferences (or Settings), select Privacy & Security > Custom, and select the Cookies with Cross-site tracking cookies setting. Then close your browser, navigate back to Outlook Web, and open the add-in.

Note: If this Firefox setting is set to Standard (default) or Custom for Cookies with Cross-site tracking cookies, and isolate other cross-site cookies, then the floor plan view will not be properly rendered.

Outlook for Mac. If your Room Search add-in users are using newer versions of the Microsoft Outlook for Mac desktop client (16.58 or later), the client may not display the Room Search add-in when the event is shown in read-only mode. To display the add-in, click the Edit Event button.

Support limitations. While the Room Search add-in is supported on desktops and laptops for Microsoft Windows and Apple Mac, the add-in is not yet supported on mobile devices. The Room Search add-in does not yet have support for accessibility. The Room Search add-in does not support the HTTP response header X-Frame-Options when set to SAMEORIGIN.

Q. By default, from which locations are my meeting rooms displayed?

A.The Room Search add-in displays your meeting rooms according to the following steps:
  1. If your device has enabled location services and you are near a building that is configured on TRIRIGA (set with latitude-longitude and has at least one reservable space that is integrated with Microsoft Exchange), then the add-in sets that building as your initial search filter and displays the meeting rooms in that building.
  2. If no configured building is found in Step 1, then the add-in checks to see if you have a primary location. If so, then from your primary location, the add-in will get the associated building. If the building has at least one reservable space that is integrated with Microsoft Exchange, then the add-in sets that building as your initial search filter and displays the meeting rooms in that building.
  3. If no configured building is found in Step 1 or 2, then the add-in displays all of your favorite meeting rooms, if any.

Q. Which of my meeting rooms are displayed?

A. The Room Search add-in allows you to search for reservable TRIRIGA meeting rooms that are integrated with Microsoft Exchange. The add-in does not search for TRIRIGA workspaces nor reservable TRIRIGA meeting rooms that are not integrated with Exchange.

Q. How do I see all of my favorite meeting rooms?

A. The Room Search add-in displays all of your favorite meeting rooms when no search filters are added.

Q. How do I change the number of available meeting rooms that are displayed per page?

A. By default, the Room Search add-in displays 10 available meeting rooms per page. To change this default value, you can select Tools > System Setup > General > Application Settings. Open the Reservation Settings tab, scroll down to the Perceptive Reserve App Settings section, and specify a new value for the Search Rooms Page Size field.

Q. How do I edit a reservation to add a food or equipment service order?

A. When you create and send an Outlook meeting invitation with TRIRIGA rooms, a room reservation is created in TRIRIGA and the meeting organizer is set as the reservation requester. However, your TRIRIGA user must have an email address that is set as the same email as your Microsoft Exchange account email. This way, when you create an Outlook meeting invitation, TRIRIGA can find your user through the meeting organizer email, and associate your user as the reservation requester.

Open your Outlook Calendar and edit an existing meeting invitation. Open the Room Search add-in. If a reservation exists on TRIRIGA that is associated to this meeting invitation and your TRIRIGA user is associated to the TRIRIGA reservation as the requester, then the add-in will display an Edit reservation button.

Click the Edit reservation button to open the associated reservation in the Room Reservation app. From here, you can add food or equipment service orders to your reservation.

Due to an Outlook JavaScript API limitation on Apple Mac desktops, the Edit reservation button will behave differently if you use the Outlook Desktop Client on a Mac. In this case, the Edit reservation button will always be visible in the Room Search panel. Also, when you click the button, this action will open your list of reservations in the Room Reservation app. The action will not bring you to the specific reservation that is associated to the meeting invitation. You must find the reservation in your list, open it, and edit it.

Q. How do I delete the association between my Microsoft Exchange and TRIRIGA users?

A. If you want to delete the association between your Microsoft Exchange and TRIRIGA users, you can log into TRIRIGA and navigate to Portfolio > People > My Profile. In the My Profile form, open the My Profile tab. Scroll to the My Profile Extension section, select the token with an Extension Type of Outlook 365, and remove the token. By doing this, the one-time authentication into TRIRIGA from the Room Search add-in will be reset. The next time that you open the add-in, it will request for your TRIRIGA user name and password.

Q. Can the Room Search add-in perform a one-time authentication into TRIRIGA?

A. Yes, the Room Search add-in can perform a one-time authentication into TRIRIGA, so that you only need to authenticate for the first time that you open the add-in. If the first authentication is successful, then the Microsoft Exchange user will be bound to the TRIRIGA user from the first login. The next time that you open the add-in, it will automatically authenticate into TRIRIGA and will not request your user name and password again.

To establish this one-time authentication into TRIRIGA, the Room Search add-in uses Microsoft Exchange user identity tokens that are validated and accepted by TRIRIGA when you login for the first time. But if the add-in continues to request the user name and password for every time that it is opened, then you must verify the following:

  1. Verify that the SSL certificate that is used by Exchange is trusted by the application server where TRIRIGA is hosted. TRIRIGA validates the Exchange user identity token that is sent by the add-in, and to do so, TRIRIGA needs to call an Exchange REST service. If the SSL certificate that is used by Exchange is not trusted by the application server where TRIRIGA is hosted, then TRIRIGA cannot validate the token and the one-time authentication is never completed.
  2. Verify that the date and time is accurate on the system that hosts TRIRIGA. The Exchange user identity token is valid for a short period of time. If the date and time for TRIRIGA are not accurate, then TRIRIGA may still reject a token that is otherwise valid.
  3. Verify that the Exchange server names can be resolved by the system that hosts TRIRIGA. TRIRIGA needs to make a call to Exchange to validate the token. The URL to which TRIRIGA sends the request, comes inside the token. If the system cannot resolve the Exchange address that is contained in the URL, then TRIRIGA cannot validate the token and the one-time authentication is never completed.

Q. Are there other authentication requirements?

A. Depending on your TRIRIGA configuration for SAML SSO, the initial authentication might require the server or Service Provider (SP) to automatically redirect your users to the Identity Provider (IdP). This configuration is commonly known as SP-initiated SAML SSO. For guidance and examples of SAML SSO configurations, see Examples of configuring SSO.

Q. Where can I find other important information?

A. For important information and known limitations, see the IBM TRIRIGA Release Notes for 11.0 and 4.0. As of April 21, 2020, Office 365 is now renamed Microsoft 365.