HaloCRM

HaloCRM Guides

Guides > Google Workspace Integration

Google Workspace Integration

In this guide we will cover:

- Configuring Google Workspace

- Site/Agent Mappings

- Advanced Mappings

- New User Onboarding Ticket Creation

- Licence Management

- Importing Agents and Users

- Asset Imports

- Halo Integrator

- Google Sign-In

- Connecting Multiple Google Workspace Accounts (v2.182.1)



Configuring Google Workspace

To enable the Google Workspace integration, 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.


Connecting as a non-reseller 

If some of your customers use Google services but you are not a reseller of Google you can still integrate their Google directories to your Halo instance. You will need to have admin access to the customer's directory and can then connect to the integration using the details (client ID and secret) from their directory. If you are on versions prior to v2.182 you will only be able to connect to one directory at a time. v2.182+ offers a multi-tenanted version of the integration, you can set up a connection for each of your customer's Google directories. See the section 'Connecting Multiple Google Workspace Accounts (v2.182.1)' for more information on this. 


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.


Fig 1. Connect to Google Workspace.


A common error is the below "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.


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. 


Fig 2. Connected workspace account.


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.


Fig 3. Site/Agent Mappings.


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.


Fig 4. Creating site mapping.


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".


Fig 5. Customer ID field.


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. 


Fig 6. Field Mappings.


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.


Similar mappings are also pre-configured for "Agent Mappings" below this.


Fig 7. Agent Mappings.


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.


Go to the "Advanced" tab. The below information will show at the top of this tab.


Fig 8. Advanced mappings information.


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.


Fig 9. Agent Role Mappings.


Similarly, the mapping shown below will add any imported agent that belongs to the "Development" group to the "Standard Change Approvers" change advise board.


Fig 10. Change Advise Board Mappings.


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. 


User roles can also be mapped to a group, i.e. below is making a group all VIP customers.


Fig 11. User Role Mappings.


New User Onboarding Ticket Creation

The "New User Onboarding" tab allows a ticket to be created when new users are imported for the first time. This can be useful for onboarding processes.


Upon setting a "Template to log when new Users are imported", the rest of the configuration will then appear below. 


Fig 12. New User Onboarding tab.


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.


Fig 13. Enable licence management and role mappings.


Importing Agents and Users

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 if using multiple.


Fig 14. Agent/User Imports mappings.


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). 


Fig 15. Asset Matching field and Customer Mappings.


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. 


Fig 16. Asset Types defaults.


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: 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'. 


Fig 17. Using a field for asset type mapping.


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. 


Fig 18. Asset Type Mappings.


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. 


Note: If Mobile options do not appear, disconnect and reauthorise your Google Workspace account.


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. 


Fig 19. Field Mappings.


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. 


Fig 20. Halo Integrator being enabled, and setting entities to import.


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.


Fig 21. Google Sign-In configuration.


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. 


Note: 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.


Connecting Multiple Google Workspace Accounts (v2.182.1)

As of v2.182.1, multi-tenancy can be used on the Google Workspace integration. This means multiple Workspace instances can be connected to Halo.


When clicking into the Google Workspace integration, there will be a button to "Add/Edit Tenants".


Fig 22. Multi-tenancy on Google Workspace.


Clicking into this will show a list of the set-up tenants. If you already have an instance set-up, it will now show under "Default", and you can add extra instances like "Halo" has been setup below. Just click "New" in the top right corner. Configuration of your original tenant is now all held in that "Default" tenant. You can rename this "Default" tenant as well if you wish.


Fig 23. List of tenants.


Configuration of an additional tenant is exactly the same as setting up the first one, with all the same configuration options.

Popular Guides

Pin It on Pinterest