HaloPSA Guides

In this guide we will cover:

- Registering an Azure Application

- Enabling the Integration

- Account and Contact Imports

- Custom Table Syncs

- Halo Integrator

- Multi-Tenancy (as of v2.182.1+)

Registering an Azure Application

To use the Dynamics 365 CRM integration, you are required to register an application in your Azure portal. To do this, open your Azure portal and select App registrations > New registration. Give your application a sensible name, and ensure that supported account types is set to "Single tenant".

Fig 1. Registering an application.

To finalise your application registration, you must register a redirect URI. Although this step is optional at the time of submission, a redirect URI is required for the integration to work successfully. The redirect URI used will differ depending on the version of Halo you are using. 

On versions prior to v2.200 the following redirect URI will need to be used:

• https://YOURHALODOMAIN/azure/auth

On versions v2.200+ you the following redirect URI will need to be used:

• https://YOURHALODOMAIN/authcallback

But the exact redirect URI you need can be found on the setup page for the integration in Halo.

Fig 2. Setting the redirect URI.

Note: If you have disconnected to the integration and are reconnecting, if your Halo instance is on v2.200+ you will need to use the new redirect URI (WWW.YOURHALODOMAIN/authcallback).

Once the application has been registered successfully, navigate to the Certificates & secrets tab. Register a new client secret using the available options. Once created, keep a copy of this secret somewhere safe, as it is not obtainable again once you leave the application.

Fig 3. Client secret.

The final step to configuring an application in Azure is to add API permissions so that your app can access resources in Dynamics 365 CRM. Navigate to the API permissions tab, where you will see that you have the permission User.Read by default. This permission can be removed as it is not required. Select Add a permission and choose Dynamics CRM from the list of available APIs.

Fig 4. Microsoft APIs.

Select Delegated permissions and then select user_impersonation. Click Add permissions to add this permission to your application.

Fig 5. Setting permissions.

Enabling the Integration

To enable the Dynamics 365 CRM integration, navigate to Configuration > Integrations, and enable the module using the plus icon in the top right hand corner of the menu icon. Once the module has been enabled, click the menu icon to begin configuring it.

Authorisation in Halo

When opening the module for the first time, you will see four fields that must be populated. First is your Dynamics Organisation url, followed by your Azure domain (This is also referred to as the Tenant ID in azure). Third is the ID of the application that you have just registered in Azure (Client ID), which can be found on the overview tab of the application in the Azure portal. The fourth option is your client secret which was generated earlier. Here is the information required from Azure, as displayed in the app registration:

Fig 6. IDs.

The Tenant ID above being for the "Azure Domain" input:

Fig 7. Azure domain.

Click the authorize application button to begin the authorization process. You will be redirected to the Microsoft login screen, and upon a successful login, you will be redirected back to the Dynamics 365 CRM module. Your application and authorisation details have now been saved. To clear these details or make changes to your application configuration in Halo, click the Disconnect from Application button.

Fig 8. Azure application.

Note that if you make changes to your application in Azure, such as changing the API permissions or your client secret expires and you have to generate a new one, you will need to disconnect from your application in Halo and re-complete the authorization process. 

Account and Contact Imports

Now you are connected to your Azure application, minimal other configuration is required for you to begin importing accounts and contacts. If you are not importing all of your accounts, it is important that you choose a default site, as imported users who have not had their accounts imported will be assigned to this site.

Fig 9. Default site.

You are now ready to import accounts and contacts using the two available buttons.

If you have additional fields in Dynamics 365 CRM such as custom fields that you have created, and you would like to bring that data into Halo, you can add field mappings for both accounts and contacts. It is important that you choose the correct data type when creating this field mapping, as your chosen type will determine which custom fields in Halo you can link your Dynamics field too. For example, a multi-select option set can only be mapped to a Halo multi select field.

Fig 10. Field mapping.

If you are mapping either a multi select or single select option set field, (The single select option set will appear as "Option Set" on the data type dropdown) you must also map each option to a value in Halo. To do this, navigate to Custom Objects > Custom Fields and open your custom field. Edit a value in the list and specify the corresponding Dynamics ID of the value.

Fig 11. Mapping values.

This step ensures that single and multi option set fields can be set correctly when they are imported into Halo.

Custom Table Syncs

You can set up tables in Dynamics 365 to sync with a table in Halo so additional data is synced over.

Fig 12. Customer mapping.

To do this head to the 'Custom Table Syncs' tab and add a mapping to the table. Here you will need to choose the Dynamics 365 table you are taking data from and the Halo table you are sending the data to (this is the table the data will be stored in in Halo). You can also add a filter here, so only certain data in the table will be pulled across. As of v2.200.1+, the variable "$-INTEGRATORLASTSYNC" can added here, which is useful when filtering to only pull new updates such as "$filter=modifiedon $-INTEGRATORLASTSYNC".

Once this is saved you will be able to add child and field mappings within this table mapping to determine where data within the table is stored. 

From v2.190+ you will be able to map grandchild lookups to a table in Halo. When configuring a table mapping you will be able to configure a grandchild mapping within the 'Child mappings' table. This allows you map data that is two relationships away from the Dynamics 365 Table selected. 

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 accounts and contacts.

Once you’ve downloaded the Halo Integrator, you should complete the configuration check on the Dynamics 365 CRM 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 Dynamics 365 CRM integration will be checked and processed the next time the Integrator runs. 

Multi-Tenancy (as of v2.182.1+)

You can now use multi-tenancy functionality on Dynamics 365 CRM. Any previously configured instance will be migrated into one called "Migrated Configuration", although this can be renamed if wished.

When clicking into the integration, you will now see a list with the migrated configuration at the top, and you can click "New" to configure another connection with the same method.

Fig 13. Adding another tenant.