This article is part of the complete 'External calendar integration (Outlook/Google Calendar)' documentation. For a complete overview, see: External calendar integration (Outlook/Google Calendar)
This document describes the actions that need to be performed in Microsoft Exchange and Microsoft Azure to implement the Reservation Sync Interface for Spacewell Workplace Management.
1. Scope
This configuration guide is applicable for Microsoft 365 Exchange Online including hybrid* Exchange setups. This configuration guide is not applicable for on-premise Exchange servers.
2. Who is this document for?
Microsoft Exchange Administrator who will configure the Exchange Online environment for the Reservation Sync Interface.
Microsoft Azure Administrator who will configure access to the Reservation Sync Interface as a registered application in Azure Portal.
Information Security Official who will review the administrative actions performed on the customer’s side as part of the above two roles.
3. Exchange configuration
The following steps implement and/or validate settings in Microsoft Exchange Online that are required by the Reservation Sync Interface to establish connectivity with Spacewell Workplace.
The following steps require administrator access to Exchange Online, ensure your Microsoft account has the necessary access rights.
3.1 Pre-requisites
3.1.1 How to access Exchange Admin Center
Exchange Admin Center (EAC) is the Web Console to manage Microsoft Exchange Online and can be accessed via: https://admin.exchange.microsoft.com/
More information about EAC can be found here: https://learn.microsoft.com/en-us/exchange/exchange-admin-center.
3.1.2 How to access Exchange Admin Shell
Exchange Admin Shell is shell access (via command line) to a remote Exchange instance, in this case Exchange Online. To connect to Exchange Admin Shell, you will need PowerShell and internet access.
Launch (Windows) PowerShell as an Administrator and install Exchange Online PowerShell Module by executing the following command:
Set-ExecutionPolicy RemoteSigned
Confirm that the executed scripts come from a trusted source with [Y] Yes and then Enter.
Execute the next command:
Install-Module -Name ExchangeOnlineManagement
This command will download and install the Exchange Online PowerShell module. Confirm with [Y] Yes and then Enter.
Connect to Exchange Online via the following command, replace the UserPrincipalName with your own administrators UserPrincipalName:
Connect-ExchangeOnline -UserPrincipalName johnsmith@contoso.onmicrosoft.com
The Microsoft 'Sign in to your account' popup appears:
Enter the administrators password and confirm with Enter.
If 2FA is enabled, there is a confirmation required from the Microsoft Authenticator App.
In Powershell the following screen is visible and the user is logged in to Exchange Online PowerShell:
Verify the domain by executing the following command:
Get-AcceptedDomain
Logging out or disconnection the Exchange Online PowerShell via the following command and confirm with [Y] Yes and then Enter:
Disconnect-ExchangeOnline
More information about connecting to Exchange Online PowerShell can be found here: https://learn.microsoft.com/en-us/powershell/exchange/connect-to-exchange-online-powershell?view=exchange-ps&preserve-view=true
3.2 Room Mailboxes
Room mailboxes are key to setting up sync between Workplace and Exchange. For each room defined in Workplace which can be reserved, there must be a corresponding room mailbox defined in Exchange.
3.2.1 Creating Room Mailbox
Room mailboxes are resource mailboxes that can be created either via Exchange Admin Center or Exchange Admin Shell. Unlike user mailboxes, resource mailboxes are not linked to Microsoft 365 user licenses or incur any costs, they are bundled with all Microsoft 365 subscriptions and an unlimited number of such resource mailboxes can be created.
Room mailboxes can be created manually through the Exchange Admin Center or using PowerShell. Both options are described below. Please select the method that most adheres to your current workflow.
Create a Room Mailbox via Exchange Admin Center
Login to Exchange Admin Center, and select Resources from the left side menu under the Recipients menu:
This shows list of all available room mailboxes in your Exchange subscription. Click on Add a room resource:
This opens a dialog for new Room Mailbox parameters. Provide a suitable name and email address for the room mailbox and click Next:
The next screen allows you to configure some additional properties for the room mailbox. These are optional properties that are not required for Reservation Sync Interface so they can be skipped, however if you have a large number of rooms then these properties can help users find the right room for their purpose using Outlook Room Finder:
Onto the next section, Booking Options, these settings have great impact on the Reservation Sync Interface, it is recommended to leave these settings at default values or otherwise match the configuration of the rooms in Workplace Management. These settings are discussed in greater detail in the below section 3.2.2
On the next screen, we can review the configured properties for the room mailbox and then click on Create to finish creating the room mailbox:
Once the room mailbox is created, you can see the room mailbox in the list of Resources:
Create a Room Mailbox via Exchange Admin Shell (PowerShell)
Connect to Exchange Admin Shell and issue the below command to create a new Room Mailbox with the below command:
New-Mailbox -Name "Conference Room" -alias conf_room -Room
The parameter -Name is used to set the display name of the Room in Outlook and Teams
The parameter -alias is used to generate the email address, e.g. in the above case it will be conf_room@yourdomain.com
The parameter -Room is most important, which identifies it as a Room resource mailbox and not a User account.
Once, the room is created, you can verify it by using the below command:
Get-Mailbox -Identity conf_room
The -Identity parameter value is the same as the -alias used in the create command above.
3.2.2 Fine-tuning Room Mailbox properties
Room mailboxes in Exchange Online have an extensive set of properties that determine how they automatically deal with meeting requests from users (auto-accept/decline) for example. These properties also impact the Reservation Sync Interface as well. While some of these properties are controllable from the Exchange Admin Center, more advanced configuration can be achieved from Exchange Admin Shell using the CalendarProcessing command.
To retrieve the current values for a given room mailbox use the below command:
Get-CalendarProcessing -Identity conf_room | format-list
The -Identity parameter is the alias of the room mailbox, you can also use email address here (conf_room or conf_room@yourdomain.com).
The format-list option ensures that PowerShell displays the extensive list of properties for the room mailbox:
The settings mentioned below are important for the Reservation Sync:
It is important that the settings in Exchange are aligned with settings in Workplace Management. For example, if the BookingWindowInDays of the meeting room is set to 180 in Exchange, but in Workplace Management you can reserve up to 2 years into the future, the meetings created from Workplace Management will not be synced to Exchange.
AutomateProcessing
This parameter decides if the meeting requests from users are automatically accepted by the room mailbox or delegated to a user who is the room admin. If you have not specified any booking delegates in the room mailbox setting, then this should be set to AutoAccept.
BookingWindowInDays
This parameter decides how far ahead in future the room can be booked. This value is by default 180. Make sure this setting is in line with the meeting rooms setting in Spacewell Workplace.
ConflictPercentageAllowed
This parameter determines if the room is unavailable for a few occurrences of a recurring series, but is available for the majority of it then it should still accept the series as a whole or not. If this setting is set to 0%, a recurring reservation is declined, if at least 1 conflict occurs. Make sure this setting is set properly to prevent out-of-sync situations.
Delete Subject & AddOrganizerToSubject
By default, when a room mailbox receives a meeting, it removes the subject when saving the invite in its calendar. Consequently the meetings subject is also not synchronized to Spacewell and the Spacewell touchpoints display the Organizer’s name instead of the subject.
If it is so desirable that subjects be displayed in Spacewell Workplace, then both of these parameters must be set to False. To set these values you can use the below command:
Set-CalendarProcessing -Identity conf_room -DeleteSubject $False -AddOrganizerToSubject $False
Verify the change by running the Get-CalendarProcessing command of the particular meeting room again.
RemovePrivateProperty
This parameter determines if the meetings 'Private' flag is removed for incoming meetings. The default value in Exchange for every room mailbox is true. This means that the ‘Private’ flag of an incoming meeting is removed, making it not private (or confidential) anymore. This value needs to be set to false to have confidential meetings created in Workplace also Private in Outlook.
Set-CalendarProcessing -Identity conf_room -RemovePrivateProperty $False
A complete list of Calendar Processing properties can be found here with more detailed explanation:
https://learn.microsoft.com/en-us/powershell/module/exchange/set-calendarprocessing?view=exchange-ps
3.3 Room Lists
Room lists are used for grouping Room mailboxes into logical groups. These are not same as distribution lists, shared mailboxes or security groups. Room lists can be created via the Exchange Admin Shell and are needed to link the Room lists room mailboxes to the corresponding reservable rooms in Workplace Management. Also the Room lists are used for grouping rooms for the Outlook Room Finder.
Reservation Sync Interface requires that the Exchange has at-least one room list and the room list is visible.
Reservation Sync Interface accesses the Rooms and Room Lists via Microsoft Graph API. Sometimes it may take 24-48 hours for room data created via Exchange Admin Shell to reflect in the API depending on the Azure cloud region / availability zone the data is being created in.
3.3.1 Creating Room List
To create a new Room List, use the below command:
New-DistributionGroup -Name "All Rooms" -Alias all_rooms -RoomList
The -Name parameter is used to specify the display name of the Room List as how it appears in Outlook Room Finder
The -Alias parameter is used to generate the email address which will later be used by the Reservation
Sync Interface
The -RoomList parameter is used to identify this group as a Room List
More informatioin about the Room Lists can be found here:
https://learn.microsoft.com/en-us/powershell/module/exchange/new-distributiongroup?view=exchange-ps
3.3.2 Adding Room Mailbox to Room List
Once you have created a Room List, you now need to add room mailboxes to this list via the below command:
Add-DistributionGroupMember -Identity all_rooms -Member conf_room
The -Identity parameter is the alias or email address of the room list
The -Member parameter is the alias or email address of the room mailbox. This can also be another room list
To verify the addition of the member, run the below command
Get-DistributionGroupMember -Identity all_rooms
3.3.3 Removing Room Mailbox from Room List
To remove a room mailbox from a Room List, use the below command:
Remove-DistributionGroupMember -Identity all_rooms -Member conf_room
The -Identity parameter is the alias or email address of the room list
The -Member parameter is the alias or email address of the room mailbox. This can also be another room list
3.3.4 Listing Room Lists
To get a list of all Room Lists in your organization, use the below command:
Get-DistributionGroup -ResultSize Unlimited | Where {$_.RecipientTypeDetails -eq "RoomList"} | Format-Table DisplayName,Identity,PrimarySmtpAddress –AutoSize
The -ResultSize Unlimited parameter ensures that all the room lists are returned
The Where clause filters the list to only Room lists and not other types of groups
The Format-Table formats the output to a table structure with 3 columns: DisplayName, Identity and Email address
The -AutoSize parameter resizes column widths in the output to match the data
3.3.5 Listing contents of a Room List
To view all the member rooms and room lists for a given room list, use the below command
Get-DistributionGroupMember -Identity all_rooms -ResultSize Unlimited | Format-Table DisplayName,Identity,PrimarySmtpAddress –AutoSize
The -Identity parameter is the alias of the room list whose members are to be fetched
4. Azure Portal configuration
The following steps grant access to the Microsoft Exchange Online environment using the Graph API, so Reservation Sync Interface can interact with it. Graph is the standard interface provided by Microsoft for programatically managing Exchange Online and replaces the erstwhile Exchange Web Services (EWS). It uses OData REST APIs and OAuth 2.0 with Client Credentials
The following steps require administrative access to Azure AD, ensure your Microsoft account has the necessary administrative privileges
4.1 App Registration
You must register Spacewell Reservation Sync Interface as an App in Azure AD/Entra ID for API access.
To register an App, login to Azure Portal. Then navigate to Microsoft Entra ID in the menu on the left:
Go to App registrations:
On the App registrations page, click on New registration:
The Register an Application screen is presented.
Enter a Name for this App
Leave the default option Accounts in this organizational directory only under the header Supported account types as it is.
Redirect URI can be left empty
Click on Register to finish creating the App:
Once the App is created, you will be redirected to the overview screen of the App.
Copy the Application (client) ID and the Directory (tenant) ID and keep them somewhere save. This information is needed later on in the configuration guide.
An App created via the above steps will be (by default) not be visible to users in the Office 365 portal or Teams under the My Apps section. This is a background App and is not intended for end-users. There is no need to assign this app to any Users or Groups
4.2 Generate a Client Secret
The next step is to generate a client secret for API access. Go to the overview of the App and click on Certificates and secrets from the left side menu:
On the center panel, click on New client secret:
This will pop-up a panel on the right side, enter a Description and set an Expires value for the secret and click on Add below:
The secret expiry duration can be set to any value as per your organizational policy.
You can now see the newly created secret in the list of client secrets for the App. Copy the Expires and the Value and keep them somewhere save. This information is needed later on in the configuration guide.
4.3 Grant API access
To grant access to the App, select API permissions from the left side menu:
Then click on Add a permission in the center panel:
This will open a pop-up panel on the right side. Select Microsoft Graph:
In the next screen, select Application permissions:
Via the Select permissions search box, the relevant permissions can be found.
Add the following permissions:
Calendars.Read
Calendars.ReadBasic.All
Calendars.ReadWrite
MailboxSettings.Read
Place.Read.All
Click on Add permissions when all permissions mentioned above are selected:
The above permissions grants access to basic details of a meeting such as meeting schedule, organizer, participants and subject. It does not grant access to other details such meeting body, attachments, free-busy information of users.
You can now see the added permissions in the list of Configured permissions for the App in the center panel:
More information about App permissions can be found here: https://learn.microsoft.com/en-us/graph/auth-v2-service
4.3.1 User TimeZone preferences
This section is only if you are using Outlook 2013 or below
Reservation Sync creates/updates meetings in UTC timezone by default in Exchange. Normally all Outlook/Teams touchpoints automatically convert and display times to all participants in their own local timezone, however some legacy touchpoints such as Outlook 2013 and below are unable to do this and display the time in source timezone (UTC), leading to confusion.
The MailboxSettings.Read permission makes sure the organizers preferred timezone can be accessed.
4.3.2 Restricting access to APIs
A Security Group can be used to limit the access to the users and recources. For the Reservation Sync Interface it is necesarry to create a security group and add all the room recources to this group.
Connect to Exchange Admin Shell and enter the following command:
New-DistributionGroup -Name "Only Rooms Security Group" -Alias all_rooms_sg -Type security
The -Type parameter security defines this group as a mail enabled security group
The -Alias parameter defines the email address of the group
Add room mailboxes to the security group with the below command:
Add-DistributionGroupMember -Identity all_rooms_sg -Member conf_room
The -Identity parameter is the alias of the security group
The -Member parameter is the alias of the room mailbox
Enter the above command for every Room in scope.
Now create an Access Policy with the below command:
New-ApplicationAccessPolicy -AppId 5002196d-7934-4f85-98ed-d65a0f249aff -PolicyScopeGroupId all_rooms_sg@spacewelltest.onmicrosoft.com -AccessRight RestrictAccess -Description "Restrict Reservation Sync Interface to Room mailboxes"
The -AppId parameter is the Application (client) ID of the App as registered in chapter 4.1
The -PolicyScopeGroupId parameter is the email of the security group we created above
The -AccessRight parameter RestrictAccess ensures that the access is restrictive and limited to the policy scope
The -Description parameters is the description of the access policy
More details about API access policy here
https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access
4.4 Grant Admin Consent
The calendar data processed by Reservation Sync using Graph API as identified in chapter 4.3, qualifies as Personal Identifiable Information (PII) data as hence processing such data requires User Consent under EU GDPR regulations. Since this is a background application it cannot seek user consent directly from the user hence an administrator must consent to data processing upfront on behalf of all users. This Admin Consent is facilitated and required by Microsoft Graph before API can be used.
Navigate to the API permissions screen of the App. There are two columns relevant: Admin consent required and Status (with the warning sign). These tell us that the permissions qualify as PII and there need to be an admin consent before the API can be used.
Select Grant admin constent for <organization name>
Confirm the grant admin consent by clicking Yes:
The Status and the sign now have changed for each of the permissions:
4.5 Share Credentials
Upon completing the above steps, the credentials generated for the App must now be shared securely with Spacewell Integration team which will then be configured in the Reservation Sync interface for automated API access. The following details must be shared in the given format
Attribute | Value |
|---|---|
Application ID | Application (client) ID (obtained in chapter 4.1) |
Directory ID | Directory (tenant) ID (obtained in chapter 4.1) |
Client Secret | Client secret (obtained in chapter 4.2) |
Client Secret Expiry Date | Client secret expiry date (obtained in chapter 4.2) |
Email Domains | Email domains (e.g. spacewell.com) |
It is recommended that the Client Secret is shared securely. A single-use expirable link can be a good way to share this information.
A secure link can be created via for example: https://onetimesecret.com/?locale=en
Enter the Client Secret in the Secret content goes here text box
Enter a passphrase
Enter a lifetime of the secret link
Click on Create a secret link
Share the link with Spacewell Integration Team
Share the passphrase Spacewell Integration Team
Share the secret link, the passphrase and the other information mentioned above and mail it to integration@spacewell.com. Use your organization name and the Application ID in the email subject.
If we find that the link has been already used, we will ask you to delete the secret generated in chapter 4.2 and repeat the process of generating a new client secret.
This is just a recommended approach to securely share credentials. You can alternately follow any other secure information transmission channel of your choice and policy.
Appendix
* Hybrid means that the room mailboxes are cloud native and user mailboxes may be synchronized with an on-premise Exchange Server. Also see which scenario’s Microsoft supports in regards to Hybrid setups: https://techcommunity.microsoft.com/t5/exchange-team-blog/the-end-of-the-rest-api-for-on-premises-mailboxes-preview/ba-p/3221219
Exchange Admin Shell cmdlet reference documentation https://learn.microsoft.com/en-us/powershell/module/exchange/?view=exchange-ps
Microsoft Graph API reference https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
Authentication and Authorization process of Microsoft Graph https://learn.microsoft.com/en-us/graph/auth/?context=graph%2Fapi%2F1.0&view=graph-rest-1.0