To ensure convenient access to meeting rooms for all employees and optimize the usage of those rooms, Mapiq's Room Calendar Integration offers transparency regarding the booking and utilization of your available meeting spaces. Integrating your M365 room calendars with Mapiq, we aim to help you streamline your office usage by providing insights into how bookable rooms are reserved and utilized.
In this article, we'll guide you through the technical details of the integration and help you assess its security, privacy, and implementation aspects.
Functionality Overview
The Room Calendar Integration offers Mapiq real-time and secure access to room calendars. This integration ensures user privacy and protects confidential data, such as meeting titles, descriptions, and attachments. By securely accessing room calendars, Mapiq can provide valuable insights into the usage of shared facilities, especially when combined with sensor data.
The Room Calendar Integration offers several key insights and functionalities, including:
Real-time access to room calendars, along with historical data.
Insights into booking rates, groups using rooms, and ad hoc vs. planned meetings.
Information on your most and least popular meeting rooms based on booking data.
Learn more about these new insights here:
Note: While the Room Calendar Integration provides these benefits, room booking via Mapiq still requires the use of the Personal Calendar Integration.
Setting Up the Room Calendar Integration
The process of seamlessly integrating Mapiq with room calendars in Microsoft 365 involves collaboration between key roles within your organization. The integration relies on the Microsoft Graph API, requiring specific permissions and actions from designated personnel.
Here is a guide to enable and configure the integration respective to the role someone holds:
Mapiq (Subscription) Administrator Role:
A Mapiq administrator with Subscription Administrator permissions in the Mapiq platform initiates and completes the installation flow through the Mapiq Admin Portal.
Exchange Administrator (or Global Administrator) Role:
An Exchange Administrator or Global Administrator in your organization's Microsoft 365 environment is needed to grant RBAC (Role-Based Access Control) permissions using PowerShell.
Microsoft Administrator Role:
Depending on your organization's Microsoft 365 consent settings, a Microsoft Administrator with either (Cloud) Application Administrator or Global Administrator permissions is required to Install the Enterprise Application in your organization's tenant.
⚠️ Note that in some organizations, any user may perform this step.
Once you have all the necessary personnel with the required level of access - both within Mapiq and your organization's Microsoft tenant - follow the steps below to enable and configure the integration:
Step 1: Install the Enterprise Application in M365
Administrators can kickstart the installation process from the Mapiq Admin portal, guided by Microsoft's consent wizard.
Follow the steps below to kickstart the installation process:
Sign in to admin.mapiq.com with an account that holds the Mapiq Subscription Administrator role.
Navigate to the Settings tab and access the Integrations settings from the left menu.
Find the "Room calendar synchronization" section.
Click "Add tenant".
Continue with the steps below to Install the Enterprise Application in M356:
Login to your Microsoft tenant by clicking the "Login to connect your tenant" button.
You will be redirected to the Microsoft Identity platform – select your account.
You will be shown the consent screen.
Depending on your organization's settings and your own role within your organization, you will be able to accept the consent. This will install the Mapiq Room Calendar application into your organization's Microsoft 365 tenant and bring you back to the Mapiq admin portal – the first step is complete.
Suppose you don't have permission to install the application in your organization's Microsoft 365 tenant. In that case, you will need to request an administrator in your Microsoft 365 environment to perform the admin consent for you. The admin can do this by directly navigating to the admin consent screen using this link: Admin Consent
Once the admin has accepted the permissions, you can complete Step 1 in the installation process.
Note: Installing the Enterprise Application alone does not give Mapiq access to any data in your tenant yet.
In the next step, you can assign fine-grained permissions using Application Role-Based Access Control (RBAC) in Exchange Online.
We need to get a reference to the security group which was created in Azure AD.
$SecurityGroup = Get-Group -Identity "Name of security group in AD"
Step 2: Configure RBAC Permissions
The Enterprise Application, by default, has no access to resources. It relies on the use of Role Based Access Control (RBAC) for Applications in Exchange Online to get access to the desired calendar resources, allowing fine-grained control of the roles and scopes.
Administrators can whitelist rooms to which Mapiq should have access by configuring 'Calendars.ReadWrite (Application)' role, granted through RBAC for Applications:
Read Permission is required to get access to existing meetings in the calendar. This allows the integration to synchronize these meetings with Mapiq and show the status of a room in the app.
*Write Permission is required to act on behalf of the calendar. This would allow the integration to decline a meeting, for example, in a no-show case.
*Currently, we don't intend to use write permissions, but in future updates, we may introduce features requiring such permissions. We're asking for both read and write permissions now, so when those features are added, you won't have to adjust any settings to use them.
Note: Make sure to grant this permission to all room calendars you would like to integrate with Mapiq.
This access can be configured using Role Based Access Control (RBAC) for Applications in Exchange Online, which allows for precise control of the roles and the scopes to which an application has access. Configuring RBAC permissions can be done using Powershell by creating a role assignment. A role assignment grants an application a specific role on a particular resource scope.
The Configuration of the RBAC permissions is done in PowerShell and involves the following steps:
Create a Service Principal in Exchange Online
This will create a pointer in Exchange Online to the Enterprise Application installed in your M365 Azure AD tenant.
Use the
'New-ServicePrincipal'Powershell command to create a new service principal.Example - Creating a new service principle
New-ServicePrincipal -AppId <Client Application ID in AAD> -ObjectId <Service principal object ID in AAD> -DisplayName <name>
The'AppId'and'ObjectId'can be found within the details of the Enterprise Application (installed in Step 1) in your Azure AD portal. Alternatively, you can find these IDs by querying the Microsoft Graph using the following Powershell commands:
# Connect to the Microsoft Graph and retrieve the relevant service principal
Connect-MgGraph -Scopes 'Application.Read.All'
Get-MgServicePrincipal -Filter "DisplayName eq 'Mapiq Room Calendar Integration'"Create a Management Scope
This allows you to scope a set of mailboxes based on the properties of the mailboxes. Use the
'New-ManagementScope'Powershell command.An example would be to create a scope based on group membership, which is creating a mail-enabled security group that contains all mailboxes you want to share with Mapiq. Then, create a management scope that filters all mailboxes in this group. Using a mail-enabled security group is just one example; you can also use other types of filters to create a management scope.
Example - Creating a management scope based on security group membership
$ManagementScope = New-ManagementScope -Name 'Mapiq Room Calendars Scope' -RecipientRestrictionFilter "(MemberOfGroup -eq '$($SecurityGroup.DistinguishedName)') -and (RecipientTypeDetails -eq 'RoomMailbox')"
Example - Creating a management scope based on country or region
$ManagementScope = New-ManagementScope -Name 'Mapiq Room Calendars Scope' -RecipientRestrictionFilter "(CountryOrRegion -eq 'NL') -and (RecipientTypeDetails -eq 'RoomMailbox')"
For further details, refer to the Microsoft documentation: Define Resource Scope
Create a Role Assignment
This ties together the application, the scope, and the role the principal has within that scope. Use the
'New-ManagementRoleAssignment'Powershell command to create the role assignment.The
'App'argument corresponds to the'ObjectId'of the service principal you created earlier using'New-ServicePrincipal', and the'CustomResourceScope'corresponds to the management scope you created in the previous step.Example - Creating a role assignment
New-ManagementRoleAssignment -App <ObjectId of Service Principal you created> -Role "Application Calendars.ReadWrite" -CustomResourceScope <Name of Management Scope you created>
Step 3: Complete the Installation
After configuring RBAC permissions in your Exchange Online environment, proceed to the Mapiq Admin portal to complete the installation. Locate the pending installation in the admin portal and click the "Continue setup" button. Confirm that the permissions in Microsoft 365 (Exchange Online) have been properly configured, then click on the "Synchronize room calendars" button.
Once the installation is successful, Mapiq will initiate the synchronization process for rooms that are connected with Mapiq. The integration utilizes change notifications provided by Microsoft Graph to stay updated with any changes in the room calendars. This enables Mapiq to respond to calendar changes in almost real-time.
Further Resources
Complete Example - Using a Scope on a Mail-Enabled Security Group
The script snippet below provides a complete example of configuring permissions, including all necessary steps. This example utilizes a mail-enabled security group to define the resource scope and assumes that group membership has already been set up:
# Connect to the Microsoft Graph and retrieve the relevant service principal
Connect-MgGraph -Scopes 'Application.Read.All'
$ServicePrincipalAad = Get-MgServicePrincipal -Filter "DisplayName eq 'Mapiq Room Calendar Integration'"
Write-Host "AAD service principal '$($ServicePrincipalAad.DisplayName)' with Id '$($ServicePrincipalAad.Id)' and AppId '$($ServicePrincipalAad.AppId)'"
# Connect to Exchange Online and create the new service principal
Connect-ExchangeOnline
$ServicePrincipalExchangeOnline = New-ServicePrincipal -AppId $ServicePrincipalAad.AppId -ObjectId $ServicePrincipalAad.Id -DisplayName $ServicePrincipalAad.DisplayName
# Create the security group in Exchange Online
$SecurityGroup = New-DistributionGroup -Name "Mapiq Room Calendars" -Type "Security" -Alias "mapiq-room-calendars"
# Note that this does not include owner or member assignment! This can be achieved via PowerShell as well or via the admin portal.
# Create the management scope based on security group membership
$ManagementScope = New-ManagementScope -Name 'Mapiq Room Calendars Scope' -RecipientRestrictionFilter "(MemberOfGroup -eq '$($SecurityGroup.DistinguishedName)') -and (RecipientTypeDetails -eq 'RoomMailbox')"
# Display the room calendars linked to the management scope (will be empty if no members have been assigned yet)
Get-Recipient -RecipientPreviewFilter $ManagementScope.RecipientFilter
# Assign the required permissions
New-ManagementRoleAssignment -App $ServicePrincipalExchangeOnline.ObjectId -Role "Application Calendars.ReadWrite" -CustomResourceScope $ManagementScope.Name
Privacy & Security
The Room Calendar Integration allows Mapiq to gather information about room usage. However, sensitive details like meeting titles, invite text, attachments, etc., are not accessible.
If you would like to learn more, you can visit the Room Calendar Integration article.
Data Visibility
Data from room calendars can be viewed in the analytics tab of Mapiq's admin portal. As an administrator, you will find statistics on meeting room utilization, including no-show and ad-hoc meet-up data (if occupancy sensors are connected to those rooms).
Only meeting room calendars connected to the Mapiq platform will be visible. To link your M356 meeting room calendars to Mapiq, add the meeting room's email address to the corresponding Mapiq Meeting Room under the Building Tab.
If the meeting room calendars in your M365 setup are not linked to a room or the correct room in the Mapiq platform, Mapiq will not be able to track or sync them.
Multiple Microsoft Tenants
The Room Calendar Integration supports synchronization with multiple Microsoft tenants. Suppose you have meeting rooms configured in different Microsoft tenants within your Mapiq subscription. In that case, please follow the steps mentioned above for each Microsoft tenant you want to integrate with.
Note: The Personal Calendar Integration still only supports one Microsoft or Google tenant.
💬 Need More Help?
If you’d like extra assistance, reach out via the Messenger (question mark in the corner) and chat with our support team, or email us at [email protected].
We’re always ready to help! 😉