SYSTEM Active Directory synchronization

Use the SYSTEM Active Directory Synchronization map to synchronize the Active Directory (AD) resources with TotalAgility.

This map synchronizes organizational units and their associated groups and users within the Active Directory; it does not synchronize any containers, objects, or users outside of an organizational unit.

For example, in the XYZ organization, the following Organization Units are available under Root:

  1. OU-ABC

    1. OU-ABC-Sales

      • OU-ABC-User 1

      • OU-ABC-User 2

    2. OU-ABC-Marketing

      • OU-ABC-Group 1

      • OU-ABC-Group 2

      • OU-ABC-Group 3

    3. OU-ABC-R&D

      • OU-ABC-User 4

      • OU-ABC-User 5

  2. OU-DEF

    1. OU-DEF-Sales

      • OU-DEF-User 1

      • OU-DEF-User 2

    2. OU-DEF-Services

      • OU- DEF -Group 1(Members: OU-ABC-User 1 and OU-DEF-User 1)

      • OU- DEF -Group 2

      • OU- DEF -User 3

  3. OU-GHI

If you synchronize the OU-ABC organization unit with TotalAgility, all organization units, groups and users within the OU-ABC organization unit will be synchronized with TotalAgility.

However, if you synchronize a specific group level AD, TotalAgility creates a category for this group at the highest level; it does not copy the full structure. For example, if you synchronize OU_ABC-Group 2, TotalAgility creates a category for OU_ABC-Group 2 and adds all the groups/users that belong to this group to the Resources group within this category.

When you run the SYSTEM Active Directory Synchronization process map:

  • If the AD user already exists within TotalAgility, then any resource imported by the process does not overwrite the existing resources and the map completes. If any errors exist, it appears in the ErrorXml variable.

  • If a category already exists within TotalAgility, another category is not created with the same name; and the users are imported into the default category. The users can then be moved to another category if need be.

The map includes server variables to define items including account name to authenticate with Active Directory, password, email subject, email content, and the rest for individual client requirements. The following table describes the server variables used with SYSTEM Active Directory Synchronization map:

Server Variable



Email address of the user or group who is notified of critical errors, such as


Content of the critical error in the email, such as There has been a critical error syncing with Active Directory. Error returned was:.


Subject of the critical error in the email, such as Critical Error Syncing Active Directory.


Content of the soft errors (not critical) in the email, such as, Some Errors have occurred while syncing with Active Directory, please visit the link below to view these:


Subject of the soft errors in the email, such as, There were errors during the sync with Active Directory.


Active directory synchronization tries to delete users from TotalAgility when corresponding users are deleted from the active directory. If deletion of user fails for any reason, such as the user is assigned to an activity, and if AD_DEACTIVATE_USER flag is set to true, user is deactivated in TotalAgility, otherwise an error is logged.


Every change within Active Directory gets a unique incrementing change number (USN). This number is stored in TotalAgility in the AD_LAST_USNCHANGED server variable. (Default: 0). This variable is used by the Active Directory Synchronization activity and a value of 0 ensures that full synchronization of all data is complete.

Note The latest USN is then updated to the AD_LAST_USNCHANGED server variable. Subsequent synchronization will only check for changes since the last USN number. This is the routine synchronization for the system. For full synchronization, you can manually reset the AD_LAST_USNCHANGED server variable to 0 and execute a new job on the SYSTEM Active Directory Synchronization map.


Password for the account to connect to your Active Directory server.


The port used for LDAP or LDAPS protocol. If the port is not specified, the default port 389 or 636 is used for respective LDAP or LDAPS.


The TotalAgility security level of TotalAgility defined resource required to complete the activity. The default value for this security level is 10.

Note If the security level is 10, TotalAgility resources with any security level can complete the activity. If the security level is one, only TotalAgility resources with the highest level of security can complete the activity.


Machine name of your Active Directory server.

Note TotalAgility only uses Server Name and OU combinations in the AD_SERVERNAME variable. For example,
  • <SERVER_NAME> - synchronizes from AD root.

  • <SERVER_NAME>/OU=OU-ABC - synchronizes from the AD Organizational Unit "OU-ABC" downward

  • <SERVER_NAME>/OU=OU_ABC-Sales,OU=OU-ABC - synchronizes from the AD Organizational Unit OU_ABC-Sales within OU-ABC downward


A specific group level where the AD will be synchronized. This means that only those resources which are members of this group will be synchronized. For example, CN=OU_ABC-Group 1, this means that all the resources belonging to OU_ABC-Group 1 will be imported to TotalAgility.

Note These variable names are case sensitive; if you do not enter the values the same as they are created within AD, the job suspends and reports an error such as Parameter is Incorrect or Parameter is not Found.


Indicates whether SSL can be used over LDAP when synchronizing TotalAgility with Active Directory server. (Default: False)


A valid ActiveDirectory account to connect to your Active Directory server.

  • ad_username must have appropriate user rights on the particular items being synchronized in Active Directory to extract the relevant information from Active Directory.

  • The user name with more than 56 characters will be truncated.


If this variable is set to True, then even a resource existing elsewhere in the AD structure, but is a member of the group you are syncing, is imported. For example, if you synchronize OU- DEF -Group 1 the OU-ABC-User 1 (which is part of OU-ABC-Sales) will also be imported along with other members of this group.

Note This only works if Chase Referral is also enabled within AD itself. The default value for this variable is False. The AD_CHASE_REFERRAL is useful when importing cross domain resources.


Holds a valid email address for the system account sending the mail to administrator.

Note Change the values of the server variables, in particular, AD_SERVERNAME, AD_USERNAME, AD_PASSWORD, and AD_EMAIL_ADMINISTRATOR, to suit the requirements of your organization.