
HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Sales Mailbox Integration
In this guide we will cover:
- Azure Active Directory Configuration
- Connecting the Mailbox
- Adding the Mailboxes
- Halo Integrator
- Viewing the Mailbox
- Other Configuration
- Setting Overrides
Azure Active Directory 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. You can also see the items in the mailbox and choose to manually relate them to opportunities or create new opportunities.
To get this up and running, you need to register a new application in Azure.
Application Registration
To register a new application in Azure, browse to your Azure Active Directory page and select App Registrations > New Registration. Give your application a sensible name before moving onto choosing what account types should be able to access your application.
Fig 1. Registering an 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.
Fig 2. Selecting an API.
Next select delegated permissions, and select the following permissions from the list:
- User.Read
- Mail.Send.Shared
- Mail.Send
- Mail.ReadWrite.Shared
- offline_access
Fig 3. Adding permissions.
Once all permissions have been selected, press the add permissions button to add these to your application.
Redirect URIs and Authorisation
Next, you need to navigate to the Authentication tab within your Azure application, where you can add valid redirect URIs. Start by adding a platform and choosing "Web". Once selected, add your Halo web application URL as the redirect URI and register the platform. This will give you the option to add additional redirect URIs.
There are extra redirect URIs 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 URI 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:
Fig 4. API details.
After obtaining the authorisation server URI, you must append /account/azureresponse to it, and add this value as a redirect URI. Using the value from the screenshot above as an example, the redirect URI 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 URIs for your application, you must ensure that the application is able to issue access tokens.
Connecting the Mailbox
To enable the Sales Mailbox integration in Halo, go to Configuration > Sales, and enable the Sales Mailbox module by clicking on the + symbol.
Fig 5. Enabling the module.
Once the module has been enabled, click into the module to begin configuring it. Once you have selected new (top right hand side), you will be presented first with the details tab of your connection, where you can begin by giving your connection a unique name. At this stage you can also enable "Import Sent Items as well as the Inbox" this means that agents sent mail will be imported as well as incoming mail.
Fig 6. Import sent items.
There are two options for matching existing Opportunities,
- Match on Email Address and Subject - Matches to any non-closed opportunity with an exact match on email address and subject.
- Match on Email Domain - Matches to any non-closed opportunity with the same email domain as the sender of the email.
Fig 7. Matching type.
Note: This will determine how emails are automatically matched to opportunities but automatic matching will need to be enabled for each agent email address for this to take place. More info on this below.
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.
Fig 8. Application ID.
Client Secret
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 copy and take note of the secret's value, as it is not retrievable again after you leave this page.
Fig 9. Creating a secret.
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.
Adding the 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. This is used to match the mailbox of the agent to their agent in Halo.
Note: Only personal mailboxes can be added to the sales mailbox. A shared mailbox cannot be added here.
Each agent that is added to this table will then have the 'My Inbox' module available. This module will show all the emails that have come into the agent's mapped email address so the agent can manage them within Halo.
Fig 10. Mailboxes table.
When adding a mailbox you will need to enter the email address you would like the sales mailbox to have access to, incoming (and outgoing) mail to this address will be scanned.
Fig 11. Adding a mailbox.
You will then need to select the agent that has access to this email address, the agent selected here will be able to see all the incoming emails to this email address.
Enable Email matching - This setting determines whether emails processed by this address will be matched to tickets automatically. When checked emails in this mailbox will be attempted to be matched to an opportunity/project ticket automatically, if they cannot be matched a new ticket will be created. If unchecked, agents will need to manage their incoming emails manually using the 'My Inbox' module. Each email can be checked and added to an existing opportunity, or added to a new one. If enabled an additional setting will appear 'Emails are matched to' here you can select which tickets emails within this mailbox are matched to, opportunities or projects (based on the ticket type 'Use')
You will also have to add permissions from the M365 Admin Centre, this is so that you can send and read data from the mailboxes. Within mailbox permissions you will want to add the "send as" permission and "read and manage" permission. To navigate here go to Users > Active Users > *Click into a user on the list (Add permissions for all users that require access to the mailbox)* > *Go into the "Mail" Tab* and you will see the below options.
Fig 12. Mailbox permissions.
Clicking into the permission links will allow you to add permissions.
Once happy with the list of mailboxes in Halo 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.
Fig 13. Enabling the integrator.
The Halo Integrator can be downloaded using the link provided, Halo can host the Halo integrator for Hosted customers. 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.
Note: If you are having issues with connecting the Halo Integrator/Sales Mailbox, please check the list of synced entities for the Halo Integrator from within Configuration > Integrations > Halo Integrator, you should see the "Sales Mailboxes" in the list of Active Integrations.
Fig 14. Integrator configuration.
Once you’ve downloaded the Halo Integrator, you should complete the configuration check on the Azure Active Directory Tab. General configuration of the Halo Integrator is not covered in this guide, this can be found here.
Fig 15. Halo integrator.
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.
Viewing the Mailbox (My Inbox)
Each agent that has been given access to the sales mailbox will have a module called 'My Inbox'. This will show all incoming emails to the address that agent has been mapped to.
Note: Agents will only be able to see emails from the address they have been mapped to, they will not be able to see mail from other address associated with the sales mailbox.
The 'My Inbox' module can be used to manually process emails and associate them with opportunities, used when an agent does not have 'Enable Email matching' enabled. Upon opening the module you will see a preview of all emails, once an email is selected you will have the option to 'Add to existing Opp' 'Add to new Opp' or 'Delete'.
Fig 16. My Inbox.
Other Configuration
Multiple changes to the Sales Mailbox functionality
1. Sent Items can now be imported and matched(Agents emails they send from their mailbox, can be sent into a ticket in Halo)
2. Opportunities and Projects can now be matched (set per Agent)
3. Email domain can be used as the matching criteria
4. Domains matching the Agents own domain will be ignored
Configure the From Address on Actions
Actions can be configured to use the personal email of the agent that is completing the action, rather than using a shared mailbox. To do this head to the action configuration (configuration > tickets > actions > defaults tab) and set the 'From address' to be '*Sales Mailboxes*.
Fig 17. From Address.
Now when this action is used, Halo will look through the "Mailboxes" table of a sales mailbox and then override the from address with the agents address (the agent performing the action) listed on the sales mailbox table.
You can also exclude ticket types from Sales Mailboxes, this is done from the settings tab of a ticket type.
Fig 18. Including/excluding a ticket type.
There is an option within Configuration > Sales > General Settings to stop email chains being sent on every ticket update from a sales mailbox.
Fig 19. Hide email chain.
When enabled, the email chain pulled through from the sales mailbox integration, will not show. Meaning that you will not see the entire chain per action, as each update to a ticket will show the entire chain.
Setting Overrides
Set Global Sales Mailbox Override
To set a global sales mailbox override head to configuration > Quotations, 'From Address'. Select 'Sales Mailboxes' and this will ensure all quotes are sent out using the configured sales mailbox.
Fig 20. Quotations configuration.
You can also set a 'fallback' mailbox, this is the mailbox that is used to send out the quotation if the agent sending it is not configured as part of the sales mailbox.
If you do not set a fallback mailbox then there will be no restriction on the from address, the agent will be able to choose to send the quotation from all the mailboxes they have access to.
Note: This setting is overridden by the mailbox settings on the action.
Set override at Client level
To set the sales mailbox override at the customer level, head to the customer's profile > Settings > Email Defaults, 'Mailbox override for Quotation emails'.
Fig 21. Customer override.
Here you can choose the mailbox used to send out quotations for this customer. This will override the global setting for quotations.
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments and Teams
- 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