SYSTEM Active Directory synchronization

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

TotalAgility does not support Active Directory synchronization with anonymous binding, as it is a security risk, and it does not enumerate the Active Directory Objects fully.

The SYSTEM Active Directory Synchronization 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

Description

AD_EMAIL_ADMINISTRATOR

Email address of the user or group who is notified of critical errors, such as "Admin@sampleemail.com".

AD_EMAIL_CONTENT_CRITICAL

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

AD_EMAIL_SUBJECT_CRITICAL

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

AD_EMAIL_CONTENT_ERRORS

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:"

AD_EMAIL_SUBJECT_ERRORS

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

AD_DEACTIVATE_USER

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 currently logged in or assigned to a live activity, the AD_DEACTIVATE_USER setting controls what happens next.

  • If AD_DEACIVATE_USER is set to false (default), then the Active Directory synchronization process logs an error attempting to delete the user. The process is then routed to a review activity (along with any other synchronization errors) for an administrator to review. The administrator may re-process any failures by taking corrective action such as forcibly logging out the target user.

  • If AD_DEACIVATE_USER is set to true, the user that could not be deleted is deactivated with no further access to the TotalAgility platform. In this case, the Active Directory synchronization process does not record an error or route it for review.

AD_LAST_USNCHANGED

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.

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.

AD_PASSWORD

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

AD_PORT

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

AD_SECURITY_LEVEL

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

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.

AD_SERVERNAME

Machine name of your Active Directory server.

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

AD_SERVERNAME_CN

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" means that all the resources belonging to "OU_ABC-Group 1" will be imported to TotalAgility.

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".

AD_USE_SECURED_CONNECTION

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

AD_USERNAME

A valid Active Directory 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 username with more than 56 characters will be truncated.

AD_CHASE_REFERRAL

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.

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.

SYSTEM_EMAIL_FROM

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

Change the values of the server variables, specificially for AD_SERVERNAME, AD_USERNAME, AD_PASSWORD, and AD_EMAIL_ADMINISTRATOR, to suit the requirements of your organization.