# Exchange app ## Exchange App #### Eliona app for Microsoft Exchange booking integration > Create a room list in Exchange, make these rooms available in Eliona as bookable assets, and allow users to book the rooms directly via Eliona. ### Configuration of Exchange Web Services (EWS) Follow these steps for Exchange Online and hybrid installations where user emails are stored in Exchange Online. *For on-premises installation of the Exchange server or a hybrid configuration with on-premises primary accounts, skip this chapter and only obtain the NTLM credentials and the EWS API URL.* > Please note that EWS for Exchange Online will be discontinued on October 1, 2026. This does not affect on-premises Exchange servers and hybrid configurations. More details about the discontinuation can be found in the [Exchange Team Blog](https://techcommunity.microsoft.com/t5/exchange-team-blog/retirement-of-exchange-web-services-in-exchange-online/ba-p/3924440). #### Application registration in Microsoft Entra To configure EWS with the Exchange app, follow the steps below to register it in Microsoft Entra. **1. Application registration** Navigate to **Entra** and select **App registrations**, then select **Register app**. You must enter the application details. **2. Permission configuration** **Application authentication (Impersonation)** For application authentication that supports impersonation: * Go to **API permissions**. * Add the permission `full_access_as_app` and grant admin consent. Here is an example of the required configuration in the application manifest: ```json "requiredResourceAccess": [ { "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40", "type": "Role" } ] } ] ``` **3. Generating secrets for authentication** To authenticate the application: * Navigate to **Certificates & secrets** in Entra. * Select **New client secret**. * Store the generated secret securely, as it is required to authenticate the application with Microsoft services. **Configuring impersonation via PowerShell** To configure impersonation and other settings that are not available in the Entra portal, you must use PowerShell. Note that an online PowerShell console without a subscription is not available. Local PowerShell installations on Windows, Linux, or macOS can manage these configurations: * Make sure the necessary PowerShell modules for managing Exchange are installed. * Use scripts to configure impersonation rights or other Exchange-specific settings. **PowerShell scripts for configuring impersonation** 1. **Connect to Exchange Online PowerShell**: ```powershell $UserCredential = Get-Credential $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection Import-PSSession $Session -DisableNameChecking ``` 2. **Assign impersonation rights**: ```powershell New-ManagementRoleAssignment –Name:impersonationAssignmentName –Role:ApplicationImpersonation –User:serviceAccount ``` 3. **Verify impersonation rights**: ```powershell Get-ManagementRoleAssignment –RoleAssignee serviceAccount –Role ApplicationImpersonation –RoleAssigneeType User ``` Replace `serviceAccount` with the name of your service account or user that will perform the impersonation. **Disconnecting the PowerShell session** Remember to close the PowerShell session once your configuration tasks are complete: ```powershell Remove-PSSession $Session ``` ### Installation The Exchange app is installed via the app store in Eliona. ### Assets The Exchange app automatically creates all rooms in the configured room list. Once a room has been created in Eliona, it remains there even if it is removed from the room list (but bookings will no longer be synchronized). A room can be renamed or deleted independently in Eliona. Whenever a new room is added to the room list, it is created in Eliona. ### Configuration The Exchange app is configured by defining one or more authentication credentials: | Attribute | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `clientID` | ClientID obtained in the Entra admin center. (Only for OAuth authentication) | | `clientSecret` | ClientSecret obtained in the Entra admin center. (Only for OAuth authentication) | | `tenantID` | ID of the Exchange Online organization (Only for OAuth authentication) | | `ewsURL` | URL of the EWS API (only for NTLM authentication) | | `username` | NTLM username (only for NTLM authentication) | | `password` | NTLM password (only for NTLM authentication) | | `serviceUserUPN` | Email address of the service user (for querying rooms, creating anonymous bookings, ...) | | `roomListUPN` | Email of the room list containing the rooms to be synchronized. CAC will be disabled if left empty. | | `bookingAppURL` | URL of the booking app. Use the one from the example below. | | `enable` | Flag to enable or disable fetching this configuration. | | `refreshInterval` | Interval in seconds for room discovery. | | `requestTimeout` | API query timeout in seconds | | `projectIDs` | List of Eliona project IDs for which this app should collect data. For each project ID, all assets are automatically created in Eliona. | Configuration is done using a corresponding JSON structure. As an example, the following JSON structure can be used to define an endpoint for app permissions: ```json { "clientId": "01234567-89ab-cdef-0123-456789abcdef", "clientSecret": "random-cl13nt-s3cr3t", "tenantId": "01234567-89ab-cdef-0123-456789abcdef", "ewsURL": "https://outlook.office365.com/EWS/Exchange.asmx", "username": "username", "password": "password", "serviceUserUPN": "eliona@example.com", "roomListUPN": "first.floor@example.com", "bookingAppURL": "http://booking:3000/v1", "enable": true, "refreshInterval": 60, "requestTimeout": 120, "projectIDs": [ "10" ] } ``` Configurations can be created in Eliona using this structure under `Apps > Exchange app > Settings` . To do this, select the /configs endpoint with the POST method. After configuration is complete, the app starts continuous asset creation. Once all detected rooms have been created, the user is informed via Eliona's notification system. ### Booking synchronization If the Exchange app and booking app are properly configured, bookings are synchronized in both directions between the Exchange server and Eliona. Bookings in Eliona must be made on the assets created by continuous asset creation. Changes and cancellations from either the Exchange server or Eliona are also synchronized with the other service. If an error occurs during synchronization from Eliona to Exchange (typically when the room does not accept the invitation), the user is informed about the issue via Eliona notifications and the booking in Eliona is canceled. If the booking is made by a user without an Exchange account (or an ad-hoc booking), the booking is performed by the service user. ### Booking time When creating or deleting a booking from Eliona, the booking becomes visible in Outlook within a few seconds. Changes in Outlook are synchronized with Eliona every `refreshInterval` seconds. ### Recurring events Recurring events can be created in Outlook. All occurrences are passed on to Eliona and synchronized. Users in Eliona can cancel specific occurrences. Note that there is a limit to how far in advance resources can be booked. The limit can be configured in Exchange administration for the resources. ### Booking multiple assets While the booking frontend does not allow multiple assets to be booked at the same time booking. Outlook does allow this. The app synchronizes the multiple booking in Eliona and the event can be modified or canceled.