Introduction

Le programme ADSIReader (ESI.Octopus.ADSIReaderApp.exe) permet d'importer les utilisateurs, les ordinateurs (postes de travail et serveurs) et les queues d'impression contenues dans votre Active Directory.

L'importation des utilisateurs peut inclure, entre autres, le prénom, le nom, le nom d'utilisateur Windows, le titre, le département, le numéro de téléphone du bureau (avec le poste téléphonique), etc. alors que l'importation des ordinateurs n'inclut que leurs noms. 

Il est possible par la suite d'utiliser le programme WMIUpdater (ESI.Octopus.WMIUpdaterApp.exe) pour obtenir la configuration technique de l'ordinateur (système d'exploitation, mémoire, type de processeur, logiciels installés, etc.).

Quant aux queues d'impressions, nous suggérons de les exclure avec le paramètre /NoPrintersDetection lors de l'exécution du programme, pour deux raisons :

• Le nom importé n'est pas toujours significatif
• Il peut exister plus d'une queue d'impression pour la même imprimante

On recommande plutôt de faire une importation unique avec le programme DataImporter et ensuite de gérer les imprimantes directement dans Octopus. 

Description du fonctionnement

Lorsque le programme ADSIReader est exécuté, selon les paramètres utilisés, il importera à partir de votre Active Directory, tous les utilisateurs, Ordinateurs et queues d'impression. Les paramètres à utiliser sont importants puisqu'ils permettent de contrôler les données à importer. De plus, un fichier de correspondance (mapping) entre les champs d'Octopus et ceux de AD est disponible à partir du répertoire de votre client Octopus. 

Prérequis

• Création d'un compte système Octopus pour l'associer à la tâche. Voir l'article Compte système Octopus.
• Bonne compréhension de l'impact de ADSIReader sur la gestion de votre parc informatique dans Octopus. Voir l'article ADSIReader - Impacts sur la gestion des ordinateurs.
• Le nom des domaines à explorer, ainsi que les OU devant être exclus.

Utilisation du programme ADSIReader

ADSIReader est un programme de type ligne de commande (DOS). Il est conçu ainsi pour être facile à automatiser (la section Automatisation de l'importation de données provenant de Active Directory vers Octopus décrit comment automatiser l'exécution de ADSIReader).

• Le nom complet du programme ADSIReader est : ESI.Octopus.ADSIReaderApp.exe
• Il est situé dans le répertoire local d'Octopus (C:\Program Files\Octopus) ou dans (\%homepath%\AppData\Local\Octopus).
• Exemple du répertoire où peut se situer Octopus :
  • Pour Windows 7 et plus : C:\Users\slevesque\AppData\Local\Octopus
  • Pour Windows XP : C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

Importation ADSIReader à partir d'une ligne de commande

L'importation d'AD à partir d'une ligne de commande permet d'utiliser différents paramètres qui peuvent éviter de polluer le contenu d'Octopus avec des données non désirées. 

Pour lancer l'exécutable ADSIReader, il faut ouvrir une fenêtre d'invite de commandes (DOS) et se positionner dans le répertoire d'Octopus. Par la suite, il faut entrer la ligne de commande suivante :

ESI.Octopus.ADSIReaderApp.exe /login:system /password:octo /domain:MonDomaine /team:1

Exemple de la ligne de commande dans DOS

Avant de lancer la commande, il est recommandé de valider les paramètres voulus.

Exemples

• Importation des utilisateurs actifs seulement et des ordinateurs, mais sans les queues d'impressions :

ESI.Octopus.ADSIReaderApp.exe /login:system /password:octo /Domain:Octopus-itsm /team:1 /NoPrintersDetection /ActiveUsersOnly

• Importation AD sans mettre à jour la base de données et modification du fichier de journalisation :

ESI.Octopus.ADSIReaderApp.exe /login:system /password:octo /Domain:Octopus-itsm /team:1 /NoDbUpdate /LogFilePath:MonFichier.log

Paramètres

Il y a 21 paramètres disponibles dont 4 obligatoires pour exécuter ADSIReader :

Paramètres obligatoires

• /Login
  • Nom d’utilisateur Octopus
• /Password
  • Mot de passe Octopus
• /Team
  • ​Le numéro de l'équipe à mettre à jour, si l'utilisateur spécifié fait partie de plusieurs équipes. Par défaut, l'équipe TI utilise normalement le numéro d'équipe 1
• /Domain:DomainName
  • Ce paramètre correspond au nom du domaine à importer

Paramètres facultatifs

• /DomainUserName
  • Permet de spécifier le nom de l'utilisateur Windows à utiliser pour se connecter à l'AD
  • Par défaut, ADSIReader va utiliser le contexte dans lequel la commande a été exécutée
• /DomainPassword
  • Permet de spécifier le mot de passe du compte Windows utilisé avec le paramètre /DomainUserName
• /NoUsersDetection
  • Désactive l'import des utilisateurs
• /NoComputersDetection
  • Désactive l'import des ordinateurs
• ​/NoGroupsDetection
  • Désactive l'import des groupes
• /NoPrintersDetection
  • Désactive l'import des imprimantes
• /Exclude:NomFichier.txt
  • Permet de spécifier un fichier contenant une liste de OU ou de CN à exclure de l'import
  • Le fichier devra contenir chaque OU ou CN à ignorer, un par ligne, présenté selon le format des noms distingués (DN)
  • Si le nom du OU ou CN contiens des espaces, il n'est pas nécessaire de l'inscrire entre guillemets.
  • Le contenu des OU ou CN spécifiés ainsi que tous leurs objets enfants seront exclus
• /ValuesExclusionsFilePath:NomFichier.txt
  • Permet de spécifier un fichier contenant une liste d'enregistrements à exclure de la synchronisation, à partir de critères basés sur les noms des variables de l’AD.
  • Il est possible d'exclure des éléments parmi les ordinateurs (computer), les utilisateurs (user), les imprimantes (printer) ou les groupes (group).
  • La compréhension de cette option est importante avant de l'utiliser, voir la section Exclusion d'enregistrements spécifique de l'AD.
• /ActiveUsersOnly
  • Ajouter ce paramètre pour importer seulement les utilisateurs actifs dans Active Directory
• /DeactivateUsers
  • Désactive les utilisateurs Octopus en fonction du statut du compte Active Directory
  • Un compte absent, désactivé ou supprimé de l'AD va désactiver le compte Octopus
  • Si on utilise un OU où les comptes en jachère sont placés, il faut utiliser le paramètre /Exclude pour automatiquement désactiver son contenu
     

• /SiteAutoCreation:False
  • Pour désactiver la création automatique de Sites
     
• /DepartmentAutoCreation:False
  • Pour désactiver la création automatique de Départements

• /ReactivateUsers
  • Réactive les utilisateurs Octopus en fonction du statut du compte Active Directory
  • Le compte sera reconnu comme il est spécifié dans la section Description de la mécanique de synchronisation.
  • Si on utilise un OU exclus avec le paramètre /Exclude, les comptes contenus ne seront pas réactivés
  • Il n'est pas requis d'utiliser la fonction /DeactivateUsers pour que celle-ci fonctionne
• /IncludeDomainNameInWindowsUserName
  • Importe les noms d'utilisateurs au format domaine\nom d'utilisateur
  • Alternativement, modifier le fichier de correspondance pour utiliser l'attribut User Principal Name de Active Directory, au format username@domaine.name
• /AllowMultipleLogon
  • Ajouter ce paramètre lorsque certains utilisateurs ont plus d'un compte dans le champ Nom d'utilisateur Windows
  • ​Si le Nom d'utilisateur Windows contient déjà celui de l'AD, toutes les valeurs du champ seront conservées

  • ​Si le Nom d'utilisateur Windows ne contient pas celui de l'AD, la valeur de l'AD sera la seule conservée

•  /MatchADKeyOnNullExternalIDOnly
  • Cette option est désactivée par défaut. (Sans l'option, ou avec la valeur False)

  • ​Cette option change la façon dont Octopus identifie un utilisateur à partir de sa clé ActiveDirectory

  • Dans certains cas extrêmement rares, notamment lors de la présence d’homonyme, il se peut que la méthode d’authentification ActiveDirectoryKey (DistinguishedName) prenne un utilisateur pour une autre.

  • Par défaut si le champ ActiveDirectoryKey correspond à un ActiveDirectoryKey d’un utilisateur déjà présent dans Octopus alors l’utilisateur est mis à jour.
  • Avec l’option activée (True) si le champ ActiveDirectoryKey correspond à un ActiveDirectoryKey d’un utilisateur déjà présent dans Octopus, il faut aussi que la valeur du champ ExternalID soit vide/nul pour que l’utilisateur soit mis à jour. Dans le cas où ExternalID n’est pas nul, un nouvel utilisateur est créé.
• /ImportManager
  • Ajouter ce paramètre pour importer le supérieur immédiat
  • L'attribut Manager d'Active Directory sera importé dans Octopus, dans le champ Supérieur immédiat
  • Lors du premier import, le supérieur immédiat ne sera pas importé dans ce champ, car il doit préalablement être importé comme utilisateur
• /NoStatusUpdate
  • Ajouter ce paramètre pour éviter que le système change l'état des CI retirés
• /LogFilePath:NomFichier.log
  • Remplace l'emplacement du fichier de journalisation
  • Par défaut, le fichier se nomme ADSIReader_AAAAMMJJ_HHMMSS.log et sera situé dans le répertoire où se trouve l'exécutable de l'application ADSIReader
  • Si on déplace le fichier dans un autre répertoire que celui d'Octopus, il faut que ce répertoire existe (le système ne peut créer le répertoire)
  • Ex.:/LogFilePath:C:\LogFiles\JournalADSI.log.
• /MappingsFilePath:NomFicher.xml
  • Remplace l'emplacement du fichier de correspondance des champs
  • Par défaut, le fichier se nomme ADSIReaderLDAPMappings.xml et se trouve dans le répertoire où se trouve l'exécutable de l'application ADSIReader

• /NoDbUpdate
  • Le programme sera exécuté, mais sans mettre à jour la base de données d'Octopus
  • Les informations récoltées se retrouveront dans les fichiers suivants : ADSIUsers.xml, ADSIComputers.xml, ADSIGroups.xml et ADSIPrinters.xml
  • On peut par la suite importer ce fichier en utilisant le paramètre /NoExtraction
• /NoExtraction
  • Les données ne seront pas extraites du domaine, mais importées à partir des fichiers XML
  • Utiliser les paramètres  /NoUsersDetection, /NoComputersDetection, /NoGroupsDetection et /NoPrintersDetection pour contrôler quels fichiers seront importés
• /PurgeLogs
  • Permet d'effacer automatiquement les vieux fichiers de logs. 
  • Le paramètre permet de déterminer le nombre de jours de fichiers logs qu'on désire conserver.
  • Pour plus d'information, voir l'article Outils Octopus | Entretien des fichiers logs.

Automatisation de l'importation de données provenant de Active Directory vers Octopus

Pour automatiser l'importation à partir de ADSIReader, voir l'article Tâches planifiées Windows.

Mise en place

Attribution automatique d'un site aux utilisateurs/ordinateurs contenus dans une unité organisationnelle (OU)

Pour attribuer automatiquement un site aux utilisateurs et aux ordinateurs contenus dans un OU rvoir l'article ADSIReader - Attribution automatique d'un site
 

Intégration avec une seule unité organisationnelle (OU)

Pour importer uniquement une seule unité organisationnelle, voir l'article ADSIReader - Intégration avec une seule unité organisationnelle (OU)

Supporter pour les équipes autres que TI pouvant gérer des CI

L'application ADSIReader est supportée dans les autres équipes que TI (équipe #1).

Toutefois, un administrateur Octopus doit exécuter des commandes pour configurer les données nécessaires à leur exécution.

Pour ce faire il faut :

• Sélectionner le menu Outils -> Gestion des données de référence... -> Général -> Équipes
• Sélectionner l'équipe 
• Appuyer sur le bouton Exécuter de la section Types de CI

Spécifications de l'importation

Description de la mécanique de synchronisation

Lorsqu'Octopus réalise l'import des utilisateurs, celui-ci va tenter de synchroniser les utilisateurs d'Active Directory aux comptes d'utilisateurs selon la logique suivante :

1. Identifiant Externe
   • Octopus tente d'abord le rapprochement en référant à l'identifiant unique du compte (ObjectGUID)
   • Si l'identifiant externe est reconnu, le compte Octopus va se faire mettre à jour : nom, prénom, nom d'utilisateur, courriel, etc.
   • L'identifiant unique AD d'un utilisateur Octopus est enregistré dans la colonne Identifiant Externe

2. ActiveDirectoryKey

   • ​​Si aucun identifiant externe correspondant n’a été trouvé, Octopus va se référer à ActiveDirectoryKey. (DistinguishedName)

   • ActiveDirectoryKey ou Distinguished Name est un moyen d'identifier de façon unique un objet dans la l’active directory. Donc notre cas il contient le nom relatif des différents éléments et entrées parents constituant ainsi un chemin d’accès vers l’objet 'utilisateur' dans l’Active directory.

   • Si un rapprochement est effectué, le compte Octopus va se faire mettre à jour.

   • ActiveDirectoryKey est normalement unique. Dans de rares cas, notamment en présence d’homonyme, cette méthode nécessite d’être ajusté, cela est possible en se référant à l’option ‘MatchADKeyOnNullExternalIDOnly’

3. Nom d'utilisateur
   • Méthode utilisée si le rapprochement par identifiant externe n'a pas fonctionné
   • Octopus va tenter de trouver une correspondance au niveau du nom d'utilisateur pour tous les comptes Octopus n'ayant pas d'identifiant externe
   • Si un rapprochement est effectué, l'identifiant externe du compte Octopus sera renseigné
4. Nom & Prénom
   • Méthode utilisée si les deux rapprochements précédents n'ont pas fonctionné
   • Octopus va tenter de trouver une correspondance entre les prénoms et noms des deux comptes, en ignorant ceux contenant déjà un identifiant externe
   • Si un rapprochement est effectué, l'identifiant externe du compte Octopus sera renseigné
   • La mécanique de rapprochement tient compte des accents, mais  ne fait pas de différence entre les majuscules et les minuscules
5. Création d'un nouveau compte
   • Aucun rapprochement n'a pu être effectué
   • Octopus va procéder à la création d'un nouvel utilisateur Octopus

Si on désire synchroniser un compte utilisateur ou un objet à nouveau, mais qu'Octopus présente déjà un Identifiant Externe, utiliser l'action Option > Vider l'identifiant Active Directory qui va retirer à la fois la clé Active Directory (DN de l'objet AD) et son identifiant externe (ObjectGUID)

Définition des informations à importer

La correspondance des champs AD-Octopus est contenue dans le fichier XML ADSIReaderLDAPMappings.xml situé dans le répertoire du client Octopus.

Voici le contenu du fichier par défaut :

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <mapping Name="User">
    <attribute LDAPAttribute="objectGUID" OctopusAttribute="ExternalID"/>
    <attribute LDAPAttribute="sAMAccountName" OctopusAttribute="Name" />
    <attribute LDAPAttribute="GivenName" OctopusAttribute="FirstName"/>
    <attribute LDAPAttribute="sn" OctopusAttribute="LastName"/>
    <attribute LDAPAttribute="Mail" OctopusAttribute="EMailAddress"/>
    <attribute LDAPAttribute="Title" OctopusAttribute="Title" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumber" Index="0" Separator="x" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumberExtension" Index="1" Separator="x" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="Mobile" OctopusAttribute="TelephoneMobile" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="homePhone" OctopusAttribute="HomePhone" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="distinguishedName" OctopusAttribute="ActiveDirectoryKey"/>
    <attribute LDAPAttribute="Department" OctopusAttribute="Department" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="EmployeeNumber" OctopusAttribute="EmployeeNumber" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="Pager" OctopusAttribute="Pager" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="physicalDeliveryOfficeName" OctopusAttribute="Local" EmptyValueHandling="NoChange"/>
    <attribute LDAPAttribute="preferredLanguage" OctopusAttribute="Language" />
  </mapping>
  <mapping Name="Computer">
    <attribute LDAPAttribute="objectGUID" OctopusAttribute="ExternalID"/>
    <attribute LDAPAttribute="distinguishedName" OctopusAttribute="ActiveDirectoryKey"/>
    <attribute LDAPAttribute="Name" OctopusAttribute="Name"/>
  </mapping>
  <mapping Name="Printer">
    <attribute LDAPAttribute="objectGUID" OctopusAttribute="ExternalID"/>
    <attribute LDAPAttribute="distinguishedName" OctopusAttribute="ActiveDirectoryKey"/>
    <attribute LDAPAttribute="Name" OctopusAttribute="Name"/>
  </mapping>
  <mapping Name="Group">
    <attribute LDAPAttribute="objectGUID" OctopusAttribute="ExternalID"/>
    <attribute LDAPAttribute="distinguishedName" OctopusAttribute="ActiveDirectoryKey"/>
    <attribute LDAPAttribute="Name" OctopusAttribute="Name"/>
  </mapping>
</mappings>

Il n'est pas requis de modifier ce fichier pour que le programme de synchronisation fonctionne. Les champs utilisés par défaut sont déjà liés.

Modification du fichier de correspondance des champs

• Si un champ contient des données dans Active Directory et qu'il y a une correspondance avec ce champ dans Octopus, les données d'AD auront priorité sur les données d'Octopus. Cependant, si le champ dans AD est vide, mais que celui dans Octopus contient des données, elles ne seront pas effacées.
• Si on décide d'importer les sites, les départements ou les sous-départements, ils seront ajoutés dans Octopus, s'ils n'existent pas déjà.
• Les possibilités de configuration d'Active Directory étant infinies (niveau fonctionnel, utilisation des champs, champs ajoutés dans le schéma), Octopus ne peut s’engager à offrir une liste des champs disponibles. Valider à l'interne, auprès d'un des administrateurs du domaine qui saura fournir une liste des attributs LDAP disponibles.

Voici quelques cas qui peuvent nécessiter de modifier le fichier de correspondance :

<attribute LDAPAttribute="userPrincipalName" OctopusAttribute="UPN"/>

<attribute LDAPAttribute="Company" OctopusAttribute="Site"/>

<attribute LDAPAttribute="Title" OctopusAttribute="Title"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumber" Index="0" Separator="x"/> <attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumberExtension" Index="1" Separator="x"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumber" Index="0" Separator="x"/> 
<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumberExtension" Index="1" Separator="x"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumberExtension"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumber" Index="0" Separator="x" StripLeading="1-"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumber" Index="0" Separator=";" EmptyValueHandling="NoChange"/>

<attribute LDAPAttribute="TelephoneNumber" OctopusAttribute="TelephoneNumberExtension" Index="1" Separator="=" EmptyValueHandling="NoChange"/>

<attribute LDAPAttribute="NomDuChampAD" OctopusAttribute="SubDepartment"/>

<attribute LDAPAttribute="Department" OctopusAttribute="Department" Index="0" Separator="-"/> 
<attribute LDAPAttribute="Department" OctopusAttribute="SubDepartment" Index="1" Separator="-"/>

<attribute LDAPAttribute="ExtensionAttribute4" OctopusAttribute="CustomAttribute.cfCorpsDeMetierOuDEmploi"/>

<attribute LDAPAttribute="description" OctopusAttribute="Local"/>

<attribute LDAPAttribute="description" OctopusAttribute="InventoryNumber"/>

<attribute LDAPAttribute="description" OctopusAttribute="CustomAttribute.Description"/>

<attribute LDAPAttribute="EmployeeNumber" OctopusAttribute="EmployeeNumber" EmptyValueHandling="Clear"/>

Exclusion d'enregistrements spécifique de l'AD

Le paramètre /ValuesExclusionsFilePath permet d'exclure certains enregistrements de la synchronisation avec AD.

Les types d'éléments qu'on peut exclure sont : 

• Les utilisateurs
• Les groupes 
• Les ordinateurs
• Les imprimantes

À partir d'un fichier en format UTF-8, on ajoute la liste d'enregistrements à exclure de la synchronisation, à partir de critères basés sur les noms des variables de l’AD.

Les règles pour utiliser ce paramètre sont les suivantes : 

• Le fichier doit être en format UTF-8.

• Si une exclusion de OU est appliquée à l'aide du paramètre /Exclude, alors cette exclusion a préséance sur le paramètre actuel.
• On peut ajouter plus d'un critère à la fois, en utilisant le point-virgule pour les séparer. 
• Noter qu'un critère ne pourra pas contenir de point-virgule parce qu'il est utilisé comme séparateur.
• Les critères contenant des guillemets seront ignorés.
• Il est possible de gérer les valeurs vides en ajoutant deux points-virgules à la fin d'une liste. 
• Si un critère n'est pas valide, la ligne au complet sera ignorée.
• Si plusieurs lignes de critères sont ajoutées, elles sont traitées individuellement (dès qu'une des lignes est vraie, l'enregistrement est exclu)

Voici un exemple de fichier : 

<ExcludedLists>
                <Computer>
                               <cn>OCTOAD-DC;OCTOAD-WS1</cn>
                </Computer>
                <User>
                               <GivenName>Mr;Ms</GivenName>
                               <sn>Loranger;Operation</sn>
                               <extensionAttribute1>Étudiant;;</extensionAttribute1>
                </User>
                <Printer>
                               <priority>1</priority>
                </Printer>
                <Group>
                               <sAMAccountName>CTS Web Access Computers</sAMAccountName>
                </Group>
</ExcludedLists>

Dépannage ADSIReader

Pour plus de détails sur les problèmes de synchronisation, cliquez ici

Journal des opérations

Fichiers générés à l'exécution du programme ADSIReader :

• ADSIReader_AAAAMMJJ_HHMMSS.log 
  • Journal des opérations (LOG) généré automatiquement chaque fois que le programme est exécuté
• ADSIUsers.xml
  • Fichier contenant l'information sur les utilisateurs qui seront importés dans Octopus, une fois la tâche terminée
• ADSIComputers.xml 
  •  Fichier contenant l'information sur les ordinateurs qui seront importés dans Octopus, une fois la tâche terminée
• ADSIPrinters.xml
  • Fichier contenant l'information sur les queues d'impression qui seront importées dans Octopus, une fois la tâche terminée
• ADSIGroups.xml
  • Fichier contenant l'information sur les groupes utilisateurs qui seront importés dans Octopus, une fois la tâche terminée

Ces fichiers seront créés dans le même répertoire que l'exécutable "ESI.Octopus.ADSIReaderApp.exe". De plus, ces fichiers peuvent être demandés lors de l'analyse d'un problème avec l'utilisation du programme ADSIReader