HaloITSM Guides

The method below can take up to 5 minutes to bring emails into Halo as tickets. To use webhooks (instant) mail processing method, please use this guide instead: 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. Incoming mail can take up to 5 minutes to be processed into Halo using this method. 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.

1. Select "New Registration"
   • 
2. Select the "Single Tenant" account type and provide a web based URL with <Halo Web App Agent Portal URL>/azure/auth
   • 
3. Once registered, navigate to the 'Authentication' tab and add the second redirect URI: <Halo Web App Agent Portal URL>/auth/account/azureresponse and save.
4. Note down the Application (Client) ID and Directory (Tenant) ID as these are required later.
   • 
5. 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.
   • 
     
6. Navigate go to the "API Permissions" tab and click "Add a permission".
   • 
     
7. Choose "Microsoft Graph" and "Delegated".
8. 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.

1. 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.

1. In Halo, navigate to Configuration > Email > Mailbox Setup, create a new entry, and select "Office 365/Azure" as the connection type.
2. 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.

NB: To ensure that the authenticating account has access to the shared mailbox, follow these steps:

1. Log into the authenticating account in Microsoft 365.
2. Head to the shared mailbox via the 'Switch Account' option.
3. 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.
4. If you do not see the licensed address in the permissions, please add it as an owner.

Contact Imports (v2.168.1+)

Once you have connected you will see an additional tab titled 'contact imports' this can be used to import contacts from Outlook as users in Halo, using the connected mailbox. 

If using this functionality you will need to add the following permission to your Azure application:

Contacts.Read

Before importing contacts you may want to create some contact mappings, this maps Outlook contact fields to user fields in Halo. To create a mapping simply use the 'Add' button to add a mapping to the table, select the Outlook field and Halo User field you would like to be associated, and hit save. New users that are created will be attempted to match to a site based on their email domain, if their domain cannot be matched to a site domain they will be assigned to the default site for new users. 

The 'Import Contacts' button can be used to manually import contacts, but these can also be imported on a schedule using the Halo Integrator. The checkbox 'Enable the Halo Integrator for importing Outlook Contacts from

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