Get Started with ADSync Utility

This article contains the following topics:

This article explains how ADSync Utility works and guides you in performing the initial setup of the utility. After you have performed the initial setup, see Configure the ADSync Utility to learn how to configure the utility.

Initial Setup

This section explains the tasks that you must perform while getting started with ADSync utility.

Verify System Requirements

Ensure that your system meets the following requirements before running the ADSync utility:

• LDAP v2 and v3 Supported Servers: Microsoft Active Directory (AD)
• Directory OS: Windows, UNIX
• Latest version of Java (version 8 or later)
• Memory: 2 GB minimum
• Compatibility with HTTPS secure communications protocol
• Compatibility with ServiceAide Cloud Service Management (CSM)

Note: Each tenant must have its own instance of the ADSync utility.

Acquire and Unzip the Utility

The ADSync utility is delivered as a ZIP file. This file contains the utility and all of the supporting files necessary for the process.

You can acquire the utility through the following means:

• Download it from CSM. Navigate to MANAGE> ADMINISTRATION> Tools> Downloads.
• Obtain it from an administrator who has the appropriate permissions for accessing the utility.

Considerations for unzipping the utility are as follows:

• The file can be unzipped to any environment with JRE configured.
• All JARs and files must remain together, exactly as they were unzipped. Do not move anything from the unzipped layout.
• The installation location must be able to connect to your LDAP server and CSM.

Once you have unzipped the utility, you are ready to configure the utility.

Deploy

The ADSync Utility is deployed as a stand-alone application on the client side. You need the Java Runtime Environment to run this application. Set up the ADSync Utility on a VMWare Server that can talk or connect to the specific directory.

Set up a service account that has permissions to connect to the directory server and run queries.

Schedule

You can schedule the synchronization process to run as required. Ideally, run the synchronization process once every day. Schedule the process during your off-business hours.

The scheduler runs as a Windows/Linux background job. For more information, see the topic Create a Job Scheduler in Configure the ADSync Utility.

Design

When you run the ADSync Utility, it compares the data between CSM and your LDAP. Next, the differences between the LDAP server and CSM data are synchronized as follows:

Restrictions

• All user IDs are case-sensitive. When you run the synchronization successfully, the utility creates a backup file for all your data. When you run the synchronization the next time, only the differences are updated on CSM. If the case of a user id in the backup file is not identical to the one in LDAP, the one in the backup file is deleted. If you want to modify an ID after the backup is generated, delete the backup and modify the ID manually.
• In the absence of backup files, ADSync Utility cannot remove any users.
• If you want to run a full sync, remove all backup files.

• Create the organization structures of the records in CSM before you start using the ADSync Utility. In the absence of the organization structure, users are not mapped to their respective organizations.

• Use only one instance of ADSync Utility for each directory server.
  If you change the search filter, the corresponding backup files are rendered useless. The new search filter results in new backup file (or backup files, depending on the number of search bases).

How the ADSync Utility Works

This topic describes how the synchronization works.

On Directory Server (Client Side)

• The ADSync Utility uses a service account to connect to the global catalog server and domain controllers.
• A Search Base list is used to look for users from the list of Organization Units (OUs).
• The application cycles through each OU and looks for users in accordance with the search criteria. This criteria is as defined follows:
  (&(objectClass=user)(objectClass=person)(objectClass=organizationalPerson))
• The fields in the Directory Server are mapped with the fields in CSM using the attribute_map.list file.
• For each matching entry, the application looks for certain attributes. Examples of such attributes are first-name, last-name, and email. The complete list of attributes can be found in the attribute_map.list file. The application also looks for disabled and expired accounts and tags them as inactive users in the data feed. The attribute userAccountControl and loginDisabled are used for for checking disabled accounts. The attribute  accountExpires is used for checking expired accounts.
• The application writes the matching entries to a CSV file in ADSync Utility after cycling through all the OUs. The application also constructs an XML document with the data and streams it to CSM.
• The server response contains the errors and warnings that are encountered while processing the data. The response is generated in XML format and written in the INFO tag of the log file. The log file is at <:Install_Directory>/sync/logs/sync_data.log.0. For more information about this file, see logger.properties File. You can set up file monitors on this log file. As part of your monitoring service, look for errors and warnings. The strings to search for, from a monitoring perspective, would be:
  • "notes" - The notes tag contains the summary of the overall response that is received from the server.
  • "SEVERE"
  • "<errors>" or "<error>" - The “errors” tag lists all the errors and the "error" tag contains each individual error.
  • "<warnings>" or "<warning>" - The “warnings” tag lists all the warnings and the "warning" tag contains each individual warning.
  • "response" - The "response" tag contains the XML response from the server. The data from LDAP is written to CSM in batches of 500 records. The server generates a response XML for each batch after it is processed.

On CSM (Server Side)

• The data from the LDAP is written to the ADSync Utility first. Then it is validated before being transferred to the CSM database.
• You can configure a threshold value for deletion of user records from the CSM database. No records are deleted if the number of records that are marked for deletion is above this value. The synchronization of the remaining data is not affected. The information about a threshold breach is recorded in the sync_data.log.0 file.
• On receipt of the data from the LDAP, CSM starts immediate processing of the data.
• Based on the user ID in the incoming feed, the corresponding contact record is identified in CSM. 
• The incoming entry is compared with the data existing in CSM. An automatic update statement is created based on the difference between the two. This condition applies to changes in attributes like phone, email, and department.
• Each new record is created as a Self-Service user. These users have their primary group and license set to Self-Service. The time zone for the new contact is based on the corresponding location.
• For all inactive contacts in the feed:

  • All contacts who are Self-Service users are deactivated and the Login Enabled flag is set to false. This change effectively stops the user from logging in to CSM.

  • All contacts who are technicians are deactivated and the Login Enabled flag is set to false. This change effectively stops the user from logging in to CSM.

  • All contacts who are part of the Administration group are deactivated and the Login Enabled flag is set to false. This change effectively stops the user from logging in to CSM.

  • All disabled users who exist in the Directory Server, but not in CSM, remain in the data feed. However new records are not created for such users.

  • All deleted users in the Directory Server would not be part of the data feed. The process sets all those CSM accounts that are not part of the feed as inactive. Such user names are released for reuse in future accounts.

• The exceptions that are encountered during the synchronization are written to syn_data.log file. The log includes information about:

  • Errors that are encountered while processing data.
  • Contacts without locations.
  • Contacts that were made inactive.
  • Administrative accounts that were inactive in the incoming feed but not made inactive in CSM.

Note: If the contact timezone is not specified while creating or updating the record, then the default slice timezone is used. This value is set in the Configuration Parameter DEFAULT_TIMEZONE

For more details about the configuration files that are mentioned in this article, see Configuring the ADSync Utility.

Backup

After the synchronization process is successful, CSM generates a response in XML format. This XML information is added to sync_data.log.0 file in the ADSync Utility. Based on the sync_data.log.0 file, ADSync Utility generates a backup file at a predetermined location. The backup data is stored at <:Install_Directory>/sync/backup. Do not modify the structure of this directory. When you run the synchronization successfully the first time, the utility creates a backup file for all your data. When you run the synchronization the next time, only the delta changes are updated on CSM. If you want to run a full synchronization, delete the existing backup files. Otherwise, do not modify the contents of this folder.

The backup file is generated only if the synchronization is successful as a whole. In some cases, the overall synchronization is successful, but an individual record fails. Update such records manually.

The backup folder consists of the following elements:

• Backup File - The utility creates an XML file for writing the backup. This file is at <:Install_Directory>/sync/backup. The name of the file starts with "bak_".
• backupIDMapper.properties  File - This file is located at <:Install_Directory>/sync/backup/idMapper. The utility writes a separate backup file for each combination of a search base entry and a search filter. The information about each combination is written to the backupIDMapper.properties file. If this file is absent from the default location, the sync process fails. In that case, no data is sent to CSM. If you delete this file, all the existing backup files are rendered useless.
• ProcessXMLDocument.dtd File - This file provides a template for processing the XML backup files. This file is at <:Install_Directory>/sync/backup/dtd.

Configure Proxy Network

You can also run the ADSync Utility on a proxy network. To configure your proxy settings:

1. Configure the sync.properties file. Follow these steps:
   1. Navigate to <:Install_Directory>/conf/sync.properties.
   2. In the sync.properties file, update the proxy host and port details. If you are using proxy authentication services, also provide details of proxy user name and password. ADSync Utility supports basic authentication.
      For more information about these attributes, see Configuring the ADSync Utility.
   3. Save and close the sync.properties file.
2. Configure your browser settings for enabling the Proxy Server. Follow these steps for Internet Explorer:
   1. Navigate to  Tools> Internet Options> Connections> LAN Settings.
   2. Enable Proxy Server.
   3. Specify the IP Address of the proxy server and the port number. The host and port details must be the same as configured in the sync.properties file.