Knowlege base

Synchronize Users against an AD/LDAP Sources

Article ID: 21
Last updated: 25 Jul, 2022

All the applications included in the UC Suite share the same users list. This list can be edited manually through the web interface, adding users one by one, or automatically, importing the user list from a CSV file. If you have a large number of users, you might want to keep the user list in sync with an external directory.

The Synchronization Service lets you import users from an external source such as Active Directory, a database or the PBX. Once synchronization is enabled, the service will align the list of users once a day. When a new user is added to the external source it is inserted into the UC Suite users list. When the properties of a user are updated, the changes are written to UC Suite user data. Data transfer is optimized and only the differences are written to the database.

You could also use the synchronization service to import users once, then disable it and adjust the list manually.

Supported operations and matching criteria

The user synchronization service can perform three types of operation:

  • Insert, i.e. adding a new user
  • Update, i.e. changing one or more properties of an existing user
  • Delete, i.e. removing the user from the list

An UC Suite User list is considered to be the same as an Active Directory User when the "Active directory username" field combined with the "Domain" field value matches the Active directory account. E.g.

  • Active directory account =
  • Active directory username field in User Management = John.Smith
  • Domain field in User Management =

By default users which are deleted from the external source are automatically removed from the UC Suite. This is the main difference between importing users from CSV and synchronization. CSV import does not remove users, while the synchronization does.

If you want to create additional local users which will not be deleted when the sync operation is performed, make sure that the fields used as synchronization key (Active directory username and Domain) are blank.

How to enable Users Synchronization

You can access user synchronization through the web interface by selecting "User Management", then clicking the link "Synchronize users with an external data source" on the top of the page.

On the Welcome screen press the "Begin" button. This will enable the service.

To properly configure user synchronization, you have to:

  • Setup the connection to the data source
  • Configure the import rules
  • Enable alarms (optional)

Configuring the Data Source connection

Click the "Configure Data Source" link and select the type of external directory from which you want to import users. These may vary depending on your telephony system. Active Directory is available for all platforms.

Active Directory Connection Configuration

Enter a name for the source, e.g. MyCompanyDC, and press the "Add new source" button. The name must be unique, al least three characters long, and must contain no blanks.

Fill the form fields with these values:

  • Server: the DNS Name or IP address of the Active Directory server. If you use the DNS name, the Application Suite server must be able to resolve it
  • LDAP object path: the subtree from which the accounts user will be imported. Basics of LDAP queries can be found on Microsoft web site.
  • Username: you must enter the credentials of a domain user. This does not need to be an Administrator; any domain user can access the Active Directory
  • Password: tick the checkbox to the right to show or hide the password characters

Note: If you leave the "LDAP object path" field blank, the "Users" branch will be queried.

Press "Add" and "Back". When the new source has been added, enable it through the checkbox. Once enabled, the service will test the connection parameters.

Active Directory Secure Connection

As of March 2020, Microsoft is updating security requirements for LDAP connections to Active Directory. After this update, Secure LDAP (LDAPS) will become mandatory for all LDAP connections to Active Directory. LDAP connections to Active Directory will not work unless Secure LDAP is configured.

Starting from Spring 2020 release and above, Imagicle follows above Microsoft statement and, for new IAS installations, Secure LDAP using SSL on port 636 is automatically enabled for both authentication and users' synchronization.

If you are upgrading an existing IAS to Spring 2020 or above, the connection is automatically migrated to Secure LDAP and a test is performed to verify AD server reachability. If reachability is granted, then it means Microsoft statement has been respected. If AD can't be reached, then we just leave the connection as it is.

It is also possible to change manually the LDAP authentication settings:

  • access to Imagicle server via RDP and edit file C:\Program Files (x86)\StonevoiceAS\Apps\Fw\Settings\FW.Profile.Api.config.xml
  • add a new line, or update the existing one, for the preference Authentication.UseSecureLDAPConnection (see image below)
<?xml version="1.0" encoding="utf-8"?>
  <preference key="Authentication.UseSecureLDAPConnection" value="SecureThenUnsecure" />
  <!-- OR -->
  <preference key="Authentication.UseSecureLDAPConnection" value="SecureOnly" />
  <!-- OR -->
  <preference key="Authentication.UseSecureLDAPConnection" value="UnSecureOnly" />
  • possible values are:
    • SecureThenUnsecure: authentication is tried to be granted using Secure LDAP (LDAPS), if connection failes, authentication is tried again using unsecure LDAP;
    • SecureOnly: authentication is tried to be granted using ONLY Secure LDAP (LDAPS);
    • UnSecureOnly: authentication is tried to be granted using ONLY unsecure LDAP

Configuring Synchronization Rules

The external directory will not contain all the information needed to fill the Users profile properties. You have to provide the missing values through the web interface.

On the top of this page, select the type of source you want to configure the rules for (Active Directory).

For each field you have the various choices including the following.

  • Only when adding a new user set this value (followed by a textbox): this option applies only to insert operations. You can specify a default value for the field, which you could modify later from the User Management page, since it will not be overwritten if the user already exists.
  • Only when adding a new user set this value (followed by a checkbox): the same as the previous option for boolean fields. Boolean fields can only be set to true (checked) or false (unchecked).
  • Import every time from source: applies both to insert and update operations. You decided to manage this property from the remote data source, so the value will be synchronized at each cycle.
  • Keep existing value: the property will not be synchronized. You'll manage the value from the IAS web interface. When the user is created (insert operation) the field will be set to blank. During next cycles (update operation) the value will remain unchanged.

Other options may involve specifying a prefix to be added to another field value. For instance the First extension number may be imported from the Telephone Number or IP Phone or Skype for Business SIP URI Active Directory fields.

Warning: not all the choices may be available for all the fields. E.g. there is no point in assigning the same default value to a user's personal address.

Save the changes

The Apply button saves the changes. The Reload button undoes the changes. The Default button resets to the default values.

Press "Next" or "Back" to continue.

Synchronizing Users against Active Directory - Supported Attributes List

This table list the Active Directory user attributes and shows the UC Suite fields they are mapped to.

  • Active Directory Display Name: label displayed in the Active Directory user interface
  • LDAP Attribute Name: name to be used in LDAP queries, reported for reference but not required to configure UC Suite
  • UC Suite Field: Label displayed in the adapter's rule configuration UC Suite web page
  • UC Suite Database name: this is never displayed to the user

General Tab

Active Directory Display Name LDAP Attribute Name UC Suite Label UCSuite Database name Example Value
First Name givenName First Name user_nome John
Initials initials - - JS
Last Name sn Last Name user_cognome Smith
Display Name displayName - - "John, Smith"
Description description - - Sales Manager
Office physicalDeliveryOfficeName - user_office_location London Office
Telephone Number telephoneNumber First Extension Number* user_telnum, user_amnum 0123 456 789
Telephone Number (Other) otherTelephone - - 0123 4457 89
Email mail Email, "Voicemail Address", "Fax to Email Address", "Single Sign-on Id" user_mail, user_voicemailaddr, user_pref_fax_mailinaddr, ssoid
Web Page wWWHomePage - -
Web Page (Other) url - -,
Password password - - JohnsPass321
Destination OU destinationOU - - OU=Sales,DC=Domain,DC=Com
Common Name CN - - John Smith or %lastname% %firstname%
Modify User if already exists Modify - - True or False
Delete User Delete - - True or False

Address Tab

Active Directory Display Name LDAP Attribute Name UCSuite Label UCSuite Database name Example Value
Street streetAddress User address user_address 10 Downing St;London
(Use a semi-colon for carriage return)
PO Box postOfficeBox - - Po Box 1
City l (Lowercase L) - - London
State/Province st - - New York
Zip/Postal Code postalCode - - 20013
Country c - - GB

Account Tab

Active Directory Display Name LDAP Attribute Name UCSuite Label UCSuite Database name Example Value
User Logon Name userPrincipalName Active Directory username, Domain, Single Sign-on Id*** userPrincipalName, user_ad (without domain), user_domain (without the username), user_authname, ssoid
User Logon Name (Pre W2K) sAMAccountName PBX username user_ccmname JSmith

Telephones Tab

Active Directory Display Name LDAP Attribute Name UCSuite Label UCSuite Database name Example Value
Home homePhone Home phone user_telcasa 123 123 123
Home (Other) otherHomePhone - - 0123 123 123
Pager pager - - 1234
Pager (Other) otherPager - - 123
Mobile mobile Mobile business number user_mobileBusinessNumber 123 456 789
Mobile (Other) otherMobile - - 123 456 789
Fax facsimileTelephoneNumber Fax number user_faxNumber 123 456 789
Fax (Other) otherFacsimile
- - 0123 456 789
IP Phone ipPhone First Extension Number* user_telnum, user_amnum 750
IP Phone (Other) otherIpPhone - - 330750
Notes info - - General information (Use a semi-colon for carriage return)

Organization Tab

Active Directory Display Name LDAP Attribute Name UCSuite Label UCSuite Database name Example Value
Title title - - Manager
Department department Department user_department Sales
Company company - - Big Corp
Manager manager - - CN=Ste Jobs,OU=Managers,DC=Domain,DC=Com
Employee ID employeeID - -
Employee Type employeeType - -
Employee Number employeeNumber - -
Car License carLicense - -
Division division - -
Middle Name middleName - -
Room Number roomNumber - -
Assistant assistant - - CN=Joe Blog,OU=Managers,DC=Domain,DC=Com
User's Picture** jpegPhoto / thumbnailPhoto - Pictures are saved in SQL DB JPEG pictures supported. Max 200KB size

* Either telephoneNumber or ipPhone attributes can be imported based on synch rules configuration

** Feature supported from Imagicle 2020.Winter.1 release. Either jpegPhoto or thumbnailPhoto attributes can be imported, based on synch rules configuration

*** Single Sign-On feature, based on SAML or OpenID Connect protocols, is supported from Imagicle 2022.Winter.1 release.

Extension Number Alias Synchronization

This field is by default left empty, If required, you can synch this user's field from the following attributes:

  • Active Directory:
    • otherTelephone
    • otherIpPhone
    • telephoneNumber
    • ipPhone
    • UserPrincipalName

  • LDAP:
    • Telex Number
    • telephoneNumber
    • pager
    • mail

Site Name synchronization

Starting from Imagicle UC Suite Summer 2021, we can import Site Name from Active Directory or LDAP, to enable overlapping dial plan across multiple gateways or PBXs.

Depending on the users repository source, the Site Name can be synchronized from one of the following attributes (selectable in the synch rules page):

  • Active Directory:
    • department (default)
    • physicalDeliveryOfficeName
    • company
  • LDAP: 
    • departmentNumber (default)
    • o
    • ou
    • l

Users' pictures synchronization

Starting from Imagicle UC Suite Winter 2020, users' pictures can be synchronized with Active Directory LDAP, to enable two UC Suite features:

  • Viewing the user photo in the 'Colleagues' tab of the Imagicle Attendant Console.
  • Providing a users' picture repository for Cisco Jabber clients. Please see here.

Depending on the users repository source, the picture can be synchronized from one of the following attributes (selectable in the synch rules page):

  • Active Directory:
    • jpegPhoto
    • thumbnailPhoto
  • LDAP: 
    • jpegPhoto

The default maximum picture size is 200 KB, bigger pictures will be discarded. If you need to adjust such size threshold, please contact Imagicle Support.

Pictures are saved in the Imagicle database.


The Synchronization service is able to send alarms and warnings should a problem occur during or after synchronization. A brief report is included. The options are pretty self-explanatory. The global SMTP settings are used.

Testing user Synchronization

Once the configuration is complete, you can test it live by pressing the "Run now" button.

Warning: the synchronization process can take a long time if you have a large number of users, depending on the data source type.

To setup the daily schedule, use the "Enable Auto mode" checkbox. Set the hour of the day when you want the service to run, and press save the changes. A countdown will tell you the time left to the beginning of the process.


Every time the synchronization process is completed, a text report is generated. You can download the report through the web interface. Reports older than 15 days will be automatically removed.

If the synchronization operation is successful, the report contains only statistics. If a user is skipped, details are included so you can edit the user in the data source and try again.

Should an unexpected error be raised, debug information is included in the report. In this case, please send the file to Imagicle Support.

Article ID: 21
Last updated: 25 Jul, 2022
Revision: 13
Views: 3050
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Importing from CSV files     Syncing Users' Privileges from Imagicle LDAP Module, generic...