HaloCRM

HaloCRM Guides

Guides > Google Workspace Integration

Google Workspace Integration

General Configuration 


To enable the Google Workspace integration in Halo, go to Configuration > Integrations > Identity Management, and enable the module. Once the module has been enabled, click the menu icon for the module to begin configuring it.


Connect to Google


You must choose a designated Google account to connect to your Halo instance. This designated account must have read access to both users and groups in your Google directory.



Common Error

When you get the 'App Blocked' message:

Scroll to the end of the URL and copy the client ID the bit appended after client_id= (example: 923645183353-bofimqlxrtudrgdvtizcoau1ojkrjhirmmszm.apps.googleusercontent.com). Go to workspace admin https://admin.google.com, and search for API Controls. Click Manage Third Party Access. Once there, click on Add app and select the first option ( OAuth ) and paste in that client ID to search.

If this is still not working when searching, remove the ".apps." part in the string as well… then the lookup will detect "halo services"




Once you have decided which account to connect, clicking connect now will redirect you to the Google login screen where you can login to the chosen account. Once completed, you will be redirected back to the Google Calendar module in Halo, where some new options will be available.


During the authorization process, you will notice that our app is currently listed as unverified. Please bear with us whilst we work with Google to verify the app and remove this screen from the authorization process. 


Once connected, your account email will be displayed at the top of the setup screen. You can disconnect at any time from Halo using the disconnect account button. 



Site/Agent Mappings


Now that you have successfully connected Halo with your Google account, you can begin configuring Site/Agent mappings. This feature allows you to map subsets of users in your Google directory to different sites in Halo, or create them as agents. This is achieved by creating filter profiles based on fields from Google Workspace, to filter down your overall user list.



Before creating any filters, you should first choose which directory you would like to import your users from. Unless you are a reseller of Google Workspace, you should always choose "Import from my directory only". If you are a reseller and you would like to also import users from your customer's Google directories, you should choose the option "Import from multiple customer directories".


When adding a mapping, you must first choose which site the mapping is for. If you choose *Agent*, the the mapping will be applied to the agent import rather than the users import. You will also be given an extra option to choose a default role that should be given to any agents created via this mapping. If you would like to apply a filter to the mapping, check the box to apply a filter, and three additional options allowing you to build the filter will appear. If you do not apply a filter to the mapping, then all users from your Google directory will be retrieved.



If you have chosen to import from your customers directories, you will have another additional mandatory field for the customer ID. To obtain this value, navigate to account settings in Google Workspace where this value will be displayed at the top of the page. When importing from your own directory, you can specify your own customer ID, or use the value "my_customer".



Field Mappings


A selection of Google Workspace fields can be mapped to system and custom fields in Halo, for both users and agents. You will notice when opening the module for the first time that quite a few of these field mappings have already been created for you. 



To add a new field mapping, simply press the plus icon on either the user mapping or agent mapping table, and choose which Google Workspace field should be mapped to which Halo field. Each field can only be mapped once and the name attribute mappings cannot be adjusted.


Advanced Mappings


You can manage your Halo agents' roles and hence their application permissions in Halo by mapping Google groups to roles. You can also manage which agents belong to which change advise boards in the same way.



During an agent import, if a user from your Google directory belongs to a group that is mapped to a role, the role will be applied to their agent account. For example, the mapping shown below will apply the administrator role to any agent that is being imported and belongs to the Development group.



Similarly, the mapping shown below will add any imported agent that belongs to the Development group to the Example CAB change advise board.



If a user was then removed from the Development group in Google Workspace, they would be removed from the cab and lose their administrator role during the next import. 


Licence Management


You can also manage the status of your agents based on the roles that they have been assigned during an import. Take extra care when configuring this feature, as enabling it and not correctly adding all roles that should make an account active could result in agents losing their access to Halo.


Importing Users and Agents


By default, when importing from your Google directory, a user will always be matched to an existing record in Halo via their unique Google ID, which is assigned to each account when they are first imported. However, if you already have your user list in Halo, but have never imported from your Google directory before, then users will not have a unique Google ID assigned to them, and duplicate users could be created during the import. By choosing at least one matching field, you can prevent duplicate users being created by matching old records on either their name, or email address. The matching process works based on the order in which you add the field to these boxes. 



Once ready, click either the import users or import agents button to open the importer screen. Providing at least one site/agent mapping has been configured, Halo will fetch your user list using the filters associated with each mapping, and display them on the importer screen so that they can be reviewed before proceeding with the import. If a user account is retrieved more than once, only the first instance of that user will be imported.


Example: if you create 2 mappings, one that links to site A and another that links to site B, and the user John Smith is found in both mappings, he will only be imported into site A.


Halo Integrator


Once you’re happy with all of your configuration, you can then enable the Halo Integrator for the integration. This allows you to run an agent and/or user import on a schedule using the configuration you have chosen. The Halo Integrator can be downloaded using the link provided. Each time the import is completed via the Halo Integrator, the last sync date and the last error (if there was one) will be saved so that you can view them within the Halo web application. 


The use of the integrator is not covered in this guide.


Google Sign-In


Now that your users/agents exist in Halo, you may wish to enable Google Sign-In on the agent application and end user portal. Enabling Google Sign-In will present you with some additional options as shown below.



If you are using a hosted solution of Halo and are a trialist, you are not required to specify a Google App ID. This means you will be authenticating using a Google application configured by Halo. However, if you are using an on premise solution, or you wish to manage your own Google app, you will need to register a new Google project and OAuth client for Google Sign-In. This can be done here: https://developers.google.com/identity/sign-in/web/sign-in.  Once completed, copy the app's ID into the field provided in Halo.


If you're hosted but are no longer a trialist so you have your own auth URL, you won't be able to use Halo's default Google app for single sign-on as your auth URL will not be registered as a valid redirect URL. To resolve this, you will need to create an app in the Google developer portal that you can use for single sign-on from this link: https://developers.google.com/identity/sign-in/web/sign-in. You will need to register a new OAuth client, where the auth URL will be similar to (https://myhalourl.com/auth/account/googleresponse) is added as a redirect URL. Once the app has been created you will need to copy your Google app ID (not including the portion "apps.googleusercontent.com") into the corresponding field on the integration page in Halo. 


It is advised that Google Sign-In is confirmed as working with your configuration first before activating the automatic redirect, otherwise, you may interrupt the sign in process for your users/agents.

Popular Guides

Pin It on Pinterest