Difference between revisions of "Google Workspace User Import"

From Hornbill
Jump to navigation Jump to search
 
(10 intermediate revisions by one other user not shown)
Line 1: Line 1:
 +
This document can now be found at its new location in the [https://docs.hornbill.com/data-imports-guide/users/google/overview Hornbill Document Library].
 +
 +
[[file:hornbill-document-library.png|Data Imports Guide|link=https://docs.hornbill.com/data-imports-guide/users/google/overview]]
 +
 +
<!--
 +
 
<div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;">
 
<div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;">
 
{| style="width:100%"
 
{| style="width:100%"
Line 11: Line 17:
 
== About the Google Workspace User Import Utility ==
 
== About the Google Workspace User Import Utility ==
 
The utility provides a simple, safe and secure way to create user accounts on the Hornbill platform by synchronizing with accounts held in your Google Workspace domains.  The tool is designed to run behind your corporate firewall, safely and securely connect to Google via your Hornbill instance, query the required account information, transform and load into the Hornbill instance.  The tool connects to the Hornbill in the cloud over HTTPS/SSL so as long as you have standard internet access then you should be able to use tool without the need to make any firewall configuration changes.  The tool supports both the initial bulk import as well as incremental adds and updates.  You can schedule the tool to run periodically to perform the import/update tasks as required.
 
The utility provides a simple, safe and secure way to create user accounts on the Hornbill platform by synchronizing with accounts held in your Google Workspace domains.  The tool is designed to run behind your corporate firewall, safely and securely connect to Google via your Hornbill instance, query the required account information, transform and load into the Hornbill instance.  The tool connects to the Hornbill in the cloud over HTTPS/SSL so as long as you have standard internet access then you should be able to use tool without the need to make any firewall configuration changes.  The tool supports both the initial bulk import as well as incremental adds and updates.  You can schedule the tool to run periodically to perform the import/update tasks as required.
−
 
−
=== Open Source ===
 
−
 
−
The Google Workspace User Import Utility is provided open source under the [https://wiki.hornbill.com/index.php/The_Hornbill_Community_License_(HCL) Hornbill Community Licence] and can be found [https://github.com/hornbill/goHornbillGoogleUserImport here] on GitHub
 
  
 
|style="width:5%"|
 
|style="width:5%"|
Line 32: Line 34:
  
 
=== Windows Installation ===
 
=== Windows Installation ===
−
* Download the architecture specific [https://github.com/hornbill/goHornbillGoogleUserImport/releases/latest latest package] from GitHub  
+
* Download the architecture specific [https://github.com/hornbill/user-import-google/releases/latest latest package] from GitHub  
 
* Extract zip into a folder you would like the application to run from e.g. '''C:\Hornbill_Import\'''
 
* Extract zip into a folder you would like the application to run from e.g. '''C:\Hornbill_Import\'''
 
* Open '''conf.json''' and add in the necessary configuration
 
* Open '''conf.json''' and add in the necessary configuration
−
* Open Command Line Prompt as Administrator
+
* Open Command Line Prompt
−
* Change Directory to the folder with goHornbillGoogleUserImport.exe '''C:\Hornbill_Import\'''
+
* Change Directory to the folder with user_import_google.exe '''C:\Hornbill_Import\'''
−
* Run the command goHornbillGoogleUserImport.exe -instance=yourinstanceid -apikey=yourapikey -file=gconf.json -dryrun=true
+
* Run the command user_import_google.exe -file=conf.json -dryrun=true
  
 
== HTTP Proxies ==
 
== HTTP Proxies ==
Line 187: Line 189:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
====Configuration Details====
 +
 +
* <code>GoogleConf</code>
 +
:* <code>KeysafeID</code> - The ID of the Keysafe Key that the utility will use to authenticate all Google Workspace requests with. See the [[Google Workspace]] page for more information regarding creating this key.
 +
:* <code>Customer</code> - The unique ID for the customer's Google Workspace account. In case of a multi-domain account, to fetch all groups for a customer, fill this field instead of '''Domain'''. You can also use the '''my_customer''' alias to represent your account's '''Customer''' ID. Either the '''Customer''' or '''Domain''' property must be provided.
 +
:* <code>Domain</code> - The domain name. Use this field to get groups from only one domain. To return all domains for a customer account, use the '''Customer''' property instead. Either the '''Customer''' or '''Domain''' property must be provided.
 +
:* <code>Query</code> - Query string for searching user fields. For more information on constructing user queries, see the [[https://developers.google.com/admin-sdk/directory/v1/guides/search-users Search for Users Google Documentation]].
 +
:* <code>Show Deleted</code> - boolean true or false. If true, the API call to Google will return information about any deleted accounts. This is particularly useful for processing leavers, and setting their Hornbill accounts to archived.
 +
* <code>User</code>
 +
:* <code>Operation</code> - both / create / update - import actions to perform on the discovered user records
 +
:* <code>HornbillUserIDColumn</code> - The column to match Google users against Hornbill users
 +
:* <code>AccountMapping</code> - The Hornbill user account fields to match your discovered Google user record fields against
 +
:* <code>ProfileMapping</code> - The Hornbill user extended profile fields to match your discovered Google user record fields against
 +
:* <code>Type</code>
 +
::* <code>Action</code> - both / create / update - import actions to perform account type updates on the discovered user records
 +
:* <code>Status</code>
 +
::* <code>Action</code> - both / create / update - import actions to perform account status updates on the discovered user records
 +
::* <code>Value</code> - active / suspended / archived
 +
:* <code>Role</code>
 +
::* <code>Actio</code> - both / create / update - import actions to perform account roles on the discovered user records
 +
::* <code>Roles</code> - An array of roles to apply to the discovered users
 +
:* <code>Image</code>
 +
::* <code>Action</code> - both / create / update - import actions to perform account profile image updates on the discovered user records
 +
:* <code>Site</code>
 +
::* <code>Action</code> - both / create / update - import actions to perform account profile site updates on the discovered user records
 +
::* <code>Value</code> - Mappable name of the site to apply to the discovered users records
 +
:* <code>Org</code> - Organisational units to associate the imported users with
 +
::* <code>Action</code> - both / create / update - import actions to perform account organisational unit updates on the discovered user records
 +
::* <code>Value</code> - Mappable name of the organisational unit to apply to the discovered users records
 +
::* <code>Options</code>
 +
:::* <code>Type</code> - general / team / department / costcenter / division / company - the type of organisation unit
 +
:::* <code>Membership</code> - member / teamLeader / manager
 +
:::* <code>TasksView</code> - true / false - if set true, then the user can view tasks assigned to this group
 +
:::* <code>TasksAction</code> - true / false - if set true, then the user can action tasks assigned to this group
 +
:::* <code>OnlyOneGroupAssignment</code> - true / false - if set to true, then only one group of this type can be associated to the user. Any other group memberships for the user & type that existed before the import will be removed and replaced by this single group
 +
* <code>Actions</code> - a list of pre-import actions to perform on discovered user properties
 +
:* <code>Action</code> - Regex / Replace / Trim - the action to be performed
 +
:* <code>Value</code> - The value to perform the action of. Can be hard-coded or mapped with template variables
 +
:* <code>Output</code> - the name of the new property to store the action output in. These are placed in the discovered user data, and can then be mapped to using templates in both the '''AccountMapping''' and '''ProfileMapping''' objects
 +
:* <code>Options</code> - The options that can be set for the action -
 +
::* <code>ReplaceOld</code> - Action "Replace" - The "old" string to be replaced from the Value string
 +
::* <code>ReplaceNew</code> - Action "Replace" - The string to replace the "old" string from above with, from the Value string
 +
::* <code>RegexValue</code> - Action "Regex" - The regular expression to perform against the Value
 +
* <code>Advanced</code>
 +
:* <code>LogLevel</code> - The log level to apply to the output
 +
:* <code>LogRetention</code> - The number of days to keep logs for
 +
<br>
 +
<br>
  
 
====Associating a Site to Hornbill User Accounts====
 
====Associating a Site to Hornbill User Accounts====
Line 206: Line 257:
 
<br>
 
<br>
 
<br>
 
<br>
 +
====Google Workspace - Available Properties====
 +
Aside from the standard set of properties provided by Google (see [[https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User the User object documentation for more information]], we also provide a list of other useful properties that you can use in your templates:
 +
 +
* Extended (or flattened) user properties:
 +
:* familyName
 +
:* fullName
 +
:* givenName
 +
:* homePhone
 +
:* workPhone
 +
:* mobilePhone
 +
:* managerEmail
 +
:* jobTitle
 +
:* employeeId
 +
:* employeeType
 +
:* languageCode
 +
:* customAddress
 +
:* homeAddress
 +
:* otherAddress
 +
:* workAddress
 +
* Location type properties:
 +
:* buildingId
 +
:* customType
 +
:* deskCode
 +
:* floorName
 +
:* floorSection
 +
 
== Preparing to Run the Import ==
 
== Preparing to Run the Import ==
 
Ultimately, the executable will be scheduled in Windows task scheduler (see later) but to test, gain confidence, and perform the initial upload of users the utility can be executed from a command prompt window on an ad-hoc basis. The command used to execute the import can contain a number of command line parameters.
 
Ultimately, the executable will be scheduled in Windows task scheduler (see later) but to test, gain confidence, and perform the initial upload of users the utility can be executed from a command prompt window on an ad-hoc basis. The command used to execute the import can contain a number of command line parameters.
−
* instance - MANDATORY - The (case-sensitive) ID for your Hornbill instance, for example: <nowiki>https://live.hornbill.com/</nowiki>'''instanceid'''/
+
 
−
* apikey - MANDATORY - An API key for a user on your Hornbill instance that has the correct rights to make the API calls in the tool. See API Key Rules below for more information
+
=== Command Line Parameters ===
 +
 
 
* file - Defaults to '''''conf.json''''' - Name of the Configuration file to load
 
* file - Defaults to '''''conf.json''''' - Name of the Configuration file to load
−
* dryrun - Defaults to '''''false''''' - Set to True and the XMLMC for Create and Update users will not be called and instead the XML will be dumped to the log file, this is to aid in debugging the initial connection information
+
* dryrun - Defaults to '''''false''''' - Set to True and the XMLMC for Create and Update users will not be called and instead the XML will be dumped to the log file, this is to aid in debugging the initial connection information.
−
* workers - Defaults to '''''3''''' - Allows you to change the number of worker threads used to process the import, this can improve performance on slow import but using too many workers have a detriment to performance of your Hornbill instance
+
* workers - Defaults to `3` - Allows you to change the number of worker threads used to process the import, this can improve performance on slow import but using too many workers have a detriment to performance of your Hornbill instance.
−
* debug - Defaults to '''''false''''' - Outputs extra information to the log to help with debugging issues.
+
* forcerun - This should '''only''' be used in the event of the error''' ''Unable to run import, a previous import is still running'' ''' to force the import to ignore the "running" status.
−
* apitimeout - Defaults to '''''60''''' - The number of seconds allowed before timing out API calls
+
* creds - Defaults to `false` - Set to `true` to decrypt and output the API key that is stored locally. NOTE - the tool will prompt you for your instance ID, and this can only be decrypted by the user who originally performed the encryption, and only on the same machine that it was encrypted on.
 +
 
 +
=== First Run ===
 +
 
 +
From version '''2.0.0''' of the User Import - Google utility, when you first run the utility it will prompt you for the ID of your Hornbill instance (case-sensitive), and the API key (also case-sensitive) that will be used to authenticate the API calls back into Hornbill. This information will be encrypted, and stored locally on the client PC that will be running the tool. For each subsequent import run, the utility will decrypt your instance ID and API key, and will use those to make the API calls back into Hornbill.
 +
 
 +
NOTE - the encrypted instance ID and API key can only be decrypted on the computer, and by the user, that performed the encryption, so please keep this in mind when scheduling your imports.
 +
 
 +
Should you wish to use a different API key to what has been previously encrypted, just delete the '''import.cfg''' file from the folder where the import binary resides, and re-run your import from the command line inputting the Instance ID and new API Key as you would have on its first run.
  
 
== Testing Overview ==
 
== Testing Overview ==
Line 254: Line 340:
  
 
== API Key Rules ==
 
== API Key Rules ==
−
This utility uses ([[API keys]]):
+
This utility uses ([[API keys]]) that require rights to the following APIs:
  
 
* activity:profileImageSet
 
* activity:profileImageSet
Line 293: Line 379:
  
 
=== Windows ===
 
=== Windows ===
−
You can schedule .exe to run with any optional command line argument from Windows Task Scheduler.
+
You can schedule goHornbillGoogleUserImport.exe to run with any optional command line argument from Windows Task Scheduler.
−
* Ensure the user account running the task has rights to Azure2UserImport.exe and the containing folder.
+
* Ensure the user account running the task has rights to goHornbillGoogleUserImport.exe and the containing folder.
 
* Make sure the Start In parameter contains the folder where the executable resides in, otherwise it will not be able to pick up the correct path. eg:
 
* Make sure the Start In parameter contains the folder where the executable resides in, otherwise it will not be able to pick up the correct path. eg:
 +
-->
 +
[[Category:HDOC]]

Latest revision as of 18:49, 11 April 2024

This document can now be found at its new location in the Hornbill Document Library.

Data Imports Guide

Retrieved from "https://wiki.hornbill.com/index.php?title=Google_Workspace_User_Import&oldid=32238"