fxLdapSync - synchronization FX/MX users with LDAP

Application purpose and function
Application configuration
Synchronization logic description for FaxChange
Synchronization logic description for MobilChange

Application purpose and function

FXLDAPsync is application for FaxChange/MobilChange user database synchronization with LDAP server (so users must be stored in database, not in Active Directory; but MobilChange users can be stored in the registry).

FaxChange (MobilChange) database is accessed using fxODBC (ADO) interface, so application must be run directly on FaxChange (MobilChange) server. To install it, simply copy content of support\FaxChange\FxLDAPsync folder from UMS CD to disk on server.
Application gets list of users based on specified filter from LDAP server and according this list configures, creates or deletes users in FaxChange (MobilChange) database. It can report info about its work in umsMonitor (you must import umsmonitor.reg file from install folder into registry) and sends result of synchronization to the specified address.

Application can be run manually or in regular intervals using any task scheduler, e.g. like task in umsTaskManager.

Application configuration

Configuration is stored under registry key [HKLM/Software/datasys/faxchange/fxldapsync].

Values description:

cesky_telecom= 0 - normal mode (synchronization based on e-mail address), 1 - Czech Telecom mode (synchronization based on EmplID)
email_gw - gateway type for mail sending, by default "s" (SMTP)
enable_add - enable/disable (1/0) adding of new users into FX database
enable_remove - enable/disable (1/0) deleting users from FX database
fx_charset - FX database charset encoding, by default (if not defined): CP1250
Possible values see libiconv documentation
fx_server - FaxChange server name
is_ad = 0/1 - Czech Telecom mode setting saying, if X500 / AD is used
ldap_filter - filter for reading data from LDAP, by default: (serialNumber=*). If serialNumber attribute is not present in LDAP, you must enter valid filter!
ldap_charset - LDAP charset encoding, by default (if not defined): UTF-8
ldap_multi_filter - template filter for ldap_only_once=0; is it contains "%s" string, it is replaced by alphabet letters; if value doesn't exist, "(mail=%s*)" is used

table of LDAP attribute names mapping (ldap_nm_*) with recommended settings for Active Directory. Values ldap_dv_* are default attribute values (if attribute is not present in LDAP, this values will be used as if stored in LDAP), ldap_mf_* are switches of value modification for existing user (1=modify value for existing user (default), 0=do not modify).

ldap_nm_EmplID=DsFx2ID	ldap_dv_EmplID	--	user ID uživatele, e.g. personal number
ldap_nm_fEmail=mail	ldap_dv_fEmail	ldap_mf_fEmail	mail address
ldap_nm_Mobile=mobile	ldap_dv_Mobile	ldap_mf_Mobile	mobile phone
ldap_nm_fName=displayName	ldap_dv_fName	ldap_mf_fName	display name or name (givenname)
ldap_nm_fName2	ldap_dv_fName2	ldap_mf_fName2	surname (sn)
ldap_nm_fCostCode=DsFx2Costcode	ldap_dv_fCostCode	ldap_mf_fCostCode	costcode for user
ldap_nm_Phone=telephoneNumber	ldap_dv_Phone	ldap_mf_Phone	phone number
ldap_nm_FaxNum=facsimileTelephoneNumber	ldap_dv_FaxNum	ldap_mf_FaxNum	fax number
ldap_nm_FaxFlg	ldap_dv_FaxFlg	ldap_mf_FaxFlg	setting of FaxChange rights
ldap_nm_fCover=DsFx2Coversheet	ldap_dv_fCover	ldap_mf_fCover	coversheet name
ldap_nm_fGroup=DsFx2Group	ldap_dv_fGroup	ldap_mf_fGroup	user's group in FaxChange
ldap_nm_Division	ldap_dv_Division	ldap_mf_Division	division
ldap_nm_Dept=department	ldap_dv_Dept	ldap_mf_Dept	department
ldap_nm_Job	ldap_dv_Job	ldap_mf_Job	job name
ldap_nm_Street=streetAddress	ldap_dv_Street	ldap_mf_Street	address
ldap_nm_City=l	ldap_dv_City	ldap_mf_City	city or location

Red values - used for FX mode only
Green values - used in both modes
Black values - used for MX mode only

ldap_only_once – method of reading users from LDAP. If equal to 0, LDAP users are got by sequential reading in alphabetical order (must be used when LDAP server can not return all users by single query), otherwise single read operation is used. Default value is 1.
ldap_server_1 - first LDAP start point in form: host|port|root_dn|search_base|password
Example: 192.168.16.202||cn=Dir Manager,o=CESKY TELECOM,c=CZ||pass
If port is empty (see example), default value 389 is used.
If search_base is empty, it is created from root_dn (in example o=CESKY TELECOM,c=CZ will be used)
Password must be stored in encoded form - run fxLdapSync with /w parameter and password typed from keyboard will be stored into registry in encoded form.
ldap_server_2, ldap_server_3, ... - other start points, if necessary.
ldap_sync_e - sender's e-mail address. Messages with information from "fxldapsync" will be sent with this email address (default value is fxLdapsync@localhost)..
logpath - if present, log file in form fxldapsyncYYMMDD.log is written to this folder
loglevel - logging level: 1 (least) to 5 (most), default 3
pabx_len - virtual faxnumber length (PABX)
r_admines - administrator's e-mail address (recipient)
r_adminns - administrator's name (recipient)
restricted_faxs - list of fax numbers separated by semicolon, which will not be assigned to the users

Example of registry settings for MS Active directory LDAP server can be found in fxLdapSync.reg file in installation folder.

Command line parameters:

fxLdapSync [options]
options: /<appname>      application type (FX or MX). If not specified, FX is assumed
         /w              prompt for password for root_DN
         /d<path>        log path. valid only if "logpath" parameter is not specified in the registry.
         /r<path>        name of alternative configuration. It must be stored as subkey of HKLM/Software/datasys/faxchange/fxldapsync.
         /h              this help

Alternative configuration is good for separate settings for synchronization of FaxChange and MobilChange, or for synchronization against more LDAP servers with different setting.
Tools is able to synchronize also distribution groups and public folders (only those visible in addressbook) - setting of ldap_filter from fxLdapSync.reg file allows this. But you must add "Microsoft Exchange System Objects" container of Active Directory into searched branch.

Synchronization logic description for FaxChange

Common part

Application reads into memory all users from FX database, which have bit 2 in fControl array equal to 0 (i.e. no FX groups).
Application reads into memory all users from all LDAP start points.

It can happen that some fields (e.g. FAXFLG) aren't present in LDAP. In such case application takes from configuration default values and use them as if they were read from LDAP.
Processing in "Czech Telecom" mode is specific for this company and is not described here. In common you should use "normal" mode described bellow.

"Normal" mode

For every user in FX database reads FreeText field and parse it. These items are important:

NoSync – do not synchronize account
AutoPABX – last used PABX
EmailHand – synchronize partialy/fully (1/0)

For all records which have non-empty fEmail and don't have NoSync=1:

search for record with the same e-mail in LDAP data
if record is found:
- transfers these LDAP items according to configuration into FX database (see table bellow)
  1. name / display name (full synchronization only)
  2. FX group name (full synchronization only)
  3. fax permissions (full synchronization only)
  4. costcode
  5. coversheet name (full synchronization only)
  6. Employee ID
  7. sets fGate = email_gw value (full synchronization only)
- processes PABX for given user:
  1. reads user's fax number from LDAP, uses its last right [pabx_len] digits (new PABX)
  2. if AutoPABX = new PABX: do nothing
  3. if AutoPABX <> new PABX:
    - delete record from tPABX table, where fPABX = AutoPABX and fUserId = current FX record UserId
    - creates tPABX record: fPABX = new PABX, fUserId = current UserId
    - writes/changes AutoPABX=new PABX item in FreeText item for FX record
- marks LDAP record as synchronized (or deletes it from the memory)
if record is not found: delete record from FX database

Now goes through LDAP records not marked as synchronized (not deleted). These are records existing in LDAP but not in FX database. For every of them:

Creates new user in tUser table with unique fId
Writes these data from LDAP into new user:
1. e-mail address
2. name / display name
3. FX group name
4. fax permissions
5. costcode
6. coversheet name
7. sets fGate = email_gw value
Creates record in tPABX table with fPABX = new PABX, fUserId = current UserId
Writes AutoPABX=new PABX item in FreeText item for FX record

Mapping LDAP items to FX db items

Names of searched items in LDAP must be taken from configuration, so if FAXNUM item is renamed to FAX_NUMBER, you simply change information in configuration!

LDAP name	tUser name	Remark
FAXNUM (string, <30 chars)	No direct equivalent, but used to generate record in PABX database (see algorithm above) and AutoPABX item in FreeText	unique fax number, used for fax receiving
FAXCSH (string, <30 chars)	fCover	coversheet page name for given user
FAXGRP (string, <30 chars)	fGroup	defines user group which is user member of and whose standard settings will be applied to this user's FaxChange attributes if explicit setting isn't specified
FAXFLG (string, <30 chars)	fFlags, fControl, fLng – see next table	contains these settings: fax permissions and language; structure is described in next table
INTERNET-ADDR	fEmail	SMTP address
COSTCODE	fCostCode	Cost centre code
COMMON-NAME	fName	User name

FAXFLG item structure

It is text field, where every character specifies some part of FX settings.

Char	Meaning	Values	Mapping to FX
1	right to send international faxes	y (yes), n (no), d (standard setting according to group rights)	fFlags character 1, values Y/N/D
2	right to send long distance faxes	y (yes), n (no), d (standard setting according to group rights)	fFlags character 2, values Y/N/D
3	right to send faxes out of your PBX	y (yes), n (no), d (standard setting according to group rights)	fFlags character 3, values Y/N/D
4	right to send faxes inside of your PBX	y (yes), n (no), d (standard setting according to group rights)	fFlags character 4, values Y/N/D
5	right to use low priority faxes	y (yes), n (no), d (standard setting according to group rights)	fFlags character 5, values Y/N/D
6	right to use normal priority faxes	y (yes), n (no), d (standard setting according to group rights)	fFlags character 6, values Y/N/D
7	right to use high priority faxes	y (yes), n (no), d (standard setting according to group rights)	fFlags character 7, values Y/N/D
8	right to schedule fax sending	y (yes), n (no), d (standard setting according to group rights)	fFlags character 8, values Y/N/D
9	right to send faxes	0 (yes, standard user), 1 (no, faxing disabled)	fControl bit 0: 0 = enabled, 1 = disabled
10	setting language for communication	0 (CZ), 1 (UK), 2 (SK)	fLng = "CZ", "UK" or "SK"

Synchronization logic description for MobilChange

Common part

Application reads into memory all mail users from MX database, (account_type=1), which have user_source=2,3 or 4
Application reads into memory all users from all LDAP start points.

It can happen that some fields aren't present in LDAP. In such case application takes from configuration default values and use them as if they were read from LDAP.
Processing in "Czech Telecom" mode is specific for this company and is not described here. In common you should use "normal" mode described bellow.

"Normal" mode

For all records which have non-empty i_user_id and have x_email_rucne=0:

search for record with the same e-mail in LDAP data
if record is found:
- transfers these LDAP items according to configuration into MX database
  1. email addres (into email item)
  2. name / display name
  3. cost centre ID
  4. sets Gateway = value of email_gw
- marks LDAP record as synchronized (or deletes it from the memory)
if record is not found: delete record from MX database

If i_user_id is empty (null), sets x_email_rucne=1.
Now goes through LDAP records not marked as synchronized (not deleted). These are records existing in LDAP but not in MX database. For every of them:

Creates new user in MXUser table with i_user_id=email
Writes these data from LDAP into new user:
1. e-mail address
2. name / display name
3. cost centre ID
4. sets Gateway = value of email_gw