HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Sales Mailbox Integration
Azure Configuration
This integration allows you to create actions on open opportunities from emails within specified sales mailboxes. The integration will scan the sales mailboxes and detect if the email can be added to an opportunity based on the opportunity email address and the subject. To get this up and running, you need to register a new application in Azure.
Application Registration
To register a new application in Azure, select App Registrations > New Registration. Give your application a sensible name before moving on to choosing what account types should be able to access your application.
The redirect URI can be left blank for now, as multiple redirects can be configured later in the application setup process.
API Permissions
Now that an application has been registered, you must give it the relevant permissions required by the integration. In your new application, go to the API Permissions tab to get started. You should see your list of current permissions will be listed, along with options to manage these. Select the option to add a new permission, and choose Microsoft Graph from the available APIs.
Next select delegated permissions, and select the following permissions from the list:
- User.Read
- Mail.Read.Shared
- offline_access
Once all permissions have been selected, press the add permissions button to add these to your application.
Redirect URLs and Authorisation
Next, you need to navigate to the Authentication tab within your Azure application, where you can add valid redirect URLs. Start by adding a platform and choosing "Web". Once selected, add your Halo web application URL as the redirect URL and register the platform. This will give you the option to add additional redirect URLs.
There are extra redirect URLs that must be added for different elements of the integration to work successfully. Using https://halowebapp.com as an example Halo application URL that should be replaced with your own URL, the following redirect must also be added:
https://halowebapp.com/azure/auth
A further redirect URL must be added, that requires you to obtain the authorisation server URL of your Halo application. To find the URL of your authorisation server, in your Halo application, open Configuration > Integrations > Halo API:
After obtaining the authorisation server URL, you must append /account/azureresponse to it, and add this value as a redirect URL. Using the value from the screenshot above, the redirect URL that must be added is http://localhost:49490/account/azureresponse .
If you have any difficulty obtaining your authorisation server URL, please contact the Halo Support Team.
Underneath the area of the Authentication tab where you can register redirect URLs for your application, you must ensure that the application is able to issue access tokens.
General Configuration
To enable the Sales Mailbox integration in Halo, go to Configuration > Sales, and enable the Sales Mailbox module. Once the module has been enabled, click the menu icon for the module to begin configuring it.
Once you have selected new, you will be presented first with the details tab of your connection, where you can begin by giving your connection a unique name.
Once complete, you then need to add tenant id (directory id), application id and application secret. To retrieve the Azure Application and Directory IDs, open Azure and open your configured application. You can find the application ID from the overview page:
From here, navigate to the Certificates and Secrets tab. Underneath the Client Secrets heading, register a new client secret. You can choose whichever expiry length you wish, but keep in mind that you will need to update this value in Halo once it expires and you generate a new secret. You must ensure you take note of this value, as it is not retrievable again after you leave this page.
Although these fields are not all marked with an Asterix to indicate they are mandatory, the integration will not function with any of these fields unpopulated.
Mailboxes
Once the connection has been added the next step is to add all of the mailboxes which you would like to scan. Switch over to the Mailboxes tab and you will be presented with a table containing all of the currently mapped sales mailboxes.
To add new mailboxes to the list click Edit and then Add.
Once happy with the list of mailboxes you can click the Test Mailbox Access button to test that the connection has access to the specified mailboxes. If any of them fail you will need to go into Azure and alter the permissions of the main connection to be able to read all the mailboxes that are needed.
Click save to persist the list of mailboxes.
Halo Integrator
Once you’re happy with your configuration for the rest of the connection, you can then enable the connection to be synced via the Halo Integrator application.
The Halo Integrator can be downloaded using the link provided. You can also choose whether to automatically import emails from sales mailboxes. Each time a connection is synced via the Halo Integrator, the last sync date and the last error (if there was one) will be saved to the connection so that you can view them within the Halo Web Application.
Once you’ve downloaded the Halo Integrator, you should complete the configuration check on the Sales Mailbox Tab. General configuration of the Halo Integrator is not covered in this guide.
If all points return with a green ticket, then you are ready to import. If any points return a red cross, you should revisit the configuration for the integration.
To manually import via the Halo Integrator, switch to the Processes tab and click “Start Processing”. This will process all integrations that are enabled for the Integrator. Alternatively, if your Halo Integrator application is already configured to run on a schedule, the Sales Mailbox integration will be checked and processed the next time the Integrator runs.