Introduction

This article describes the steps to follow to analyze errors related to running ADSIReader as well as the most common problems using this tool.

The use of ADSIReader requires your Octopus administrators to have the expertise of active Directory.
It is run locally on a computer in your network.

For more information on how it works:

https://wiki.octopus-itsm.com/en/articles/adsireader-integration-active-directory

Files generated when running the ADSIReader program

Operations log :

• ADSIReader_AAAAMMJJ_HHMMSS.log 

Operations log (.LOG) generated automatically each time the program is run. It is located by default in the Octopus installation directory that is running ADSIReader, or otherwise in the path indicated by the /LogFilePath parameter.

Data read from Active Directory :

These files will be created in the same directory as the ESI.Octopus.ADSIReaderApp.exe and overwritten at every new execution. In addition, these files can be requested when analyzing a problem with the use of the ADSIReader program.

• ADSIUsers.xml

File containing information about the users that will be imported into Octopus, once the task is completed

• ADSIComputers.xml 

File containing information about the computers that will be imported into Octopus, once the task is completed

• ADSIPrinters.xml

ile containing information about the print queues that will be imported into Octopus, once the task is completed

• ADSIGroups.xml

File containing information about the user groups that will be imported into Octopus, once the task is completed

ADSIReader Troubleshooting

When a problem occurs while running the ADSIReader tool, the suggested analysis steps are :

• Make sure that the tool runs by checking on the machine that runs it:

1. if the Windows scheduled task that launches it is completed without error. You must correct errors if necessary.
2. check if the .LOG is generated, which indicates its execution
3. test the integrity of the Octopus client installation by launching the ESI.Octopus.WinUI.exe. If the Octopus client starts, it means that the installation is good, otherwise you must reinstall the Octopus client. It is recommended to keep the directory of the old installation, in order to preserve certain configuration files, such as LDAPMappings.XML, which may have been modified by yourself.

Q&A on most common issues

• In my .LOG I see users with a LogonMustBeUnique error message

1. The Windows Username field in the user record does not allow duplicates, so check if another user has the same value in this field and make corrections to avoid the error the next time you run ADSIReader.

2. It is possible that the external identifier has been changed in AD in case the user has been recreated with the same Windows username, for example. To confirm this scenario, compare the user's ExternalID value in the ADSIUsers.XML file with the External identifier column in a list of users in Octopus. In case of a different value:

   Select the user in Octopus, Tools menu > Clear the Active Directory identifier. This action will allow the update of this value from Active Directory the next time ADSIReader is run.

• There is no error in the .LOG but the user is not found in Octopus?

It is likely that the user is inactive, since the quick search finds active users by default.
You have to do a quick search using the Include inactives checkbox or otherwise look for it on the list Inactive users in the Users module.
The reason why the user was disabled should be analyzed, as this can have different causes, including the /DeactivateUsers parameter in the ADSIReader command line.

• ADSI created a duplicate of a user. Why ?

When synchronizing between AD and Octopus, a unique identifier from Active Directory is also imported into Octopus. It is visible in a list of users under the External ID column.
If the user has been recreated in AD, there will be a new external identifier assigned.

So how do I link the new AD entry to the existing user record in Octopus?

1. Select the user in question in Octopus
2. Select from the menu Tools > Clear Active Directory ID.

Once the external identifier is deleted, the next time ADSIReader is run, the assignment of the new identifier will be made and the link of the AD user with the one in Octopus will be established, according to the synchronization mechanism. For more details, click here

Attention: the action of emptying the external identifier is irreversible. Only ADSIReader is able to populate this information again.

• A user is disabled in AD but still active in Octopus

Check whether or not your ADSIReader command line contains the /DeactivateUsers parameter

• Some fields are not synchronized

The LDAPMappings.XML field mapping file contains the mapping of those fields. It is important to check if the unsynchronized field is in this file.

• Groups are not synchronized

To synchronize a group, you must first specify the AD path of the group in the group configuration in Master Data Management. The ADSIReader command line should not have the /NoGroupsDetection parameter.

The file ADSIReaderLDAPMappings.xml file must contain the following section (present by default):

  <mapping Name="Group">
    <attribute LDAPAttribute="objectGUID" OctopusAttribute="ExternalID"/>
    <attribute LDAPAttribute="distinguishedName" OctopusAttribute="ActiveDirectoryKey"/>
    <attribute LDAPAttribute="Name" OctopusAttribute="Name"/>
  </mapping>

• One or a few members of a group are not synchronized

It is necessary to check if the user is active or if he has a duplicate among the inactive users.

The groups sync requires the users to be synced, so the parameter /NoUsersDetection should not be used in this case.