HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Syncing Exchange Calendars using the Microsoft Graph API

Syncing Exchange Calendars using the Microsoft Graph API

Topics Covered in This Guide


  • How to connect to the integration using the different connection types
    • Use an Azure application with application permissions
    • Each Technician connects to their Exchange account individually
    • Connect to a single account which has delegate access to each Agent's calendar
  • Create MS Teams meetings with the Teams Meeting Appointment Type
  • Set appointments to be private
  • Syncing appointment locations 


This guide covers how to connect to the Exchange Calendars integration using the Microsoft Graph API connection method. When using this method there are three connection types you can use:

  • Connect to a single account which has delegate access to each agent's calendar 
  • Each technician connects to their Exchange account individually 
  • Use an Azure application with application permissions

You will need to connect using one of these three connection types, we will cover how to do this in the guide. You will only need to follow the section relevant to the connection method you are using.




For Connection Type: Use an Azure application with application permissions


This option is recommended as it gives permissions to the application (This may be a security issue for the company, so the next connection type may be more suited), which stops the need to have delegate access to every user. This is an application permission. 


Azure App Registration


Firstly, you will need to set up an App Registration in Microsoft Azure. This can be done by navigating to the App Registrations tab of Azure and selecting new registration. The only thing you will need to set up here is the access type (single tenant) and name. Once this registration is complete you should keep this window open as you will need to refer back to the App registration when setting up your Calendar Integration.


To get into the new app registration, head to https://portal.azure.com then click into the microsoft entra area:


Then create a new registration



Give the app a name


create a new secret (copy the secret "value" and make sure you store it somewhere safe as it will disappear after you click off the screen, for security reasons)



API Permissions: remove user.read


Add the following API Permissions (must be an Application Permission):


Calendars.ReadWrite (make sure to grant admin consent)



Add in the following Application (Client) ID, Tenant ID and secret value (NOT the Secret ID) into the corresponding fields in Halo



NB: The secret value will only be available to copy right after creation, once clicking off the screen it can't be copied and is starred out. Make sure to copy the secret and store it somewhere safe.



Add the credentials into the corresponding fields in Halo, and now your appointments will be synced.


Access is to be for all agents calendars, click on the "Enable for All Agents" button


Immutable IDs (Available As of v2.164)

When using this connection type you will have the option to use Immutable IDs. This prevents issues caused by the ID of an Exchange appointment changing when certain properties on the appointment are changed.


Additional permissions must be granted to your Azure application to use this functionality. The following permission is needed:

 User.Read.All permission (type: application)


Immutable IDs can be enabled by selecting the 'Use Immutable IDs' button at the bottom of the exchange calendars integration page. Note, enabling this is irreversible and you will not be able change your connection method/type following this. 


Webhooks

Note: Immutable IDs must be enabled to use the webhook functionality. Once enabled a 'webhooks' section will be available under the exchange calendar setup page.


Webhooks can be configured to receive instant updates for Created, Updated, and Deleted events from Exchange.


As shown on the setup screen, subscriptions for an agent will be created/deleted automatically when toggling the integration on/off in their preferences. Any active subscriptions will be renewed either when a webhook is received for an event for that agent, or daily via the task scheduler.


You can manually manage the subscription for each agent in the table provided. The add button also contains an "All" option to create a subscription for all outstanding agents.







For Connection Type: Connect to a single account which has delegate access to each Agent's calendar


The following video contains a walkthrough on how to connect to Exchange calendars using this connection type. Written steps to connect are also provided below.




























Important Notes:

An Administrator must connect to the single account below. Meeting invites will be sent from the connected account's email address. The azure account used when authorising the application from inside Halo needs to have delegate or "Full Access Permission" to each of the accounts (Mailbox Folder Permission) that you are connecting to for editing/adding appointments. 


Azure App Registration


Firstly, you will need to set up an App Registration in Microsoft Azure. This can be done by navigating to the App Registrations tab of Azure and selecting new registration. The only thing you will need to set up here is the access type (single tenant) and name, redirect URI is necessary. Once this registration is complete you should keep this window open as you will need to refer back to the App registration when setting up your Calendar Integration.


To get into the new app registration, head to https://portal.azure.com then click into the microsoft entra area:


Then create a new registration



Give the app a name and a redirect URI i.e. https://*yourhaloinstance.com*/azure/auth, the platform dropdown should be set to "Web"


create a new secret (copy the secret "value" and make sure you store it somewhere safe as it will dissapear after you click off the screen, for security reasons)





Add the following API Permissions:


User.Read.All

Calendars.ReadWrite

Calendars.ReadWrite.Shared

offline_access


Remove user.read


 (make sure to grant admin consent for all of them)



Add in the following Application (Client) ID, Tenant ID and secret value (NOT the Secret ID) into the corresponding fields in Halo



NB: The secret value will only be available to copy right after creation, once clicking off the screen it can't be copied and is starred out. Make sure to copy the secret and store it somewhere safe.



Add the credentials into the corresponding fields in Halo:

Then click *Authorise Application* 


If you receive redirect URI errors, make sure the redirect is set up correctly i..e choose "Web" from the platform dropdown and use the following convention for the uri: https://*yourhaloinstance.com*/azure/auth


If the access is to be for all agents calendars, then click on the "Enable for All Agents" button



Give mailbox permissions to another Microsoft 365 user:

If using this connection type you may need to grant the account you are connecting with delegated permissions to access each agent's mailbox (depending on your company requirements). This will grant the account full access to your calendar. A guide on how to do this can be found at the following link:

https://docs.microsoft.com/en-us/microsoft-365/admin/add-users/give-mailbox-permissions-to-another-user?view=o365-worldwide   





For Connection Type: Each Technician Connects to Their Exchange Account Individually


Azure App Registration


Firstly, you will need to set up an App Registration in Microsoft Azure. This can be done by navigating to the App Registrations tab of Azure and selecting new registration. The only thing you will need to set up here is the access type (single tenant) and name, redirect URI is necessary. Once this registration is complete you should keep this window open as you will need to refer back to the App registration when setting up your Calendar Integration.


To get into the new app registration, head to https://portal.azure.com then click into the Microsoft Entra area:


Then create a new registration.




Give the app a name, set the access to be single tenant and add a redirect URI. The redirect URI you need can be found on the configuration page for the integration, but will follow the format  https://*yourhaloinstance.com*/azure/auth . The platform dropdown should be set to "Web".



Now create a new secret (copy the secret "value" and make sure you store it somewhere safe as it will disappear after you click off the screen, for security reasons). You will need to give the following API Permissions to the application:


User.Read.All

Calendars.ReadWrite

Calendars.ReadWrite.Shared

offline_access


Remove the user.read permission


Ensure to grant admin consent for all of them.


Add in the Application (Client) ID, Tenant ID and secret value (NOT the Secret ID) into the corresponding fields in Halo




NB: The secret value will only be available to copy right after creation, once clicking off the screen it can't be copied and is starred out. Make sure to copy the secret and store it somewhere safe.





Add the credentials into the corresponding fields in Halo:


If you receive redirect URI errors, make sure the redirect is set up correctly i..e choose "Web" from the platform dropdown and use the following convention for the uri: https://*yourhaloinstance.com*/azure/auth


If using the method where each technician connects to their own exchange account, you will now need to ask your agents to navigate to the Calendar module and scroll down to find the "Exchange Calendar" section where you can connect or disconnect your account. If this does not show up immediately, you will need to clear your cache and log out and back in.




Common Errors


Description

Cause

Resolution

When testing which calendars the connected account has access too, an error is given saying "The specified object was not found in the store"

Either the connected account does not have the required level of access to the user’s calendar, or they have only just been granted the correct level of access. Sometimes granting delegate permissions can take up to an hour to take effect.

Ensure the connected account has delegate access to read/edit the user’s calendar. There are multiple ways of doing this, but here is a short guide we've used before.




Teams Meeting

Once connected you can send Teams Meeting invites from Halo by checking the below setting on any Appointment Types that this applies to.



Setting Appointments to be Private

When syncing appointments to Halo, you can set appointments to be private from within Configuration > Calendars and Appointments > General Settings:


Syncing Appointment Locations

To have the appointment location sync over to the appointment in exchange, first ensure you have the appointment location field enabled. This can be enabled under configuration > Calendars and Appointments > General settings. 


Once enabled, when raising an appointment in Halo you will be prompted to choose/enter a location for the appointment. This location will also be visible against the appointment in exchange. 


Exchange Calendars and Multi-Tenancy

The Exchange calendars integration is single tenanted at present so it does not have the functionality to sync appointments from multiple azure tenants.


Popular Guides

Pin It on Pinterest