Overview

The ADSIReader program (ESI.Octopus.ADSIReaderApp.exe) allows importing users, computers (workstations and servers) and printer queues stored in your Active Directory.

The user import can include, among others; first name, last name, Windows username, title, department, phone numbers (with the phone extension), while import of computers includes only the computer name. 

It is possible to use the WMIUpdater program (ESI.Octopus.WMIUpdaterApp.exe) to obtain the technical configuration of computers (operating system, memory, processor type, installed software, etc.).

Regarding print queues, we suggest excluding them with the /NoPrintersDetection parameter during import for two reasons:

The imported name is not always significant

There can be more than one queue per printer

Instead, it is recommended to do a single import with the DataImporter program and then manage the printers directly in Octopus.
 

How ADSIReader Works

When ADSIReader is executed, based on parameters used, it will import from your Active Directory all users, computers and print queues. Parameters are very important to control what is imported. Also, a mapping file defining the relation between Octopus and Active Directory properties is available in your installation folder (see file ADSIReaderLDAPMappings.xml).

Prerequisites

• Creation of an Octopus System account to run the above mentioned task. See the Octopus System Account article.
• A good understanding of the impact of ADSIReader on computer asset management in Octopus. Please refer to the ADSIReader - Impacts on computer asset management article.
• Name of domain(s) needing to be explored and which OU(s) need to be excluded (if applicable).

ADSIReader program usage

ADSIReader is a command line (DOS) type program. It has been designed to be easily automated (the Import Automation section will describe how to automate recurring imports).

• The complete program name is: ESI.Octopus.ADSIReaderApp.exe
• It is located in the local Octopus directory, either (C:\Program Files\Octopus) or (\%homepath%\AppData\Local\Octopus)
• Examples of directory where Octopus can be located:
  • For Windows 7 and more: C:\Users\slevesque\AppData\Local\Octopus
  • For Windows XP : C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

ADSI import from a command line

The AD import from a command line allows to use different parameters that can prevent from importing non desired data in Octopus. 

To run the ADSIReader executable, you need to open a DOS window and go to the Octopus folder. Then, you need to enter the following command line: 

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

Example of a DOS command line

Before you run the command, it is recommended to validate the required parameters.

Examples

• Import active users only and computers, but without the print queues:

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

• Import from AD without updating the database while modifying the log file name and location:

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

Parameters

There are 21 parameters available, of which 4 are mandatory to execute ADSIReader.

Mandatory Parameters

• /Login
  • Octopus username
• /Password
  • Octopus password

• /Team

  • ​The number of the team to be updated if the user is part of a multiple teams environment. By default, the IT team has team number 1.

• /Domain:DomainName
  • This parameter is the name of the domain to import.

Optional Parameters

• /DomainUserName​
  • Specifies the Windows username to use if you are importing from an untrusted domain.
  • By default, ADSIReader will use the user context from which the command was invoked.
• /DomainPassword
  • ​Specifies the password associated with the /DomainUserName parameter.
• /NoUsersDetection
  • Deactivates user importation.
• /NoComputersDetection
  • Deactivates computer importation.
• /NoGroupsDetection
  • Deactivates group importation.
• /NoPrintersDetection​
  • Deactivates printer queues detection.
• ​/Exclude:FileName.txt
  • Specifies a file containing a list of OUs to be excluded.
  • The file needs to contain each OU to exclude, one per line, using their distinguished name (DN).
  •  If the OU or CN name contains spaces, there is no need to declare it between quotation marks.
  • The content of a specified OU and its child OU will be excluded.
• /ValuesExclusionsFilePath:FileName.txt
  • Allows you to specify a file containing a list of records to exclude from the synchronization with criteria based on the variable names of AD.
  • It is possible to exclude elements among computers, users, printers or groups.
  • Understanding this option is important before using it, see Exclusion of Specific Record From AD section. 
• /ActiveUsersOnly
  • Add this parameter to restrict import to active users only from Active Directory.
• /DeactivateUsers
  • Deactivates Octopus users following Active Directory account status.
  • Missing, disabled or deleted account in AD will result in Octopus account deactivation.
  • If you use an OU dedicated to unused account, use the /Exclude parameter to automatically deactivate its content.

• /SiteAutoCreation:False
  • To disable automatic site creation
• /DepartmentAutoCreation:False
  • To disable automatic Department creation
     

• /ReactivateUsers
  • ​Reactivate Octopus users based on Active Directory status.
  • The Active Directory account will be recognized as specifiable in the Import Mechanics section. 
  • You do not need to use the /DeactivateUsers feature to use this one.
  • If you use an excluded OU using the /Exclude switch, accounts contained therein will not be reactivated.
• /IncludeDomainNameInWindowsUserName
  • Import users using the domain\username format
  • Alternatively, modify the mapping file to use the User Principal Name attribute, with the format username@domain.name.
• /AllowMultipleLogon
  • Add this setting when some users have more than one account in the Windows Username field
  • If the Windows Username already contains the one from AD, all values in the field will be retained
  • If the Windows Username does not contain the one from AD, the value from AD will be the only one kept
• /MatchADKeyOnNullExternalIDOnly
  • This option is turned off by default.
  • This option changes the way Octopus identifies a user with the ActiveDirectoryKey
  • In some rare scenario where a conflict is found with ActiveDirectoryKey a conflict will be found and Octopus will counfound one user for another.
  • If the ActiveDirectoryKey corresponds to another ActiveDirectoryKey of an existing user, the Octopus user will be updated.
  • With the option set to True if the ActiveDirectoryKey equals to another ActiveDirectoryKey of another user already existing in Octopus, the value of the ExternalID must be empty/null for the user to be updated. In the case where ExternalID is not empty/null, a new user is created.
• /ImportManager
  • Add this parameter if you want to import the hierarchical manager.
  • The Manager attribute from Active Directory will be imported to the Supervisor field of the user file.
  • During the first import, the supervisor field will not be imported since the supervisor first needs to be imported as a user
• /NoStatusUpdate
  • Add this parameter is you do not want to change CI status to Retired
• /LogFilePath:FileName.log 
  • Replaces the location and name of the operation log file.
  • By default, the file will be named ADSIReader_YYYYMMDD_HHMMSS.log and will be located in the same directory as the ADSIReader executable program.
  • If you relocate the file to a different folder, make sure the folder already exists (Octopus will not create the folder).
  • Example: /LogFilePath:C:\LogFiles\ADSIReader.log
• ​/MappingsFilePath:FileName.xml
  • Specify the location of the field mapping file.
  • By default, the program will use the ADSIReaderLDAPMappings.xml file contained in the application folder.

• /NoDBUpdate
  • The program will run without updating the Octopus database.
  • Extracted information will be stored in the following files: ADSIUsers.xml, ADSIComputers.xml, ADSIGroups.xml and ADSIPrinters.xml.
  • You can later import those files using the /NoExtraction parameter
• /NoExtraction
  • The program will run without extracting data from the network, but using the XML files.
  • Use the /NoUsersDetection, /NoComputersDetection, /NoGroupsDetection and /NoPrintersDetection to control which files are not imported.
• /PurgeLogs
  • Can automatically erase old log files
  • The parameter is used to determine how many days of log files that you want to keep.
  • For more information, see the Octopus Tools | Maintenance of log files.

Automate data import from Active Directory to Octopus

To automate the import from ADSIReader, refer to the Windows Scheduled Tasks article.

Implementation

Automatic attribution of a site to users/computers part of an Organizational Unit (OU)

To automatically attribute a user or computers to the right site based on OU location, refer to the ADSIReader - Automatic site assignation article.

Integration with a single organizational unit (OU)

To import only a specific organizational unit, refer to the ADSIReader - Integration for a single organizational unit (OU) article.

Support for non-IT teams managing CIs

The ADSIReader application is supported in teams other than TI (Team #1).

However, an Octopus administrator mus execute commands to configure the data required for their execution.

To do this, you need to:

• Select menu Tools -> Reference data management... -> General 
• Select Team
• Press the Execute button in the CI Types section

Import specifications

Import mechanics

When Octopus performs importation of users, it will attempt to synchronize AD users relative to the Octopus users the following way:

1. External Identifier
   • Octopus first tries to match using a unique identifier (ObjectGUID).
   • If the external identifier is recognized, the Octopus account will be updated: lastname, firstname, username, email, etc.
   • The AD unique identifier is stored in the External Identifier column.
2. ActiveDirectoryKey
   • If no external identifiers has been found, Octopus will refer to ActiveDirectoryKey (DistinguishedName)
   • ActiveDirectoryKey or DistinguishedName is a way to uniquely identify an object in Active Directory. In our case it contains the relative name of different attributes and parent name (relative path) to the user object in Active Directory.
   • If the object is matched/found, the Octopus account will be updated.
   • ActiveDirectoryKey is normally unique. In the rare case that a conflict is present, this method must be adjusted. This will be accomplished with the option MatchADKeyOnNullExternalIDOnly.
3. Username
   • Used if the recognition based on External Identifier has not produced a match.
   • Attempts to match the account based on the Windows Username for all Octopus account that do not have an External Identifier.
   • If a match is made, the External Identifier will be recorded.
4. Lastname & Firstname​
   • Used if both previous methods have not produced a match.
   • Attempts to find a match between both lastname and firstname for all Octopus account that do not have an External Identifier.
   • If a match is made, the External Identifier will be recorded.
   • Recognition is accent sensitive and case insensitive.
5. Creation of a new account
   • No match could be made.
   • Octopus will create a new account.

If you want to force synchronization of an object that already has an External Identifier, use the action found in Tools > Clear Active Directory identifier which  removes both the Active Directory Key (Distinguished name) and External Identifier (ObjectGUID).

Imported Information

The mapping between AD and Octopus fields is stored in the XML file "ADSIReaderLDAPMappings.xml" located in Octopus client directory.

Here is the content of the default file:

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

You are not required to modify this file for the import to work. The default fields to import are already defined.

Mapping file modification

• If a field containing data in Active Directory has an equivalent field in Octopus, the AD data will have priority on the one in Octopus. However, if the field is empty in AD but contains data in Octopus, it will not be overwritten.
• If you decide to import sites, departments or sub departments, they will be added in Octopus if they do not already exist.
• The possibilities of Active Directory configurations being infinite (functional level, field usage, fields added to the schema), Octopus cannot provide a list of available fields. However, you can contact an administrator for your domain who will provide you with a list of available LDAP attributes.

Here are some cases where it could be necessary to modify the mapping file:

<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="NameOfFieldAD" 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.DescriptionInAttribute"/>

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

Exclusion of Specific Record From AD

The /ValuesExclusionsFilePath parameter allows to exclude certain records from the AD synchronization.

The types of elements that can be excluded are: 

• The users
• The groups 
• The computers
• The printers

From a  UTF-8 format file, you add the list of records to exclude form the synchronization, using criterion based on the AD variable names.

The rules for using this parameter are:

• The file must be in UTF-8 format. 

• If an OU exclusion is applied in the parameters, then this exclusion takes precedence over the current parameter.
• More than one criteria can be added at a time, using the semicolon to separate them.
• Note that a criterion cannot contain a semicolon because it is used as a separator.
• Criteria containing quotation marks will be ignored.
• Empty values can be handled by adding two semicolons at the end of a list.
• If a criterion is invalid, the entire line will be ignored.
• If several lines of criteria are added, they are processed individually (as soon as one of the lines is true, the record is excluded).

Here is an example of a file:

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

ADSIReader Troubleshooting

For more information about synchronisation problems, click here

Operation Log Files

The following files are generated when executing ADSIReader:

• ADSIReader_AAAAMMJJ_HHMMSS.log 
  • This log file is generated automatically each time ADSI is run
•  ADSIUsers.xml (version 3.8 or higher)  - ADSIEmployees.xml (version 3.7 and lower)
  • File containing user information to be imported in Octopus, once completed
• ADSIComputers.xml:
  • File containing computer information to be imported in Octopus, once completed
• ADSIPrinters.xml:
  • File containing print queue information to be imported in Octopus, once completed
• ADSIGroups.xml:
  • File containing user group information to be imported in Octopus, once completed.

These file are created in the directory where the ESI.Octopus.ADSIReaderApp.exe is located. Note that these files could be required to troubleshoot issues with ADSIReader.