Difference between revisions of "Azure User Import"

From Hornbill
Jump to navigation Jump to search
 
(55 intermediate revisions by 7 users 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/azure/overview Hornbill Document Library].
 +
 +
[[file:hornbill-document-library.png|Data Imports Guide|link=https://docs.hornbill.com/data-imports-guide/users/azure/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 5: Line 11:
 
|}
 
|}
 
</div>
 
</div>
 +
 +
{|style="width: 100%"
 +
|- valign="top"
 +
|style="width:73%"|
 
== About the Hornbill Azure User Import Utility ==
 
== About the Hornbill Azure 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 Azure AD.  The tool is designed to run behind your corporate firewall, connect to your Azure instance, query the required account information, transform and load into the Hornbill instance.  The tool connects to the Hornbill and Azure instances 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 Azure AD.  The tool is designed to run behind your corporate firewall, connect to your Azure instance, query the required account information, transform and load into the Hornbill instance.  The tool connects to the Hornbill and Azure instances 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 employs the Azure Graph API to query the contents of Azure AD. If you would like to know more about this API and it's capabilities, please refer to the relevant Microsoft documentation: [https://docs.microsoft.com/en-gb/azure/active-directory/develop/active-directory-graph-api '''Azure Graph API Information''']
+
=== Open Source ===
  
−
The last utility using the Azure Graph API is version 1.4.4 [https://github.com/hornbill/goAzure2HUserImport/tree/v1.4.4 (download from GitHub)]
+
The Azure User Import Utility is no longer provided open-source, and is maintained solely by Hornbill as a closed-source, but free-to-use, tool.
  
−
As of '''v2.0.0''' the utility uses the Microsoft Graph API instead. Please refer to [https://docs.microsoft.com/en-gb/graph/ '''Microsoft Graph API Information''']. Please note that you will likely need to set a different set of permissions AND generate a new ClientSecret for the changes to take effect.
+
|style="width:5%"|
 +
|
 +
|style="width:22%; border-style: solid; border-width: 1px; border-color:#e6e6e6; background-color:#f2f2f2;"|
  
−
=== Open Source ===
+
== Related Articles ==
−
 
+
:* [[Azure App Registration Instructions]]
−
The Azure 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/goAzure2HUserImport here] on GitHub
+
:* [[User Import TimeZone Fields Options]]
 +
:* [[User Import DateTime Format Options]]
 +
:* [[API keys|Hornbill API Keys]]
 +
:* [[Hornbill KeySafe]]
 +
:* [[Users|Hornbill Users]]
 +
:* [[Organisation|Hornbill Organisations]]
 +
|}
  
 
== Installation Overview ==
 
== Installation Overview ==
  
 
=== Windows Installation ===
 
=== Windows Installation ===
−
* Download the [https://github.com/hornbill/goAzure2HUserImport/releases/latest latest package] from GitHub  
+
* Download the architecture specific [https://github.com/hornbill/user-import-azure/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 configration
+
* Open '''conf.json''' and add in the necessary configuration
 
* Open Command Line Prompt as Administrator
 
* Open Command Line Prompt as Administrator
−
* Change Directory to the folder with goAzure2HUserImport_x86.exe '''C:\Hornbill_Import\'''
+
* Change Directory to the folder with azure_user_import.exe '''C:\Hornbill_Import\'''
−
* Run the command goAzure2HUserImport_x86.exe -dryrun=true
+
* Run the command azure_user_import.exe -dryrun=true
−
 
 
−
Change "x86" to "x64" depending on your architecture
 
  
 
== HTTP Proxies ==
 
== HTTP Proxies ==
  
−
If you use a proxy for all of your internet traffic, the HTTP_PROXY Environment variable needs to be set. The https_proxy environment variable holds the hostname or IP address of your proxy server. It is a standard environment variable and like any such variable, the specific steps you use to set it depends on your operating system.
+
{{UtilityProxies}}
−
 
 
−
For windows machines, it can be set from the command line using the following:
 
−
<br>
 
−
<code>
 
−
set HTTP_PROXY=HOST:PORT
 
−
</code>
 
−
<br>
 
−
Where "HOST" is the IP address or host name of your Proxy Server and "PORT" is the specific port number.
 
−
 
 
−
=== URLs to White List ===
 
−
 
 
−
Occasionally on top of setting the HTTP_PROXY variable the following URLs need to be white listed to allow access out to our network
 
−
 
 
−
* https://files.hornbill.com/instances/INSTANCENAME/zoneinfo - Allows access to lookup your Instance API Endpoint
 
−
* https://files.hornbill.co/instances/INSTANCENAME/zoneinfo - Backup URL for when files.hornbill.com is unavailable
 
−
* https://eurapi.hornbill.com/INSTANCENAME/xmlmc/ - This is your Instance API Endpoint, eurapi can change so you should use the endpoint defined in the previous URL
 
−
* https://api.github.com/repos/hornbill/goAzure2HUserImport/tags - '''Optional''' Allows access to check for the latest version of the Import Tool
 
  
 
== Configuration Overview ==
 
== Configuration Overview ==
 
Prior to configuring the .json file, it is advisable to read the following wiki page regarding [[users|'''Hornbill User Accounts''']] as it will provide some context to the content on this page.
 
Prior to configuring the .json file, it is advisable to read the following wiki page regarding [[users|'''Hornbill User Accounts''']] as it will provide some context to the content on this page.
 
<br>
 
<br>
−
===API Keys===
 
−
There is an additional element of Hornbill configuration that we'll call upon when completing the configuration An [[API_keys|'''API key''']] needs to be created and will be used by the import utility to access your Hornbill instance.
 
−
<br>
 
−
===Completing the Configuration File===
 
−
A default configuration file called conf.json is provided, if a configuration file is not specified as a command line argument then conf.json must exist. At first glance, the conf.json seems quite lengthy, however it can be broken down into sections and each of these sections tackled one by one.
 
 
<br>
 
<br>
 +
A default configuration file is provided conf.json, if a configuration file is not specified as a command line argument then conf.json must exist.
  
−
    {
+
  {
−
     "APIKey": "",
+
     "KeysafeKeyID": 0, /* this is the Keysafe key ID, which contains your database credentials */
−
    "InstanceId": "",
 
−
    "UpdateUserType": false,
 
−
    "UserRoleAction": "Create",
 
 
     "AzureConf": {
 
     "AzureConf": {
−
        "Tenant": "",
 
−
        "ClientID": "",
 
−
        "ClientSecret": "",
 
 
         "UserFilter": "startswith(displayName,'Dave')",
 
         "UserFilter": "startswith(displayName,'Dave')",
 +
        "UserProperties": [ /* list all the fields that you require from Azure */
 +
            "businessPhones",
 +
            "employeeId",
 +
            "mailNickname",
 +
            "mail",
 +
            "givenName",
 +
            "surname",
 +
            "telephoneNumber",
 +
            "department"
 +
        ],
 
         "UserID": "mail",
 
         "UserID": "mail",
 
         "Debug": false,
 
         "Debug": false,
−
         "APIVersion":"1.6",
+
         "APIVersion":"v1.0", /* Azure API Version - leave as-is */
 
         "Search":"groups",
 
         "Search":"groups",
 
         "UsersByGroupID":[
 
         "UsersByGroupID":[
Line 86: Line 85:
 
         ]
 
         ]
 
     },
 
     },
−
     "UserMapping":{
+
     "User": {
−
        "userId":"<nowiki>{{.mail}}</nowiki>",
+
      "Operation":"Both", /* options : Create/Update/Both ; import actions to perform on the discovered user records */
−
        "UserType":"basic",
+
      "UserDN": "&#123;&#123;.userPrincipalName&#125;&#125;",
−
        "Name":"<nowiki>{{.givenName}} {{.surname}}</nowiki>",
+
      "AccountMapping":{ /* mapping of fields in the format: "Field in Hornbill": "data to insert" [4] */
−
        "Password":"",
+
          "UserID":"&#123;&#123;.mail&#125;&#125;",
−
        "FirstName":"<nowiki>{{.givenName}}</nowiki>",
+
          "LoginID":"&#123;&#123;.mail&#125;&#125;",
−
        "LastName":"<nowiki>{{.surname}}</nowiki>",
+
          "EmployeeID":"&#123;&#123;.mail&#125;&#125;",
−
        "JobTitle":"",
+
          "UserType":"basic", /* (basic vs user) */
−
        "Site":"<nowiki>{{.physicalDeliverOfficeName}}</nowiki>",
+
          "Name":"&#123;&#123;.givenName&#125;&#125; &#123;&#123;.surname&#125;&#125;",
−
        "Phone":"<nowiki>{{.telephoneNumber}}</nowiki>",
+
          "Password":"", /* if left blank a random password will be generated [7] */
−
        "Email":"<nowiki>{{.mail}}</nowiki>",
+
          "FirstName":"&#123;&#123;.givenName&#125;&#125;",
−
        "Mobile":"<nowiki>{{.mobile}}</nowiki>",
+
          "LastName":"&#123;&#123;.surname&#125;&#125;",
−
        "AbsenceMessage":"",
+
          "JobTitle":"",
−
        "TimeZone":"",
+
          "Site":"1", /* if set, see also comments below on SiteLookup [8] */
−
        "Language":"",
+
          "Phone":"&#123;&#123;index .businessPhones 1&#125;&#125;",
−
        "DateTimeFormat":"",
+
          "Email":"&#123;&#123;.mail&#125;&#125;",
−
        "DateFormat":"",
+
          "Mobile":"",
−
        "TimeFormat":"",
+
          "AbsenceMessage":"",
−
        "CurrencySymbol":"",
+
          "TimeZone":"", /* see [[User Import TimeZone Fields Options]] */
−
        "CountryCode":""
+
          "Language":"", /* ISO 629 in combination with ISO 3166 as per [https://en.wikipedia.org/wiki/Language_localisation this wikipedia entry] */
−
    },
+
          "DateTimeFormat":"", /* see [[User Import DateTime Format Options]] */
−
    "UserAccountStatus":{
+
          "DateFormat":"",
−
        "Action":"Both",
+
          "TimeFormat":"",
−
         "Enabled": false,
+
          "CurrencySymbol":"", /* any character */
−
        "Status":"active"
+
          "CountryCode":"" /* expects ISO 3166 Alpha 2 two Character Country Code [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes (see here)] */
−
    },
+
          "Enable2FA": "disabled",
−
    "UserProfileMapping":{
+
          "DisableDirectLogin": "false",
−
        "MiddleName":"",
+
          "DisableDirectLoginPasswordReset": "false",
−
        "JobDescription":"",
+
          "DisableDevicePairing": "false"
−
         "Manager":"<nowiki>{{.manager}}</nowiki>",
+
        },
−
        "WorkPhone":"",
+
        "Type":{
−
        "Qualifications":"",
+
          "Action":"Create" /* options : Create/Update/Both ; setting to Basic User (as opposed to Full User) */
−
        "Interests":"",
+
        },
−
        "Expertise":"",
+
         "Status":{
−
        "Gender":"",
+
          "Action":"Both", /* options : Create/Update/Both ; on what action to change the User Account Status */
−
        "Dob":"",
+
          "Value":"active" /* options : active/suspended/archived */
−
        "Nationality":"",
+
        },
−
        "Religion":"",
+
        "Role":{
−
        "HomeTelephone":"<nowiki>{{.telephoneNumber}}</nowiki>",
+
            "Action":"Both" /* options : Create/Update/Both ; on what action to change the User Role */
−
        "SocialNetworkA":"",
+
            , "Roles":[ /* list of Roles assigned to the users being imported */
−
        "SocialNetworkB":"",
+
              "Basic User Role"
−
        "SocialNetworkC":"",
+
            ]
−
        "SocialNetworkD":"",
+
        },
−
        "SocialNetworkE":"",
+
         "ProfileMapping":{ /* further fields [5]  */
−
        "SocialNetworkF":"",
+
          "MiddleName":"",
−
        "SocialNetworkG":"",
+
          "JobDescription":"",
−
        "SocialNetworkH":"",
+
          "Qualifications":"",
−
        "PersonalInterests":"",
+
          "Interests":"",
−
        "homeAddress":"",
+
          "Expertise":"",
−
        "PersonalBlog":"",
+
          "Gender":"",
−
        "Attrib1":"",
+
          "Dob":"",
−
    "Attrib2":"",
+
          "Nationality":"",
−
    "Attrib3":"",
+
          "Religion":"",
−
    "Attrib4":"",
+
          "HomeTelephone":"&#123;&#123;.telephoneNumber&#125;&#125;",
−
    "Attrib5":"",
+
          "SocialNetworkA":"",
−
    "Attrib6":"",
+
          "SocialNetworkB":"",
−
    "Attrib7":"",
+
          "SocialNetworkC":"",
−
    "Attrib8":""
+
          "SocialNetworkD":"",
 +
          "SocialNetworkE":"",
 +
          "SocialNetworkF":"",
 +
          "SocialNetworkG":"",
 +
          "SocialNetworkH":"",
 +
          "PersonalInterests":"",
 +
          "homeAddress":"",
 +
          "PersonalBlog":"",
 +
          "Attrib1":"1",
 +
          "Attrib2":"2",
 +
          "Attrib3":"3",
 +
          "Attrib4":"4",
 +
          "Attrib5":"5",
 +
          "Attrib6":"6",
 +
          "Attrib7":"7",
 +
          "Attrib8":"8"
 +
        },
 +
        "Manager":{
 +
            "Action": "Both" /* options : Create/Update/Both/__clear__/__clear_if_empty__ ; on what action to change the User's Manager */
 +
            , "AzField": "userPrincipalName" /* field in Azure containing the manager's unique identifier - (default: userPrincipalName) */
 +
            , "HornbillUniqueColumn":"h_user_id"  /* field in Hornbill to match resulting AzField to - (default:h_user_id) */
 +
        }
 +
      }
 
     }
 
     }
−
     , "UserManagerMapping":{
+
     , "Image":{ /* Profile Image configuration section [10] */
−
        "Action":"Both"
+
      "Action":"Both" /* options : Create/Update/Both ; on what action to change the Image */
−
        , "Enabled":true
+
      , "UploadType": "AZURE" /* options : URI/URL/AZURE ; local (network) drive or HTTP(S) served image */
−
    }
+
      , "InsecureSkipVerify": false
−
    , "Roles":[
+
      , "ImageType": "jpg" /* options : jpg/png */
−
        "Basic User Role"
+
      , "ImageSize": "240" /* options: ""/48/64/96/120/240/360/432/504/648 [https://docs.microsoft.com/en-us/graph/api/profilephoto-get see  restrictions]; "" will use the default MS thumbnail size */
−
    ]
+
      , "URI": "&#123;&#123;.id&#125;&#125;"
−
    , "SiteLookup":{
 
−
        "Action":"Both"
 
−
        , "Enabled": true
 
 
     }
 
     }
−
     , "ImageLink":{
+
     , "Site":{
−
        "Action":"Both"
+
      "Action":"Both" /* options : Create/Update/Both ; on what action to change the User's Site [9] */
−
        , "Enabled": false
+
      , "Value": "&#123;&#123;.physicalDeliveryOfficeName&#125;&#125;"
−
        , "UploadType": "URL"
 
−
        , "ImageType": "jpg"
 
−
        , "URI": "<nowiki>http://whatever.server.com/userdb/images/{{.mail}}</nowiki>.jpg"
 
 
     }
 
     }
−
     , "OrgLookup":{
+
     , "Org":[ /* Organisational Units to associate the imported user with [6] */
 +
      {
 +
        "Action":"Both" /* options : Create/Update/Both ; on what action to add to the organisational structure */
 +
        , "value":"&#123;&#123;.department&#125;&#125;" /* name of organisational unit */
 +
        , "MemberOf":""
 +
        , "Options": {
 +
          "Type":2, /* options : 0,...,5 ; type of organisational unit, respectively: general/team/department/costcenter/division/company */
 +
          "Membership":"member", /* options : member/teamLeader/manager */
 +
          "TasksView":false, /* options : true/false ; If set true, then the user can view tasks assigned to this group */
 +
          "TasksAction":false, /* options : true/false ; If set true, then the user can action tasks assigned to this group */
 +
          "OnlyOneGroupAssignment":false
 +
        }
 +
      }
 +
      , {
 
         "Action":"Both"
 
         "Action":"Both"
−
         , "Enabled":true
+
         , "value":"Great Company"
−
         , "OrgUnits":[
+
         , "MemberOf":""
−
            {
+
        , "Options": {
−
                "Attribute":"<nowiki>{{.department}}</nowiki>",
+
          "Type":5,
−
                "Type":2,
+
          "Membership":"member",
−
                "Membership":"member",
+
          "TasksView":false,
−
                "TasksView":false,
+
          "TasksAction":false,
−
                "TasksAction":false
+
          "OnlyOneGroupAssignment":false /* options: true/false ; if set to true, then a user can only be associated to a single group at any one time */
−
            }, {
+
        }
−
                "Attribute":"<nowiki>{{.companyName}}</nowiki>",
+
      }
−
                "Type":5,
+
    ]
−
                "Membership":"member",
+
  }
−
                "TasksView":false,
+
  }
−
                "TasksAction":false
 
−
            }
 
−
        ]
 
−
    }
 
  
−
# An API key is set up against a user within Hornbill (accessed through: Administration > System > Organisationl Data > Users).
 
−
# There are instructions on-line on how to obtain the Secret ID
 
−
# please note that all field names are specified as lowercase - this is to ensure smooth running for the mapped fields.
 
 
# The fields are quite self-explanatory and part of the "Details"-section (as opposed to the "About"-section [5]), most can be left as-is. The mapping is done with some templating of the format &#123;&#123;fieldname&#125;&#125;. One can be a little adventurous, for instance "&#123;&#123;.mgrfirstname&#125;&#125; - &#123;&#123;.mgrlastname&#125;&#125;" puts a space, hyphen and space between the person's manager's first and last name. One can use this to prefix or suffix the values coming from the database or indeed to set a static value (as done for example with userType and Attribute under OrgLookup for the company (Type:5)).
 
# The fields are quite self-explanatory and part of the "Details"-section (as opposed to the "About"-section [5]), most can be left as-is. The mapping is done with some templating of the format &#123;&#123;fieldname&#125;&#125;. One can be a little adventurous, for instance "&#123;&#123;.mgrfirstname&#125;&#125; - &#123;&#123;.mgrlastname&#125;&#125;" puts a space, hyphen and space between the person's manager's first and last name. One can use this to prefix or suffix the values coming from the database or indeed to set a static value (as done for example with userType and Attribute under OrgLookup for the company (Type:5)).
−
# The same holds here as for [4], this is regarding the "About"-section of the user's details.
+
# The same holds here as for [1], this is regarding the "About"-section of the user's details.
−
# this is a non-ordered list of the organisation structure - it allows one to associate the imported user to one or more levels within the organisation. The delivered configuration file will associate each imported user with EACH of the three discernable levels (company, department and division) - depending on your requirements regarding the availability of services and such, you will likely want to manipulate this section and perhaps only leave behind the "department" level (Type: 2) with the TasksView and TasksAction set accordingly. Please note that this import only adds and not REMOVE any association.
+
# this is a non-ordered list of the organisation structure - it allows one to associate the imported user to one or more levels within the organisation. The delivered configuration file will associate each imported user with EACH of the three discernable levels (company, department and division) - depending on your requirements regarding the availability of services and such, you will likely want to manipulate this section and perhaps only leave behind the "department" level (Type: 2) with the TasksView and TasksAction set accordingly. Please note that this import only adds and not REMOVES any association.
 +
# The password field should be left empty as the utility generates a secure password that adheres to the User Password Policy as specified on your Hornbill instance. This password will only be temporary as the user should use the "Forgot Password" link available on the Hornbill Login Screen to reset their password the first time they navigate to your Hornbill instance.
 +
# "Site" - Recognises a corresponding Hornbill site ID. E.g. "Site":"1" - The value of Site should be numeric. As an alternative, the import configuration provides a "Site Lookup" section (outlined in a later section) which can make a site association based on the contents of a directory attribute.
 +
# If a lookup action is not needed, remove the action type so only empty quotes are left i.e. ''"Action":""''
 +
# "Image" - by default this will take the thumbnail image. IF ''.id'' does NOT work for the '''"URI"''', please try ''.userPrincipalName'' instead.
 +
<br>
 +
<br>
 +
===Keysafe===
 +
You will need to create a [[Hornbill_KeySafe|'''KeySafe record''']] of type "Azure Imports" and set Client ID, Client Secret and Tenant ID. The KeySafeID can be obtained from looking at the URL of the KeySafe record <nowiki>https://live.hornbill.com/</nowiki>'''instanceid'''<nowiki>/security/keysafe/</nowiki>''#KeySafeID''<nowiki>/</nowiki>
 +
 
 +
'''Note:''' There are relevant Microsoft instructions online on how to obtain the ClientID and ClientSecret from within Azure - [[Azure App Registration Instructions|our quickstart version]]. We have found that the following permissions need to be granted within Azure, though these could differ for you, so please rely on your own expertise. Application permissions on: ''Group.Read.All, GroupMember.Read.All, Team.ReadBasic.All, TeamMember.Read.All, User.Read.All''. Delegated permission on ''User.Read''. The permission settings need to be confirmed.
  
 
=== Filtering ===
 
=== Filtering ===
−
There are two methods of filtering users that you can configure with this tool. They are both defined in the '''AzureConf''' section of the configuration.
+
There are two methods of filtering users that you can configure with this tool. They are both defined in the configuration's ''AzureConf''' section.
  
 
To import all direct User objects within one or more Azure Groups:
 
To import all direct User objects within one or more Azure Groups:
Line 205: Line 236:
 
=== Fields ===
 
=== Fields ===
 
These fields are those which Azure AD recognise as part of an account (eg givenName) they match LDAP variables quite nicely. However, please keep in mind that although for instance multiple email addresses can be set in Azure, only the main one in ''mail'' can be used (unless one makes amendments to the script)
 
These fields are those which Azure AD recognise as part of an account (eg givenName) they match LDAP variables quite nicely. However, please keep in mind that although for instance multiple email addresses can be set in Azure, only the main one in ''mail'' can be used (unless one makes amendments to the script)
 +
 +
====Associating a Site to Hornbill User Accounts====
 +
The DB Import utility has the ability to associate a Hornbill Site record to a user account based on the contents of a field. This is achieved through a "Look-up". The Look up mechanism is quite simple and works in the following manner.
 +
# The import reads the fields (template rules work) that is specified in the "value" field. In the example shown, the '''site''' field is used.
 +
# It takes the content and tries to identify if there is an existing site record in Hornbill with a name that matches the value of the site. e.g. if the site field contained "Brussels", the import would look for a Hornbill Site record with the name "Brussels".
 +
# If a match is found, the import will associate the user to the site.
 +
# If no site record is found, the import will move onto the next user.
 +
i.e. The name of the Site record in Hornbill must match the value of the directory attribute specified. More on Hornbill Sites can be found here: [[Sites|'''Sites''']]
 +
<br>
 +
<br>
 +
====Associating a Group to Hornbill User Accounts====
 +
The DB Import has the ability to associate a Hornbill Group to a user account based on the contents of a fieldname. This is achieved through a "Look-up". The Look up mechanism is quite simple and works in the following manner.
 +
# The utility reads the attribute that is specified in the orgLookup section. In the example shown, the '''department''' field is used.
 +
# It takes the content and tries to identify if there is a Hornbill Group that exists with a name that matches the value of the field name. e.g. if the '''department''' field contained "Accounting", the utility would look for a Hornbill Group called "Accounting".
 +
# If a match is found, the import will associate the user to the group.
 +
# If no Hornbill organisation is found, the import will move onto the next user.
 +
i.e. The name of the Organization(Group) in Hornbill must match the value of the database field. More on Hornbill Organisational Groups can be found here: [[Organisation|'''Organisation Structure''']]
 +
<br>
 +
<br>
 +
====User Manager Mapping in Hornbill====
 +
Both Hornbill and Azure can store a manager relationship between two users.
 +
 +
The utility will determine the manager for a user as it is stored in Azure and use the field given in '''AzField''' to match this against a user within Hornbill using the field defined in the '''HornbillUniqueColumn'''.
 +
 +
In instances whereby the userPrincipalName is used as the Hornbill User ID, the defaults should suffice.
 +
 +
IF, for instace, Azure's employeeId is used as User ID in Hornbill, then '''AzField''' should be set to '''employeeId'''.
 +
 +
The manager link is handled by the ProfileMapping part in the Hornbill API - so the link will be set on: Both, Create or Update based on what the regular Account is doing.
 +
 +
IF you do '''NOT''' want the Azure Import to set a manager, just do not use any value in the '''Action''' parameter. If you want to activate the manager mapping, then any of the three Both/Create/Update values will suffice.
 +
 +
You have two additional Actions:
 +
* __clear__ - this will remove the managers from each individual found in the Azure search
 +
* __clear_if_empty__ - will remove the managers from each individual found in the Azure search who do NOT have a manager
  
 
== 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 the 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.
−
* 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; instead, the XML will be dumped to the log file to aid in debugging the initial connection information.
 
* file - Defaults to '''''conf.json''''' - Name of the Configuration file to load
 
* file - Defaults to '''''conf.json''''' - Name of the Configuration file to load
 
* zone - Defaults to '''''eur''''' - Allows you to change the ZONE used for creating the XMLMC EndPoint URL: <nowiki>https://{ZONE}api.hornbill.com/{INSTANCE}/</nowiki>
 
* zone - Defaults to '''''eur''''' - Allows you to change the ZONE used for creating the XMLMC EndPoint URL: <nowiki>https://{ZONE}api.hornbill.com/{INSTANCE}/</nowiki>
−
* 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 the performance of your Hornbill instance.
 +
* debug - Defaults to '''''false''''' - outputs extra information to the log to help with debugging issues.
 +
 
 +
From version '''4.0.0''' of the Azure User Import Utility, when you first run the utility it will prompt you for two vital pieces of information:
 +
 
 +
* The Instance ID (also referred to as the instance name) can be found in the URL used by your organisation to access your Hornbill instance i.e. <nowiki>https://live.hornbill.com/</nowiki>'''instanceid'''/ (case sensitive).
 +
* A valid API key. This needs to be created against a Hornbill user account with enough rights to create and update user accounts. Details on how to create an API key can be found [[API_keys|'''here''']].
 +
 
 +
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 relevant API calls back into Hornbill.
 +
 
 +
NOTE - the encrypted information 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 or Keysafe Key ID to what has been previously encrypted, delete the '''import.cfg''' file from the folder where the import binary resides, and re-run your import from the command line inputting the requested details as you would have on its first run.
  
 
== Testing Overview ==
 
== Testing Overview ==
Line 238: Line 316:
 
Example command line:
 
Example command line:
 
<code>
 
<code>
−
goAzure2HUserImport.exe -dryrun=true
+
azure_user_import.exe -dryrun=true
 
</code>
 
</code>
  
Line 251: Line 329:
  
  
−
==Trouble Shooting==
+
== API Key Rules ==
−
=== Logging Overview ===
+
This utility uses ([[API keys]]):
 +
 
 +
* activity:profileImageSet
 +
* admin:keysafeGetKey
 +
* admin:sysOptionGet
 +
* admin:userAddGroup
 +
* admin:userAddRole
 +
* admin:userCreate
 +
* admin:userDeleteGroup
 +
* admin:userProfileSet
 +
* admin:userSetAccountStatus
 +
* admin:userUpdate
 +
* data:entityAddRecord
 +
* data:entityUpdateRecord
 +
* data:queryExec
 +
* session:getSystemLicenseInfo
 +
 
 +
=Troubleshooting=
 +
== Logging Overview ==
  
 
All Logging output is saved in the "log" directory which can be found in the same location as the executable. The file name contains the date and time the import was run '''''Azure_User_Import_2015-11-06T14-26-13Z.log'''''
 
All Logging output is saved in the "log" directory which can be found in the same location as the executable. The file name contains the date and time the import was run '''''Azure_User_Import_2015-11-06T14-26-13Z.log'''''
−
===Common Error Messages===
+
==Common Error Messages==
  
 
Below are some common errors that you may encounter in the log file and what they mean:
 
Below are some common errors that you may encounter in the log file and what they mean:
Line 267: Line 363:
 
* ''' ''[ERROR] Unable to Load LDAP Attribute: '[LDAP attribute name]' For Input Param: '[Hornbill Parameter name]' '' ''' - When the import utility is unable to load a particular LDAP attribute, this means that the attribute field in your directory does not contain a value. This error will not prevent the user account being created or updated in Hornbill and can be considered more as a warning rather than an outright failure or problem.
 
* ''' ''[ERROR] Unable to Load LDAP Attribute: '[LDAP attribute name]' For Input Param: '[Hornbill Parameter name]' '' ''' - When the import utility is unable to load a particular LDAP attribute, this means that the attribute field in your directory does not contain a value. This error will not prevent the user account being created or updated in Hornbill and can be considered more as a warning rather than an outright failure or problem.
 
* ''' ''[ERROR] Unable to Set User Status [status name]: You have reached your user subscription limit of [xx], you will need to expand your subscription level if you wish to add more users'' ''' - The utility is trying to update the user status of an existing user account from an inactive status (i.e. "archived" or "suspended") to "active" however in order for this to be successful you must have some subscriptions available.
 
* ''' ''[ERROR] Unable to Set User Status [status name]: You have reached your user subscription limit of [xx], you will need to expand your subscription level if you wish to add more users'' ''' - The utility is trying to update the user status of an existing user account from an inactive status (i.e. "archived" or "suspended") to "active" however in order for this to be successful you must have some subscriptions available.
 +
* ''' ''[ERROR] Unable to run import, a previous import is still running'' ''' - this can occur if the previous import failed to complete. Perform a manual (non-scheduled) run of the import from the command line including the argument "forcerun=true". Future imports should now run without issue.
  
 
=== Error Codes ===
 
=== Error Codes ===
Line 276: Line 373:
  
 
=== Windows ===
 
=== Windows ===
−
You can schedule .exe to run with any optional command line argument from Windows Task Scheduler.
+
You can schedule azure_user_import.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 azure_user_import.exe and the containing folder.
 +
* Ensure the user account running the task is the one who performed the first run of the tool on this PC, as the instance details are encrypted and can only be decrypted by that user on the current Windows machine
 
* 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:
  
 
[[File:Ldap_import_schedule.png]]
 
[[File:Ldap_import_schedule.png]]
 +
 +
-->
 +
[[Category:HDOC]]

Latest revision as of 18:08, 10 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=Azure_User_Import&oldid=32102"