Configure the ADSync Utility

This article contains the following topics:

This article explains how to configure the ADSync Utility.

Configurations in Serviceaide Intelligent Service Management 

Configure how the Serviceaide Intelligent Service Management server interacts with the ADSync Utility.

Configure the Tenant Information and Sync Properties

The sync.properties file contains the Intelligent Service Management information for your tenant. The ADSync utility is configured with either the tenant or the suborganization admin login credentials.

You can only synchronize users data using the utility.

For more details about the sync.properties file, see sync.properties File.

Configure How User Deletion Is Handled

To configure how Intelligent Service Management treats the deletion of user data, navigate to MANAGE> Tools> Configuration Parameters. Configure the following parameter:

• ACTIVE_DIRECTORY_USERS_DEPROVISION_USERS_THRESHOLD

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.

Configure the ADSync Utility on Client Side (LDAP)

The ADSync utility relies on a set of configuration files. These files are delivered with the ADSync Utility. The files are located in the ADSync Utility folder. The support team does not have access to these files. In this step, you configure files with the following environment information, and test the utility:

• Connection information of your LDAP server
• Connection information of Intelligent Service Management
• How the values in your LDAP server map to the fields in Intelligent Service Management configuration files

All these files are located in the ADSync Utility folder. As you configure these files, be sure to maintain their location in this folder. All the ADSync files must remain in the same relative location to which you unzip them. You can move the entire ADSync Utility folder, but all files must remain together.

Before you begin the synchronization, ensure that you have defined the organization structure in Intelligent Service Management.

ADSync Utility Configuration Files

This topic explains the configuration files that are included with the ADSync Utility.

searchBase.list

This file contains a list of all the Organization Units (OUs). The list is used to extract user data that is sent to Intelligent Service Management. Each line consists of a fully qualified OU, such as:

• OU=Users,DC=Bedford,DC=Nimsoft Service Desk,DC=InteQ,DC=com
• OU=Users,DC=Boston,DC=Nimsoft Service Desk,DC=InteQ,DC=com
• OU=Users,DC=Seattle,DC=Nimsoft Service Desk,DC=InteQ,DC=com

If the searchBase.list file is empty, the utility fetches the data from all records in the LDAP server.

attribute_map.list

This file contains a list of all the user attributes to be collected for each user account. You edit this file to apply the appropriate Active Directory (AD) attribute name to the Intelligent Service Management fields.

The values are mapped using the following equation:

Intelligent Service Management attribute=Active Directory attribute

You can do the mapping in any of the following formats:

• You can map an AD value with the respective Intelligent Service Management value. Enter only the name of your AD attribute against the Intelligent Service Management attribute.

For example: first_name=givenName

• You can pass multiple active directory values for a Intelligent Service Management attribute in the following format: ${Value1} ${Value2}.

For example: name=${last_name}, ${first_name}

The spaces between the values or any other items that are placed outside of the ${} are treated as static values and are included, as is, in the attribute definition.

• You can pass a static value (text) as the mapping for a Intelligent Service Management attribute. If the entire value on the right-hand side is static, put it in double quotes.

For example: title="this is an example of a static string"

• You can pass a combination of AD attributes and static values for a Intelligent Service Management attribute. Follow these rules strictly:

  • When you use a combination of AD attributes and static values, ensure that the AD attribute is included within ${}.

For example: job_title=Sr. ${title}

Here, the static value is “Sr.” and the AD value is title.

• • While passing a combination of AD attributes and static values, Do NOT use double quotes to represent a static value. In this case, anything that is not included within ${}, is treated as static string by default. If you use double quotes, they become a part of the static value.

For example: job_title=“Sr.” ${title}

Here, the entire text string “Sr.”, including the quotation marks, is treated as a static string.

• • While passing a combination of AD attributes and static values, DO NOT put the entire right-hand side value in double quotes. In this case, ADSync ignores the AD value and treats it as a part of the static text string.

For example:  name="this is an example of a static value which includes an AD attribute ${department}"

In this example, ${department} is not treated as a variable as it is included inside the quotes. Instead, ${department} is also treated as text.

If a user account does not have any value corresponding to the AD attribute specified by you, then only the static values are passed for that account. This rule is not applicable to the org_name attribute. For more information about org_name, see Configure the org_name Attribute.

Do verify the description of each attribute, in the list of attributes, for exceptions.

Important Considerations:

• If you change the mapping for an attribute after running the ADSync Utility, and you run the utility again, the new values overwrite the existing ones in Intelligent Service Management. Similarly, if you delete the mapped value, the same is deleted from Intelligent Service Management when you run the utility again.
• The time_zone attribute is not available any more. The current version of the application auto updates the time zone of the logged in user according to their system settings. So, the manual setting is no longer required.
• You cannot map an AD attribute to more than two attributes in Intelligent Service Management. While mapping an attribute for the second time, ensure that you enter it in ${attribute} format.
  For example: Consider that you want to map the mail attribute on the LDAP to the e_mail and user_login attributes on Intelligent Service Management.

Define the attributes as follows:
e_mail=mail
user_login=${mail}

List of Attributes For Microsoft Active Directory

List of Attributes For Novell eDirectory:

• #Nimsoft Service Desk Field = Directory Service Field Name
• first_name=givenName
• last_name=sn
• job_title=title
• e_mail=mail
• user_login=uid
• manager=manager
• org_name=${company} >> ${physicalDeliveryOfficeName} >> ${ou}
  For more information about org_name, see Configure the org_name Attribute.
• lvl1_name=company
• lvl2_name=physicalDeliveryOfficeName
• lvl3_name=ou
  Note: Always use the org_name attribute instead of lvl1_name, lvl2_name, and lvl3_name. If you are using the org_name attribute, there is no need to define lvl1_name, lvl2_name, and lvl3_name. These levels are only provided for backwards compatibility with earlier versions of the application.
• phone1=telephoneNumber
• phone2=mobile

logger.properties

This file lets you configure the logging levels and output files for the Active Directory synchronization process. The name-value pairs to be configured for logging purposes are as follows:

sync.properties

This file provides the main configuration center for the data synchronization. The name-value pairs available for configuration are as follows:

During the troubleshooting, the support team can ask you to validate the values set in the sync.properties file.

• Authorization Token = authtoken for the user integration engine in customer slice
• Slice Token = slicetoken for the slice where the sync process writes to
• Action URL = The URL to the correct instance where the customer wants to send the sync output

Configure the org_name Attribute

The org_name attribute represents your organizational hierarchy. This attribute is configured in the attribute_map.list file. The value that you specify here displays all the levels of your organizational hierarchy.

You can define an org_name using active directory (AD) attributes, static values, or a combination of both.

The following rules must be followed while configuring the org_name:

• If you use an AD attribute to represent a level, ensure that the attribute is enclosed within ${ }. For example: ${department}.
  This format is not required for static values. For example: Human Resources.
• Each level must be separated with the string "single space>>single space". For example: ${company_name} >> ${department}, or ${company_name} >> Human Resources.
  Do not use any other characters to separate the levels.
• There is no limitation on the number of levels in the org_name.
• If you use AD attributes in the org_name, ensure that every user is mapped to at least one of the AD attributes in the org_name. If a user is not mapped to any of the AD attributes in the org_name, then that user is not mapped to any organization.
• Do not add space characters or any other characters at the beginning or end of the org_name definition.
• Do not use double quotes to represent static values in the org_name hierarchy. However, you must use double quotes when your entire org_name definition is a static value.

Example:

Case 1: org_name includes only active directory attributes:

org_name=${company} >> ${physicalDeliveryOfficeName} >> ${department} >> ${additional level} >> ${additional level}

Case 2: org_name is a combination of active directory attributes and static values:

org_name=XYZ Company >> USA >> ${state} >> ${county} >> ${village} >> Human Resources

In this example:

• • XYZ Company, USA, and Human Resources are static values.
  • ${state}, ${county}, and ${village} are AD attributes.

You can add any number of levels as static values in the org_name.

Case 3: Entire org_name is a static value:

org_name="XYZ Company >> USA >> New York >> Human Resources"

Ensure that, in this case, the value on the right side is included in double quotes.

Enable an ISM SSL Environment for the ADSync Utility

To enable an SSL environment for the ADSync Utility, perform the following steps:

1. Click view site information (the lock icon) next to the Intelligent Service Management URL in your browser address bar.
2. Navigate to Certificate, Details, and click Copy to File.
3. Click Next and set the format that you want to use as .DER encoded binary X.509 (.CER).
4. Click Next, enter the file name, and save the file.
5. Click Next, verify the path, and click Finish.
6. Copy the saved certificate file to the ADSync root (ad-user-sync\) location.
7. Run the keytool command from the ADSync root (ad-user-sync\) location.

8. Import the saved certificate to the ADSync local keystore si by running the following command from the ADSync root:
   keytool -importcert -trustcacerts -alias aliasname -keystore si -file saved_certificate_file_name
   Note: To run the keytool command from the ADSync root, you need jre/bin in your PATH environment variable.
   Replace aliasname with the alias of your choice. For example, cacloudsmcert.
   Replace saved_certificate_file_name with the name of the saved certificate file. For example, cacloudsmcert.cer
   Use itmaas when prompted for password. The command prompt asks you to confirm whether the certificate can be trusted. Enter y.
   A message displays stating that the Certificate was added to keystore.

Enable LDAP SSL Certificate for the ADSync Utility

To enable an LDAP SSL certificate for the ADSync Utility, perform the following steps:

1. Get the LDAP SSL certificate either .DER or .CER format
2. Run the keytool command from the ADSync root (ad-user-sync\) location.
3. Import the saved certificate to the ADSync local keystore si by running the following command from the ADSync root:
   keytool -importcert -trustcacerts -alias aliasname -keystore si -file saved_certificate_file_name
   Note: To run the keytool command from the ADSync root, you need jre/bin in your PATH environment variable.
   Replace aliasname with the alias of your choice. For example, cacloudsmcert.
   Replace saved_certificate_file_name with the name of the saved certificate file. For example, cacloudsmcert.cer
   Use itmaas when prompted for password. The command prompt asks you to confirm whether the certificate can be trusted. Enter y.
   A message displays stating that the Certificate was added to keystore.

Follow the below steps to verify the certificates in the keystore:

1. Copy the si file to a directory.
2. Execute the below command:

   E:\>keytool -list -keystore si
   Enter the keystore password, Keystore type and Keystore provider.

3. Upon successful certificate import, 2 certificate entries should be available in the Keystore.

Test the Utility

You can run the ADSync Utility without actually sending the data to Intelligent Service Management database. To stop the data from being sent to the database, set the send.data attribute in the sync.properties file as No. The output data is displayed in the sync_data.log.0 file. The data is also added in the DATA.csv file. You can review these files to verify whether the utility is running as expected.

After the testing is over, reset the send.data attribute to Yes.

You can perform the test runs for the initial few synchronization attempts, to ensure that the utility is configured properly.

You can also use the send.data attribute to test the modifications in parameter values. When you modify a parameter value, perform a test synchronization. Update the Intelligent Service Management database only when the test run is successful.

Create a Job Scheduler

You can create a job scheduler for running the synchronization regularly. For example, if you have a UNIX environment, you create a cron job to run the utility. The job scheduler calls one of the supplied script files to execute the ADSync utility. The script files are:

• sync.bat (Windows)
• sync.sh (UNIX)

These scripts are included in the zip file and are used as is; no editing is required. The files are located in the script folder in ADSync Utility.

Configure the job scheduler so that it calls the appropriate script file at the desired interval. Ensure that sufficient access rights are granted to execute the script file. You are now ready to run the ADSync utility.

Upgrade the Utility

The ADSync Utility is updated from time to time. You can upgrade to a newer version when it is available. To avoid loss of data, follow the instructions that are provided in this topic.

While you are upgrading to the new version, verify that your utility configuration is unchanged from your existing installation. Also verify that your latest backup is available in the upgraded utility.

Follow these steps:

1. Download and unzip the new version of the utility.
2. Copy all modified properties files from your existing ADSync folder to the same location in the new ADSync folder.
3. Add back any new parameters that are introduced in the upgrade.
4. Copy all contents of the backup folder, except the dtd folder, from the existing ADSync folder to the new folder.