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.

Do not leave unnecessary line breaks or whitespaces in the searchBase.list file.

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

Intelligent Service Management Field Name	Active Directory Service Field Name	Comments
first_name	givenName
last_name	sn
job_title	title
e_mail	mail
user_login	sAMAccountName
manager	manager	Follow these rules: You cannot combine AD values and static values while representing this attribute. If you use the AD value, pass it as: manager=manager If you use a static value, you can define it only in one of the following formats: Either "LastName" or "FirstName", without any spaces. "LastName, FirstName ". Do include the comma and single space between the last name and first name. Note: You cannot refer to the manager attribute in the AD in ${manager} format. So, you cannot combine it with any other AD attribute or static value while defining an attribute.
primary_support_group		The spelling of the value that is provided in this attribute must match exactly with the corresponding value in Intelligent Service Management. For example, "administrator" is a primary support group in Intelligent Service Management. If you misspell the group as "aministrator" in the mapping, then the user is not mapped to the required group. This value is not case-sensitive. The value that you specify here is ignored if: The value does not match with any group in Intelligent Service Management. The value matches with an inactive group in Intelligent Service Management. You can enter only one primary_support_group for a user.
support_groups		The spelling of the value that is provided in this attribute must match exactly with the corresponding value in Intelligent Service Management. This value is not case-sensitive. The value that you specify here is ignored if: The value does not match with any group in Intelligent Service Management. The value matches with an inactive group in Intelligent Service Management. You can enter multiple support_groups for a user, separating them with a semicolon (;). If you have multiple support groups, you can pass them as either a static string or an active directory attribute. Consider the following rules while passing multiple values: If you want to use AD attributes, you can enter only one AD value in this file. Your definition of that AD attribute itself must include all the group names, separated by semicolons. For example, you want to pass the groups admin and public for a user. You can have an attribute that is named supportgroup in active directory and you can define its value within active directory as "admin; public". So, the mapping in the attribute_map.list looks like: support_groups=supportgroup If you pass a static string, you can do so by putting all the group names together, separated with semicolons, and included within quotes. So, the mapping in the attribute_map.list looks like: support_groups="admin; public" Also see, override_existing_support_group_values attribute.
override_existing_support_group_values	"False"	This attribute is supplementary to the support_groups attribute. With this attribute, you can specify whether the value passed for the support_groups attribute overwrites the existing value or is appended to it. This attribute can have one of the following two values: False: This is the default value. When the attribute is set to false, existing values are NOT overwritten. True: When the attribute is set to true, existing values are overwritten. Any invalid value for this attribute is treated as "False". This attribute affects only the support_groups attribute.
license_type	"1"	You can either directly provide a value as a static string or pass the corresponding attribute from active directory. To pass the value as a static string, put it in double quotes. The valid values are: 0, 1, 2, and 4, where: 0 = Fixed License 1 = Self-Service User 2 = Floater License 4 = Web Service User The default value is 1. Note: When the license type is 1, then the primary_support_group is automatically set to Self-Service. The value that is provided while defining the primary_support_group attribute is ignored. If you do not map this attribute or enter an invalid value, the license type is set to Self-Service (1) by default.
language	"en_US"	You can either directly provide a value as a static string or pass the corresponding attribute from active directory. To pass the value as a static string, put it in double quotes. For a list of all valid language codes, see Set Locations and Time Zones. The default language is “en-US”. This attribute is not case-sensitive.
org_name		Note: The mapping of org_name is governed by strict rules. For more information about this attribute, see Configure the org_name Attribute.
lvl1_name	company	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.
lvl2_name	physicalDeliveryOfficeName
lvl3_name	department
phone1	telephoneNumber
phone2	mobile

For Microsoft Active Directory, do not change the attribute names in the mapping file. For Novell e-Directory, only suggested attribute names have been listed. However, you can use any attribute names that are convenient.

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

For Microsoft Active Directory, do not change the attribute names in the mapping file. For Novell e-Directory, only suggested attribute names have been listed. However, you can use any attribute names that are convenient.

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:

Parameter Name	Parameter Description	Example Values
sync_log.pattern	Location for the log file. This file has a size limit of 50 MB. If the data exceeds 50 MB, then multiple log files are created. The latest log is available in sync_data.log.0. By default, the utility maintains the previous four logs. The older files are named as sync_data.log.1, sync_data.log.2, sync_data.log.3, and sync_data.log.4, respectively. You can modify the sync_log.count attribute to modify the number of previous log files.	../sync/logs/sync_data.log
sync_log.limit	File size limit for the log file in bytes.	5000000
sync_log.count	Number of files to retain for log rotation.	5
sync_log.level	Level of logging required. Possible values are: ALL: All logging statements - includes FINE, INFO, and SEVERE. FINE: All logging statements that are marked as FINE, INFO, and SEVERE. This value is used on the first run, for testing or validation purposes. INFO: All logging statements that are marked as INFO. This value also includes statements that are marked as SEVERE. Usually, this value is applied in production. SEVERE: Only logging statements that are marked as SEVERE are logged.	INFO
sync_err.pattern	Location for the sync error file. All the statements under the SEVERE level are logged in to this file. This file has a size limit of 50 MB. If the data exceeds 50 MB, then multiple log files are created. This file contains only the errors on the client side. The latest log is available in sync_err.log.0. By default, the utility maintains the previous four logs. The past files are named as sync_err.log.1, sync_err.log.2, sync_err.log.3, and sync_err.log.4, respectively. You can modify the sync_err.count attribute to modify the number of previous backups.	../sync/logs/sync_err.log
sync_err.limit	File size limit for the error log file in bytes.	5000000
sync_err.count	Number of files to retain for error log rotation.	5
sync_err.level	Level of error logging required. Possible values are: SEVERE: Only logging statements that are marked as SEVERE are logged.	SEVERE

sync.properties

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

Parameter Name	Parameter Description	Example Values
ldap.gc	This parameter specifies the Global Catalog server and port.	ldap://dcp1s:3268
ldap.dc	This parameter specifies the Domain Controller server and port and is usually the same as the Global Catalog server.	ldap://dcp1s:3268
ldap.bind.user	This parameter specifies the Distinguished Name of the service account that the utility uses for connecting to the Directory Server.	admin@abc.com
ldap.bind.isPwdEncrypted	If you do not want to store the LDAP password as plain text, ADSync Utility provides you the facility to use an encrypted password. When you use an encrypted password, this attribute is set to True. By default, this attribute is set to False. Any value other than True is treated as False. The ADSync Utility folder includes a password encryption utility named encryptLDAPPwd.sh or encryptLDAPPwd.bat. The utility is available in the ../scripts folder. Use only this utility to generate the encrypted password. When you run the encryptLDAPPwd utility, this attribute is automatically set to True. The encrypted password is automatically populated in the ldap.bind.user.pwd attribute.
ldap.bind.user.pwd	This parameter specifies the password for the service account that is specified in ldap.bind.user attribute. If you want to use an encrypted password, run the encryptLDAPPwd utility. When you run the encryptLDAPPwd utility, the ldap.bind.isPwdEncrypted attribute is automatically set to True and the encrypted password is populated in this attribute. If you are not using an encrypted password, ensure that the ldap.bind.isPwdEncrypted attribute is not set to True.
backup.data.folder	This parameter specifies the name and location of the backup folder. Do not change this value.	../sync/backup
search.base.list	This parameter specifies the location of the file which contains the list of Organizational Units (OUs). The utility uses this file to search for user data.	../conf/searchBase.list
ldap.searchFilter	This parameter specifies the LDAP filter for retrieving user entries from the Directory Server.	(&(objectClass=user)(objectClass=person)(objectClass=organizationalPerson))
data.file	This parameter specifies location of the file to which the incoming data is written to, for validation purposes.	../DATA.csv
record.limit	This parameter specifies a limit on returned records from the LDAP query and is used during diagnostics. Setting it to blank returns all records matching the query.
logger.file	This parameter specifies the location for the logging properties file.	../conf/logger.properties
pagesize	The value set for pagination of data that is retrieved from the Directory Server. The directory server implementations have this set to 1000. This value is the max number of records that the Directory Server can return. By setting this attribute to a value lower than that ensures pagination of data and retrieval of > 1000 records.	500
login.appender	This parameter specifies the appender to the directory server user ID. The value is used to create a Intelligent Service Managementuser ID, in email format. This value also allows organizations to have different user names and email IDs and still allow SSO. Do not modify the appender once it is set.	@companyname.com
ldap.attribute.map	This parameter specifies the map location for retrieving user attributes for each user.	../conf/attribute_map.list
authtoken	This parameter specifies the authorization token for the user integration engine in your slice.	This value is auto-populated when you download the ADSync Utility. DO NOT edit this value. If you happen to edit this value by mistake, download the ADSync Utility again.
slicetoken	This parameter specifies the additional token for dual layer security.	This value is auto-populated when you download the ADSync Utility. DO NOT edit this value. If you happen to edit this value by mistake, download the ADSync Utility again.
action.key	This parameter is a system defined action for processing user entries in Intelligent Service Management. Do not modify this parameter.	ESD_activeDirectoryUserProfileSyncAct
send.data	This parameter specifies the flag to stream user data over to Intelligent Service Management. This value is typically set to Yes. However, you can set it to No for diagnostic purposes and to verify local data files for errors. For more information about the diagnostic mode, see Test the Utility.	Yes
xml.response.dtd	This value is a system defined template that is used for processing the XML data. Do not modify this value.	../dtd/ProcessXMLDocument.dtd
action.url	This parameter specifies the URL to which the data is sent. Do not modify this URL.	This value is auto-populated when you download the ADSync Utility. DO NOT edit this value. If you happen to edit this value by mistake, download the ADSync Utility again. Note: For large transactions, the support team can provide you with a direct URL to the application, to resolve timeout issues. Only in such cases, you can update this attribute manually.
proxy.host	This parameter specifies the proxy server that your organization uses to send data over the web. If no proxy server is configured, leave this blank.
proxy.port	This parameter specifies the proxy server port that your organization uses to send data over the web. If no proxy server is configured, leave this blank.
proxy.auth.preference	This parameter specifies the type of proxy authentication in use. ADSync Utility supports only basic authentication.
proxy.user	Proxy user name.
proxy.password	Password for the proxy user name.
exit.on.severe	The flag to exit the process when an error is encountered. Recommended value is Yes.	Yes

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.

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. For more information about these levels, see attribute_map.list File. You can also define lvl1_name, lvl2_name, and lvl3_name with the org_name attribute. However, the utility gives a higher priority to the hierarchy defined in the org_name attribute.

Enable an ISM SSL Environment for the ADSync Utility

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

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

Get the LDAP SSL certificate either .DER or .CER format
Run the keytool command from the ADSync root (ad-user-sync\) location.
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:

Copy the si file to a directory.
Execute the below command:
E:\>keytool -list -keystore si
Enter the keystore password, Keystore type and Keystore provider.
Upon successful certificate import, 2 certificate entries should be available in the Keystore.

This procedure is verified on Internet Explorer and Chrome browsers.

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:

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

Browser not supported