Knowlege base

Sync Users with External Sources

Article ID: 21
Last updated: 30 Mar, 2020

All the applications included in the 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 IAS users list. When the properties of a user are updated, the changes are written to IAS user data. Data transfer is optimised 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 Application 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 IAS. 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.


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: 30 Mar, 2020
Revision: 8
Views: 2642
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Users Permissions     Sync Users with AD