Matrix Booking's Microsoft 365 integration setup guide

This technical guide explains the steps required to set up our bidirectional Microsoft 365 integration. For more information on our integration, see Microsoft 365 integrations overview.

Contents

Set up our integration in Microsoft Azure

There are several steps needed to set up our Microsoft 365 integration, on both the Microsoft and Matrix Booking sides. Some steps need to be done by your IT team, some by your Matrix Booking Administrators, and some steps by our Support Team.

In Microsoft Azure, your IT team need to:

In Matrix Booking, your Matrix Booking Administrators need to:

Note: if you want your colleagues to use our Microsoft 365 add-in, contact your Account Manager and subscribe. Afterwards, ask your IT team to install the add-in.

Set up SSO or Microsoft Entra ID in Microsoft Azure first if needed

Matrix Booking uses Microsoft Azure applications for SSO and Entra ID (formerly Active Directory). If you’re using either our SSO or Entra ID integrations, you need to set up the integrations first.

For SSO to work, make an Enterprise Application for Matrix Booking. It will have the API permissions needed so that you can add our Microsoft 365 integration to it.

You can set up SSO afterwards, but you’ll have 2 separate applications.

Register Matrix Booking as an application

If you’re using either SSO or Entra ID and they have been set up, you can reuse the existing application within the Enterprise Application. If you’re reusing an existing application, you need to log in to Microsoft's Azure Portal as an Administrator and note these 2 pieces of information from the existing application:

Application (client) ID.
Directory (tenant) ID.

To add Matrix Booking to your Microsoft Azure tenant as a client application:

Select Microsoft Entra ID from the side menu. The Overview screen will appear.
Select the + Add drop-down list. The + Add drop-down list will appear.
Select App registration from the Manage drop-down list. The Register an application screen will appear.
In the Name text box, enter “Matrix Booking”.
Select the Accounts in this organisational directory only (single tenant) option.
Select the Select a platform drop-down list. The Select a platform drop-down list will appear.
Select Web from the drop-down list.
In the Redirect URL text box, enter “https://app.matrixbooking.com”.
Select Register.
This will take you to the Matrix Booking Overview screen.
Take note of the:
- Application (client) ID.
- Directory (tenant) ID.

Note: for more information, see Microsoft’s guidance on registering an application.

Set the required permissions

To set the required permissions:

Select Microsoft Entra ID from the side menu. The Overview screen will appear.
Select the Manage drop-down list from the Overview screen’s side menu. The Manage drop-down list will appear.
Select App registrations from the drop-down list.
Select Matrix Booking. The Matrix Booking Overview screen will appear.
Select the Manage drop-down list from the Matrix Booking Overview screen’s side menu. The Manage drop-down list will appear.
Select API permissions from the drop-down list. The API permissions screen will appear.
Select + Add a permission. The Request API permissions screen will appear.
Select Microsoft Graph.
Select Application permissions.
In the Start typing a permission to filter these results search bar, begin to enter “Calendars.ReadWrite”.
Select the > Calendars drop-down list. The > Calendars drop-down list will appear.
Select the Calendars.ReadWrite permission (not shown in screenshot below).
Select the Add permissions button.
In the Start typing a permission to filter these results search bar, begin to enter “Directory.Read.All”.
Select the > Directory drop-down list. The > Directory drop-down list will appear.
Select the Directory.Read.All permission.
Select the Add permissions button.
Select the ✓ Grant admin consent for [your organisation] button (for example, Obsidian River). The Grant admin consent confirmation pop-up will appear.
When asked to confirm, select Yes.

Note: for more information, see Microsoft’s guidance on managing application permissions from Microsoft Graph and granting admin consent.

Give the required information to Matrix Booking

Contact your Account Manager and give them the following details:

Application (client) ID.
Directory (tenant) ID.
Your organisation’s domain.

Our Technical team will register the bidirectional sync from Matrix Booking’s perspective on your behalf, and they will work with your team to test that the integration is set up correctly. They will also give you our X.509 digital certificate.

Add the certificate

For additional security, we use a certificate as a credential when authenticating with the Microsoft Graph API. To add this certificate:

Select Certificates and secrets in the Matrix Booking Overview screen’s side menu.
Select the Certificates (X) tab (where X is a whole number).
Select ⤒ Upload certificate. The Upload certificate pop-up will appear.
Select the 📁 Select a file button. Your native file explorer will appear.
Find the X.509 digital certificate we gave you.
Select Open or Upload.
In the Enter a description for this certificate text box, enter a description.
Select Add.

Get the Microsoft resource’s email address

To get a Microsoft resource’s email address:

Log in to the Microsoft 365 Admin Center.
Select ⋯ Show all in the side menu. All options will be available in the side menu.
Select the Resources drop-down list in the side menu. A drop-down list will appear.
Select Rooms & equipment. The Rooms & equipment screen will appear.
Select your chosen resource (for example, Avon View).
- This will show you a details pane on the right where you will see the room’s email address.
- In this example, the room “Avon View” has the email address avon.view@obsidianriver.onmicrosoft.com.
Give this email address to your organisation’s Matrix Booking Administrator.

Finish integration setup in Matrix Booking

Once you have been informed that we’ve set up your integration, your Matrix Booking Administrator will be able to link Matrix Booking resources with Microsoft 365 resources using our web app.

Warning: the following steps assume that the resource has previously been added to Microsoft 365 and also to Matrix Booking. These steps need to be performed for each resource that will be synchronised.

Sync any existing future bookings

If you have any future bookings against any resources that you want linked between Matrix Booking and Microsoft 365, any existing future bookings between the 2 systems aren’t automatically synced.

If you have any future bookings against any resources that you want linked, any existing future bookings between the 2 systems aren’t automatically synced. You may come across 1 of the following error messages when you try to link the resource:
- Future bookings in Matrix Booking:
- Future bookings in Microsoft 365:
- Future bookings in both Matrix Booking and Microsoft 365:
Raise a support ticket to let us know:
If you’re using either Matrix Booking or Microsoft 365 as your “master” resource booking system where the future bookings currently reside.
- The date you want the sync to happen.
- The date range of bookings you want synced.
Our Support Team will run:
- A future bookings analysis.
- The future booking sync for you, so that they appear in both calendars.
You’ll need to finish the integration setup for any resource that doesn’t have any future bookings against it.

Notes:

If you add any new resources to your Locations and Resource hierarchy, we recommend that you link them to your Microsoft 365 resources (rooms).
Any resources that are linked need to go through the future booking syncing sub-process.
Try a test booking in both Matrix Booking and Microsoft 365 to see if the bookings are reflected in each other.
Ensure that you consider the next section on synchronising existing bookings.
If there are more complex scenarios (for example, where bookings in both Matrix Booking and Microsoft 365 need to be considered), contact your Account Manager team to resolve the issue.

Update the Matrix Booking resource

To update your Matrix Booking resource with the Microsoft resource’s email address, as a Matrix Booking Administrator:

Select Admin in the top bar.
Select Locations and Resources under the Location Settings section in the side menu.
Select Edit hierarchy. Your Locations and Resources hierarchy will appear.
In the Find location search bar, begin to enter the resource’s name. The resource’s name within Matrix Booking might not be the same as within Microsoft 365.
Go to your matching resource.
Select the 📝 Edit button next to your resource. The Edit [resource] pop-up will appear.
If No calendar provider appears in the Calendar drop-down, the resource isn’t associated with a Microsoft 365 resource.
Select the Calendar drop-down list.
Select the chosen calendar provider. This will have been added by the Matrix Booking Technical Team (for example, Obsidian River 365).
In the Calendar Resource text box, enter the email address of the Microsoft 365 resource that you obtained.
Select Save.
Repeat the Get the Microsoft resource’s email address steps and Update the Matrix Booking resource steps for each resource you wish to keep synced between Matrix Booking and Microsoft 365.

You should now be able to make bookings in either Matrix Booking or Microsoft 365.

Get our add-in

If you want your colleagues to use our Microsoft 365 add-in, contact your Account Manager and subscribe. Afterwards, ask your IT team to install it.

Delink a resource from Microsoft 365

To delink a Matrix Booking resource from Microsoft 365 integration so bookings are no longer synchronised:

Select Admin in the top bar.
Select Locations and Resources under the Location Settings section in the side menu.
Select Edit hierarchy. Your resource hierarchy will appear.
Go to your chosen resource.
Select the Edit 📝 button next to your resource. The Edit [resource] pop-up will appear.
Select the Calendar provider text box. A drop-down will appear.
Select No calendar provider.
Select Save.
This can only be done if Matrix Booking hasn’t received any webhook notifications (or subscription messages) for the resource from Microsoft 365. If there are such messages, an error will be shown:

In this case, the subscription messages will need to be manually deleted.