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.


Asset Imports

Under the 'Asset imports' tab you can configure how your Assets from Google workspace will be imported.


First, set an Asset matching field. This is the field that will will determine if a new asset is created or an existing one is updated. The field used here should be the unique identifier of the Asset (typically the asset number or serial number). 


Asset Sites

Then set a default site for assets to be imported to. An asset will only be imported to this site if it does not have an site mapping. Enabling the setting 'Assign mobiles to the Site of the matched User instead of the default Site' will assign the asset to the site it's user is under rather than the default site. 


To create a site mapping, add a mapping to the table and select the site you would like the mapping to apply to. Then enter the Client ID and Organization Unit Path for the customer that you would like to be imported to this site. Client ID can be obtained from your account settings in the Google Workspace admin console.


Now the site mapping are set up you determine which asset type an asset is imported as. 


Asset Types

Set the default group for new asset types, if any new asset types are created from the import, this will be the asset group the type is created under. 


The asset types of the assets can either use a fixed type for all assets, be determined from a field, or use asset type rules, determining an asset's type based on rules created here.


If you would like all imported assets to have the same asset type when imported set the 'Determining an Asset's type' field to be 'use the same type for all Assets' then set the 'Default Asset Type' field to be the asset type you would like assets from Google Workspace to be. The below image shows how to set this so all assets are imported as the 'Laptop' asset type. 




If you would like all imported assets' types to be determined by a particular field, set the set the 'Determining an Asset's type' field to be 'Use a field to determine each Asset's type'. Then in 'Field for determining an Asset's type' choose the field you would like the type to depend on. The field you choose must contain the name of the desired asset type, if this name can be matched to an existing asset type in Halo, it will be assigned this asset type. If the name is not the same as an asset type in Halo, a new asset type will be created. Note that the names must be identical in order to match. This setting is used if you have a field in Google that already determines an asset's type and you would like the types to be consistent between Halo and Google. You will still need to populate the default asset type field, as assets that do not have the selected field populated will be imported as the default asset type. The below example shows asset types will be determined by the value in the field 'Type'. 




If you would like asset types to be determined by asset rules set the set the 'Determining an Asset's type' field to be 'Determine asset type using rules'. Now you will be able to set an asset's types based on rules, These rules are based on field values, and if matched will assign an asset to the chosen asset type. When creating a rule first add criteria for the rule, select the Halo field that you would like to base the criteria on, then set the rule type and the outcome needed in the field to match the rule. If an asset matches this rule it will be imported as this asset type. For example, below the rule I have set up will check the name field of an asset, if the name begins with 'LAP' the asset will be imported with the 'Laptop' asset type. 


If an asset is imported that does not match any of these rules, it will be created under the default asset type. 


Field Mappings

Create field mappings to set data from Google workspace fields to be imported to a Halo asset field. Any data held in a Google workspace asset field will need a field mapping created in order to be imported. 


The asset field mappings are divided into two tables, the 'Mobile Field mappings' table is used to create field mappings for mobile devices. The 'Asset field mappings' table is used to create mappings for all other assets. 


To create a mapping, add to the table, select which type of Halo field you would like to map to (custom or asset), then choose the Google and halo fields you would like to map. 

Additional asset settings 

Deactivate Assets in Halo when they are deleted from Google Workspace (Halo Integrator only) - When enabled will cause an asset in Halo to be deactivated when it is deleted from Google Workspace.

Do not update an Asset's type if the Asset already exists - When enabled, if an asset already exists in Halo it's asset type will not be updated when syncing with Google Workspace.

Don't update the asset site for existing or matched assets - When enabled, if an asset already exists in Halo it's site will not be updated when syncing with Google Workspace.

Do not create new Asset records (update only) - When enabled, new assets will not be able to be created when syncing with Google Workspace, the sync will only update existing assets. 


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