HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Azure Mail Integration (Azure Mailbox Scan Method)
For customers using the new incoming/ outgoing services checkout this guide for setting up Azure Mailboxes using the instant email processing method: Configuring An Azure Mailbox (The Webhook Method)
This integration facilitates the connection of Azure mailboxes to Halo using the scan method, enabling the ingestion of received emails to create tickets. It also allows you to send emails from Halo through the connected mailbox. To initiate this process, you need to register a new application in Azure. You can choose to create a separate application for each mailbox if needed. Please note that Halo supports the connection to standard licensed mailboxes and shared mailboxes but does not currently support other mailbox types.
*MAKE SURE THE INBOX IS EMPTY BEFORE ADDING AND CONNECTING TO THE HALO MAILBOX, IF IT IS NOT, ALL EMAILS IN THE INBOX WILL BE TURNED INTO TICKETS*.
Azure Connection Configuration
To register a new application in Azure, navigate to your Azure Active Directory page and select "App Registrations > New Registration." Provide a meaningful name for your application before proceeding to specify which account types should have access to your application.
- Select "New Registration"
- Select the "Single Tenant" account type and provide a web based URL with <Halo Web App Agent Portal URL>/azure/auth
- Once registered, navigate to the 'Authentication' tab and add the second redirect URI: <Halo Web App Agent Portal URL>/auth/account/azureresponse and save.
- Note down the Application (Client) ID and Directory (Tenant) ID as these are required later.
- Navigate to the "Certificates and Secrets" tab, and under the Client Secrets section, register a new client secret. Choose an expiry length, but remember to update this value in Halo when it expires. Take note of the secret value as it cannot be retrieved again after leaving this page.
- Navigate go to the "API Permissions" tab and click "Add a permission".
- Choose "Microsoft Graph" and "Delegated".
- The necessary Graph API Permissions are listed below, with notes detailing their essential functions for the integration to work correctly. Once all permissions have been chosen, click the "Add Permissions" button to incorporate them into your application:
Regardless of what microsoft recommends, grant admin consent for all permissions, you can do this by clicking the grant admin consent at the top of the API Permissions list
- offline_access
- Grants the app the ability to access and update data even during user inactivity.
- openid
- Enables users to sign in to the app using their work or school accounts.
- Allows the app to access basic user profile information, enabling the authentication process.
- email
- Allows the app to read users' primary email addresses.
- Essential for accessing email-related information and enhancing user identification within the Halo ITSM/PSA Solution.
- profile
- Enables the app to see users' basic profile information, including name, picture, username, and email address.
- Assists with mailbox verification during the authentication process.
- mail.readwrite
- Grants the app the ability to create, read, update, and delete emails in user mailboxes.
- Does not include permission to send mail but ensures comprehensive control over mailbox operations.
- mail.send
- Allows the app to send emails as users in the organization.
- Facilitates seamless communication within the organization directly from the Halo ITSM/PSA Solution.
- mail.readwrite.shared
- Only required if the mailbox being connected is a shared mailbox.
- Authorizes the app to create, read, update, and delete mail that a user has permission to access, including shared mail.
- Does not include permission to send mail but ensures effective management of shared mail within the solution.
- mail.send.shared
- Only required if the mailbox being connected is a shared mailbox.
- Allows the app to send emails as the signed-in user, including sending on behalf of others.
- Enhances collaborative communication by enabling users to send emails on behalf of their colleagues.
- Only required if the mailbox being connected is a shared mailbox.
- Grant Admin Consent for the added permissions.
Halo Connection Configuration
Once you've registered the application in Azure and granted the necessary permissions, proceed to set up the mailbox in Halo.
If you're working with a shared mailbox, the user authorizing the connection in Halo must also have "Read and Manage" and "Send As" permissions for the shared mailbox. Ensure these permissions are added using the M365 Admin Centre and not through the Exchange Admin Console.
- In Halo, navigate to Configuration > Email > Mailbox Setup, create a new entry, and select "Office 365/Azure" as the connection type.
- Fill out the form below by entering the Client ID, Tenant ID, and Secret Value generated in the previous steps (4 and 5). Click the "Authorize Application" button. This action will redirect you to your tenant for sign-in using the details of the desired mailbox.
- Credentials:
- If you are authorizing a licensed mailbox, simply sign into your licensed mailbox using its username and password. This will allow Halo to finally be able to ingest emails as tickets and send emails out.
- If you are authorizing a shared mailbox ensure...
- ...the "Shared Mailbox" field is populated the shared mailbox's full address.
- ...the licensed user is added as a delegate user on the shared resource with Read & Manage permissions granted via the M365 Admin Center's Manage Mailbox Permissions.
- If either of these have not been configured correctly, it is possible that Halo will try to ingest emails from the authenticating licensed account rather than the shared mailbox. In case of this improper configuration, it is advisable to remove mail from the authenticating mailbox's inbox temporarily until after you can confirm that Halo is ingesting the correct mailbox's emails.
- Credentials:
NB: To ensure that the authenticating account has access to the shared mailbox, follow these steps:
- Log into the authenticating account in Microsoft 365.
- Head to the shared mailbox via the 'Switch Account' option.
- Once in the shared mailbox, right-click on the inbox folder, go to Permissions, and ensure the authenticating (licensed) address is marked as having full access.
- If you do not see the licensed address in the permissions, please add it as an owner.
Common Errors
The first thing to try when a mailbox stops working and no error below matches your issue, is to Disconnect and then reauthorise the mailbox in Halo
Error | Solution |
Length Cannot Be less than zero (Parameter 'length') | When this occurs, you must create a new secret and make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Error is not defined, and you are in doubt as of what to do | Disconnect and then reauthorise the mailbox in Halo if in doubt |
Failed to retrieve agents - 400 Bad Request: "Token refresh failed - invalid_grant - AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Connection Failed for refreshing access token for mailbox ID 3 - AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Emails not coming through to halo but mailbox is working and inbox is being emptied? | Run Report “select top 100 * from incomingemail order by IEdatecreated desc” then do a ctrl + f for rule and check to make sure it isn’t being caught by an email rule, if it is, it will be evident on the report which email rule is binning off all emails. Emails can then be added back from the deleted folder (in your outlook account) to inbox and then they will be processed back into halo once placed into the inbox folder. |
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers