HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

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

- Additional setup needed to import customer and subscription data (v2.190+)

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


Obtaining Client ID and Secret 

To obtain a client ID and secret required for connection you will need to create access credentials within your Google cloud console. 


First you will need to create a new project within your Google could console, this is where access credentials will be granted and stored. 


To create a new project, open up your Google Cloud console and select the project you are currently on. 

Fig 1. Current Project in Google 


When selected, you will see an option to create a new project. Give the project an appropriate name, choose a location (if applicable) and hit create. 


Now you will need to enable the following APIs for the project:

  • Admin SDK API


To do this head to APIs and services > Enabled APIs and services > Enable APIs and services. 

Fig 2. Enable APIs for project


From here search for the API you need to add> select this from the list and enable. 

Fig 3. Admin SDK API for project


Now this is enabled you can generate a client ID and secret for the project. 


Within your Google cloud console head to Menu > Google Auth Platform > Clients, if this is a new project you will need to configure your Google auth platform for this project. 


Configuring Auth Platform

To start configuration hit the 'Get Started' button on the Google auth platform page. 

Fig 4. Start configuring Auth platform 


When setting up give the app a name and choose a support email. The support email will be displayed to users if signing in with SSO, ensure this is a mailbox that is monitored regularly. If you would like to use google single-sign on you will need to set audience to be 'External'. Otherwise set the audience to be internal. 

Fig 5. Set audience to external


Then you will just need to enter a contact email and agree to the Google API services and data policy. Hit create. 


Now your Auth Platform is set up you can generate a client ID and secret. 


Create a new Client here. 


Fig 6. Create new Client 



From here, select 'Web application' from the dropdown, give the application a name. 


Add the following authorised redirect URI if you are using HaloPSA:

Add the following authorised redirect URI if you are using HaloITSM:

Add the following authorised redirect URI if you are using HaloCRM:



Fig 7. OAuth Client 


Then hit create. Upon creation you will be provided with a client ID and secret. 

Fig 8. Client ID and secret in Halo


Copy and paste this into a notepad for now. 


Note: The whole client ID and secret will need to be used, including the '.apps.googleusercontent.com' section.


Now you will need to assign test users to the OAuth Client to allow the connection to be authenticated. Head to the 'audience' tab and select 'Add users' under the test user section. 


Note: We recommend using test users to authenticate your Google app before publishing the app as this ensures your app works correctly and securely before exposing it to broader users.

Fig 9. Add test user to OAuth Client


When adding a test user you must enter the email (Gmail) of the user you would like to be able to authenticate the connection. You can add multiple users here, then when authenticating the connection between Google Workspace and Halo you must login with an account that has been added to the project as a test user. 


Test user authorisation will expire after 7 days, therefore once you have connected successfully and are happy with the setup you will need to publish your application using the 'Publish app' button shown in figure 9. Once the app is published the authentication will not expire. 


For more information on testing/publishing apps in Google workspace see Manage App Audience.


Additional setup needed to import customer and subscription data (v2.190+)

If you would like to import customer and subscription data from Google Workspace (available from v2.190+) you will need to complete some additional configuration in Google. At present only direct re-sellers of Google can use this functionality as this relies on the 'Google workspace reseller API' which is only available to direct resellers. 


Set-up for Direct Google Resellers

First add the 'Google Workspace Reseller API' to your Google project. 


To do this head to APIs and services > Enabled APIs and services > Enable APIs and services. 

Fig 10. Enable reseller API.


Once enabled head back to the Auth platform within the project as some additional scopes will need to be added. 


Head to the 'Data access' tab and 'Add or remove scopes'.

Fig 11. Add scopes to project.


You will need to add the following scopes:

If these scopes do not appear in the list Google provides when adding a scope, add them manually under the section 'Manually add scopes'. 

Fig 12. Adding scopes to project


Hit 'Add to table', the scopes will now appear in the , they will be auto-selected for you so hit 'Update' to add them to your project. To ensure the scopes have been added check they appear in the 'Sensitive scopes' table on the Data access page. Remember to save this page. 


Enter Connection Details in Halo

Head back into Halo and paste the client ID and secret into the respective fields on the Google Workspace setup page. 


Before you hit 'connect Now' in Halo you will need to wait at least 5 minutes for the OAuth client and redirect URI to take effect, but this could take several hours. We recommend continuing setup the following day.


When connecting 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 13. Connect to Google Workspace.


A common error is the below "App Blocked" message.

#

Fig 14. App Blocked error 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 15. Connected workspace account.


Important: Once you have completed testing/finished setting up the integration ensure you head back to your project in Google Cloud and publish your google OAuth, shown in figure 9.


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 16. 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 17. 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 18. 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 19. 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 20. 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 21. 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 22. 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 23. 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 23. 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 25. 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 26. 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 27. 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 28. 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 29. 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 30. 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 31. 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 32. 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.


Customer/Subscription Imports (v2.190+)

From v2.190+ customers and subscriptions from Google can be imported into Halo. Subscriptions and customers can be imported on a scheduled basis, pulling any changes made (e.g. subscription quantity) in Google into Halo. When used in conjunction with our functionality to automate recurring invoice quantities based on subscription count, this allows you to have your customer invoices in Halo update automatically in line with licence changes made in Google.


You must be a direct reseller of Google to import customer subscriptions from Google. 


This import is configured under the 'Customer/Subscriptions' tab on the Google workspace integration setup. 

Fig 33. Customer/subscription import setup


Prior to setup ensure you have added the 'Google Workspace Reseller API' to your Google cloud project along with the relevant scopes. For information on how to do this see the section 'Configuring Google Workspace' within this guide. 


First enter your 'Parent account Id' this will be the customer ID of your (the MSP's) tenant, this is the tenant that has access to all the customer tenant. This ID can be found within your Google Admin console > account > account settings > profile > see field 'Customer ID'.

Fig 34. Customer ID of the parent tenant


Once this is entered into Halo you can configure customer mappings.


Customer mappings

Halo customers can be mapped to Google customers using the 'Customer Mappings' table. If your Halo and Google customer have the EXACT same name, you can have mappings generated automatically using the 'Generate mappings' button. 


Update the Customer's main Site address in Halo when an existing Customer is imported from Google Workspace - When checked, the main site of each customer in Halo will update to have the address against the customer in Google. 


Once your customer mappings are complete save the page and begin the import using the 'Import customers' button. This will complete a single import, but to have customer data from Google synced to Halo each time a change is made you can enable the Halo integrator for customer sync, see the section 'Halo integrator' for more information on this. Once customer's are imported you can import subscriptions. 


Importing Subscriptions

Before subscriptions can be imported you must ensure you have mapped Halo and Google customers and completed the customer import. The import will ensure Halo customers are linked to the correct Google customer so subscriptions can be matched correctly. 


Import subscriptions using the 'Import Subscriptions' button. When imported subscriptions will be assigned to the correct customer in Halo automatically based on the Google customer this is mapped to. Once subscriptions are imported they will be visible under the 'subscriptions' tab against the customer profile. 


This will complete a one-off import. To have subscription data from Google synced to Halo each time a change is made (e.g. each time subscription quantity changes) you will need to enable the Halo integrator for subscriptions. This will sync subscription changes on a daily basis. For more information see the 'Halo integrator' section. 


Common Errors

The following errors will appear attempting to import licences if you are not a direct re-seller of Google. This is because we are attempting to call the Google reseller API, which your Google account/tenant does not have access to.

 

- 403 Permission Denied

- API not Enabled


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 automatically import user, agent, asset, customer and subscription data on a schedule, when there is a change to one of these entities in Google the change will be synced into Halo each time the integrator runs. 


Enable this using the checkbox 'Enable the Halo Integrator for the Google Workspace integration' then select which entities you would like to sync in the 'Entities to Import' field. 


 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 35. 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 36. 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 37. 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 38. 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