Directory Synchronization Templates

DirX Identity provides the following directory synchronization templates in the Samples\metacp directory of the DirX Identity installation:

Full import to the Identity store from an LDIF content file (initial and subsequent; demos 1, 2, and 3)
Delta import to the Identity store from an LDIF content file (demo 4)
Export from the Identity store to an LDIF content file (demo 5)
Import to the Identity store from a Microsoft Exchange data file in Microsoft Exchange "admin" format (demo 6)
Export from the Identity store to a Microsoft Exchange data file in Microsoft Exchange "admin" format (demo 7)
Import to the Identity store from a DirX Identity Microsoft Exchange agent data file (demo 8)
Export from the Identity store to a DirX Identity Microsoft Exchange agent data file (demo 9)
Import to the Identity store from a Lotus Notes data file (initial, subsequent, delta; demos 10, 11, and 12)
Export from the Identity store to Lotus Notes data file format (demo 13)
Conversion of Exchange format to LDIF content format (demo 16)

This chapter describes the main features of the synchronization templates for importing from an LDIF content file and exporting to an LDIF content file. (See LDIF Content Format for a description of the file format.) See the file l-metacpReadme.txt in the Samples\metacp directory for a detailed description of how the demos can be applied and what the setup needs to be. See the chapters on the Lotus Notes and Microsoft Exchange Identity agents in the DirX Identity Agent Reference for a description of Lotus Notes and Exchange import and export data file formats.

This chapter also describes how to read and write XML data files.

Import from an LDIF Content File

This example synchronization template imports the contents of an LDIF-formatted file (LDIF content format) into the Identity store.You can use it to:

Perform an initial import to an empty Identity store from an import data file.The import data file is the only source for import and all of its entries are imported.
Perform a subsequent import to a non-empty Identity store.The control logic in the synchronization profile performs a search in the Identity store to get a list of the existing entries and uses this list to perform dynamic delta recognition on an entry basis.Entries that exist in the Identity store but which are not supplied in the import data file are deleted-the logic assumes that the import data file provides 100% of the Identity store contents and the Identity store is cleared of unwanted entries.The synchronization profile performs a second level of delta recognition for entries that exist in the Identity store and in the import data file.All attributes to be synchronized are compared between both entries and the Identity store entry is modified accordingly.

The example synchronization template runs under the following assumptions:

The Identity store setup is the sample PQR database starting at /O=PQR
The PQR database contains no Organizational-Person (ORP) entries
The collective attribute subentry does not define any collective attributes
The meta controller uses the default LDAP attribute names supplied with DirX Identity

Files

This synchronization template uses the following files and Tcl scripts:

Attribute Configuration Files	Description
l-ldifattr.cfg	LDIF attribute information (source)
ldapattr.cfg	LDAP attribute information (target)
Data Files	Description
ldif.data	LDIF file for initial import into the Identity store
ldif.data1	LDIF file for a subsequent import into the Identity store
Synchronization Profile Scripts	Description
common.tcl	Control logic section. Contains the utility functions that are common to all of the synchronization templates.
import.tcl	Control logic section. Imports a file into the DirX server using one global search.
map.l-import.ldif.tcl	Mapping section. Maps attribute values from LDIF syntax to LDAP syntax for importing into the Identity store.
l-import.ldif.tcl	Variable section. The user-callable script to run the initial and subsequent imports. The script calls import.tcl.
test.import.tcl	Control logic section. Performs only the data mapping and does not interact with the Identity store (for updates). This Tcl script is called if the profile switch test_mapping_only is set to TRUE in l-import.ldif.tcl. The script writes each input data entry plus the Tcl variable arrays (one for the entry with its attributes and one for the generated LDAP entry with its attributes) to the trace file. This output allows you to check the correctness of your attribute mappings.

Attribute Configuration Files

Description

l-ldifattr.cfg

LDIF attribute information (source)

ldapattr.cfg

LDAP attribute information (target)

Data Files

Description

ldif.data

LDIF file for initial import into the Identity store

ldif.data1

LDIF file for a subsequent import into the Identity store

Synchronization Profile Scripts

Description

common.tcl

Control logic section. Contains the utility functions that are common to all of the synchronization templates.

import.tcl

Control logic section. Imports a file into the DirX server using one global search.

map.l-import.ldif.tcl

Mapping section. Maps attribute values from LDIF syntax to LDAP syntax for importing into the Identity store.

l-import.ldif.tcl

Variable section. The user-callable script to run the initial and subsequent imports. The script calls import.tcl.

test.import.tcl

Control logic section. Performs only the data mapping and does not interact with the Identity store (for updates). This Tcl script is called if the profile switch test_mapping_only is set to TRUE in l-import.ldif.tcl. The script writes each input data entry plus the Tcl variable arrays (one for the entry with its attributes and one for the generated LDAP entry with its attributes) to the trace file. This output allows you to check the correctness of your attribute mappings.

Synchronization Profile Structure

The following sections describe the contents and design of this example synchronization profile.

Variable Section Settings

The Variable section of the example synchronization profile (see the file l-import.ldif.tcl) provides the following information:

A set of profile switches that configure the operation of the synchronization profile
The names of the mapping procedures defined in the mapping section

The following table describes the profile switches.

Name	Description
home_dir	The home directory in which the synchronization profile Tcl scripts are located
debug_trace	Controls the output of the source and target Tcl variables. Possible values are: 0-Do not output 1-Output to standard out (the display) 2-Output to the meta controller trace file
trace_file	The name of the meta controller trace file
trace_level	The trace level to be used. Possible values are: 1-Perform an error trace (only trace failed operations) 2-Perform a full trace (trace all operations) 3-Perform a full trace only on operations that are actually sent to the Identity store
init_mode	Runtime execution mode. Possible values are:* REAL* - All update operations are sent to the Identity store (actual database synchronization is performed)* TRIAL* - No updates are made to the Identity store (actual database synchronization is not performed). Use TRIAL mode to examine whether the synchronization, if run in REAL mode, operates as expected and does not perform any unwanted updates
superior_info	The parameters for the automatic creation of superior entries
agent_attr_file	The name of the Identity agent attribute configuration file
x500_attr_file	The name of the Identity store attribute configuration file
agent_data_file	The name of the import data file (generated by the Identity agent export procedure)
agent_attr_list	The attributes to be synchronized from the source connected directory
conn_type	The type of the connection to the Identity store (LDAP)
x500_attr_list	The attributes to be synchronized in the Identity store
file_format	The import data file format. Possible values are TAGGED and UNTAGGED.
process_all_attr	Controls whether or not all attributes are processed. Possible values are TRUE (process all attributes) and FALSE (process those attributes in ldap_attr_list).
object_class_abbr	The type of object class abbreviations (LDAP) used in the control logic section.
user_name	User name parameter for the obj bind operation
user_pwd	User password parameter for the obj bind operation
dsa_name	Name of the Identity store as defined in the directory client configuration file (dirxcl.cfg).
server_address	Identity store address (LDAP server DNS name or IP address and port number) for the obj bind operation.
protocol	The protocol to access the Identity store. Possible values are LDAPv2 and LDAPv3. See the description of the obj bind operation for details.
base_obj	Search base parameter for the obj search operation
subset	Search scope parameter for the obj search operation
filter	Search filter parameter for the obj search operation
sort_key	Sort key parameter for the meta sortresult operation. Possible values are ASC and DESC. See the meta sortresult description in the meta object section for details.
sort_order	Sort order parameter for the meta sortresult operation. Possible value is DDN. See the meta sortresult description in the meta object section for details.
perform_read	Controls whether the meta controller is to read all attributes from the Identity store during the initial search (FALSE) or with an additional read operation (TRUE)
remove_objects	Controls whether the meta controller is to remove entries in the Identity store returned in a search result that do not exist in the source data file. Possible values are TRUE (remove entries) or FALSE (do not remove entries).
marking_attr	This switch is only relevant when "remove_objects" is FALSE: Instead of removing the entry the specified attribute type is added to the entry (using the value specified in "marking_value") to mark it as deleted.
marking_value	This switch is only relevant when "remove_objects" is FALSE: Specifies the attribute value to be used for the attribute type specified in "marking_attr".
keep_objects	Specifies the objects that should never be removed from the Identity store, even if not provided in the data file. The template profile switch specifies the name of the administrator on whose behalf the directory bind is performed; this list can be extended
test_mapping_only	Controls whether the meta controller performs the data mapping operations but no other operations. Possible values are TRUE (test mapping only) and FALSE (run entire synchronization profile).
test_max_entries	Controls how many entries are to be mapped, if test_mapping_only is TRUE. Supply the number of entries to be mapped. If all entries are to be mapped, supply -1.
_localcode	The code set in which the data to be processed is encoded. Possible values are PC850 or LATIN-1.

Name

Description

home_dir

The home directory in which the synchronization profile Tcl scripts are located

debug_trace

Controls the output of the source and target Tcl variables. Possible values are:
0-Do not output
1-Output to standard out (the display)
2-Output to the meta controller trace file

trace_file

The name of the meta controller trace file

trace_level

The trace level to be used. Possible values are:
1-Perform an error trace (only trace failed operations)
2-Perform a full trace (trace all operations)
3-Perform a full trace only on operations that are actually sent to the Identity store

init_mode

Runtime execution mode. Possible values are:*
REAL* - All update operations are sent to the Identity store (actual database synchronization is performed)*
TRIAL* - No updates are made to the Identity store (actual database synchronization is not performed). Use TRIAL mode to examine whether the synchronization, if run in REAL mode, operates as expected and does not perform any unwanted updates

superior_info

The parameters for the automatic creation of superior entries

agent_attr_file

The name of the Identity agent attribute configuration file

x500_attr_file

The name of the Identity store attribute configuration file

agent_data_file

The name of the import data file (generated by the Identity agent export procedure)

agent_attr_list

The attributes to be synchronized from the source connected directory

conn_type

The type of the connection to the Identity store (LDAP)

x500_attr_list

The attributes to be synchronized in the Identity store

file_format

The import data file format. Possible values are TAGGED and UNTAGGED.

process_all_attr

Controls whether or not all attributes are processed. Possible values are TRUE (process all attributes) and FALSE (process those attributes in ldap_attr_list).

object_class_abbr

The type of object class abbreviations (LDAP) used in the control logic section.

user_name

User name parameter for the obj bind operation

user_pwd

User password parameter for the obj bind operation

dsa_name

Name of the Identity store as defined in the directory client configuration file (dirxcl.cfg).

server_address

Identity store address (LDAP server DNS name or IP address and port number) for the obj bind operation.

protocol

The protocol to access the Identity store. Possible values are LDAPv2 and LDAPv3. See the description of the obj bind operation for details.

base_obj

Search base parameter for the obj search operation

subset

Search scope parameter for the obj search operation

filter

Search filter parameter for the obj search operation

sort_key

Sort key parameter for the meta sortresult operation. Possible values are ASC and DESC. See the meta sortresult description in the meta object section for details.

sort_order

Sort order parameter for the meta sortresult operation. Possible value is DDN. See the meta sortresult description in the meta object section for details.

perform_read

Controls whether the meta controller is to read all attributes from the Identity store during the initial search (FALSE) or with an additional read operation (TRUE)

remove_objects

Controls whether the meta controller is to remove entries in the Identity store returned in a search result that do not exist in the source data file. Possible values are TRUE (remove entries) or FALSE (do not remove entries).

marking_attr

This switch is only relevant when "remove_objects" is FALSE:
Instead of removing the entry the specified attribute type is added to the entry (using the value specified in "marking_value") to mark it as deleted.

marking_value

This switch is only relevant when "remove_objects" is FALSE:
Specifies the attribute value to be used for the attribute type specified in "marking_attr".

keep_objects

Specifies the objects that should never be removed from the Identity store, even if not provided in the data file. The template profile switch specifies the name of the administrator on whose behalf the directory bind is performed; this list can be extended

test_mapping_only

Controls whether the meta controller performs the data mapping operations but no other operations. Possible values are TRUE (test mapping only) and FALSE (run entire synchronization profile).

test_max_entries

Controls how many entries are to be mapped, if test_mapping_only is TRUE. Supply the number of entries to be mapped. If all entries are to be mapped, supply -1.

_localcode

The code set in which the data to be processed is encoded. Possible values are PC850 or LATIN-1.

Mapping Section Procedures

For LDAP access to the Identity store, the main purpose of the mapping section of the example synchronization profile (see the file map.l-import.ldif.tcl) is to assign attribute values from LDIF records to attribute values in directory objects. This is a simple one-to-one mapping.

Control Logic

The control logic supplied in the example synchronization profile has the following characteristics:

Synchronizes from a single source only (the import file is the entry owner)
Moves all of the entries from the import file into the Identity store
Creates superior entries automatically with the parameters specified in the profile switch in the Variable section
Processes import entries individually
Performs dynamic delta recognition on the subsequent import. The delta recognition is performed in two phases:
- Matched entries: For matched entries, performs the modify operation on the target entry in the Identity store according to the target attribute synchronization flags set in the profile switch in the Variable section
- The set of entries supplied in the import file: compares the complete import file with the entries in the Identity store, removes any entries not supplied in the import file, and adds entries available in the import data file that do not exist in the Identity store.
No ordering of the import file is necessary

Customizing This Synchronization Template

To customize this synchronization template:

Ensure that its control logic matches your import synchronization needs
Determine whether you want automatic creation of superior entries. If you do, supply the information for it in the appropriate profile switch in the Variable section.
Develop attribute configuration files for the source and target directory (1 each). You can use the attribute configuration files supplied with DirX Identity as templates, or create your own.
Choose the specific set of attributes that you want to synchronize, for the source directory and for the target directory
Decide on your data file names and supply them in the appropriate profile switch in the Variable section
Supply your credentials for binding to the Identity store in the appropriate profile switch in the Variable section
Choose the file format (tagged or untagged) that represents the data to be imported. Depending on your selection, you’ll need to have additional information in the attribute configuration file (for a tagged file) or additional information supplied in the set of synchronized attributes (for an untagged file).
Select the search parameters to be used to get an appropriate search result that is used for matching the entries.
Select the entries that should never be deleted.
Decide whether entries should be deleted or whether such entries simply should be marked as deleted.
Select to search with all relevant attributes, or to search with just the distinguished name and perform another read operation for the attributes whenever they are needed (for example, before a modify operation can be performed).
Create the mapping procedures by:
- defining the mapping for each attributes
- writing Tcl code to perform the mapping

Use the mapping procedure scripts supplied with DirX Identity as templates.

Export to an LDIF Content File

This example synchronization template exports the contents of the Identity store to an LDIF-formatted file.The example synchronization template runs under the following assumptions:

The Identity store setup is the sample PQR database starting at /O=PQR
The PQR database contains entries
The meta controller uses the default LDAP attribute names supplied with DirX Identity

Files

This synchronization template uses the following files and Tcl scripts:

Attribute Configuration Files	Description
l-ldifattr.cfg	LDIF attribute information (target)
ldapattr.cfg	LDAP attribute information (source)
Data Files	Description
export.data	LDIF file created by the export process
Synchronization Profile Scripts	Description
common.tcl	Control logic section. Contains utility functions that are common to all of the synchronization templates.
export.tcl	Control logic. Exports data from the Identity store using one global search.
map.l-export.ldif.tcl	Mapping section. Maps LDAP entries to LDIF syntax.
l-export.ldif.tcl	Variable section. This is the user-callable Tcl script to run the export operation. The script calls export.tcl

Attribute Configuration Files

Description

l-ldifattr.cfg

LDIF attribute information (target)

ldapattr.cfg

LDAP attribute information (source)

Data Files

Description

export.data

LDIF file created by the export process

Synchronization Profile Scripts

Description

common.tcl

Control logic section. Contains utility functions that are common to all of the synchronization templates.

export.tcl

Control logic. Exports data from the Identity store using one global search.

map.l-export.ldif.tcl

Mapping section. Maps LDAP entries to LDIF syntax.

l-export.ldif.tcl

Variable section. This is the user-callable Tcl script to run the export operation. The script calls export.tcl

Synchronization Profile Structure

The following sections describe the contents and design of this example synchronization profile.

Variable Section Settings

The Variable section of the example synchronization profile (see the file l-export.ldif.tcl) provides the following information:

Profile switches that configure the operation of the synchronization profile
The names of the mapping procedures defined in the mapping section

The following table describes the profile switches.

Name	Description
home_dir	The home directory in which the synchronization profile Tcl scripts are located
debug_trace	Controls the output of source and target Tcl variables. Possible values are:* 0* - Do not output 1 - Output to standard out (the display)* 2* - Output to the meta controller trace file
trace_file	The name of the meta controller trace file
trace_level	The trace level to be used. Possible values are:* 1-Perform an error trace (only trace failed operations) 2-Perform a full trace (trace all operations) 3*-Perform a full trace only on operations that are actually performed
agent_attr_file	The name of the Identity agent attribute configuration file.
x500_attr_file	The name of the Identity store attribute configuration file.
dump_file	The name of the export data file to be created or to be appended (depends on the file_mode switch).
file_attr_list	The attributes to be synchronized in the export data file
file_format	The data format to use for the generated export data file. Possible values are TAGGED and UNTAGGED.
file_mode	The mode to write to the export data file (overwrite or append).
conn_type	The type of the connection to the Identity store (LDAP).
x500_attr_list	The attributes to be synchronized from the Identity store.
user_name	User name parameter for the obj bind operation.
user_pwd	User password parameter for the obj bind operation.
dsa_name	The name of the Identity store as defined in the directory client configuration file (dirxcl.cfg).
server_address	Identity store address (LDAP server DNS name or IP address and port number) for the obj bind operation.
protocol	The protocol to access the server for the obj bind operation. Possible values are LDAPv2 and LDAPv3. See the obj bind operation.
base_obj	Search base parameter for the obj search operation.
subset	Search scope parameter for the obj search operation.
filter	Search filter parameter for the obj search operation
sort_key	Sort key parameter for the meta sortresult operation. Possible values as ASC and DESC. See the description of the meta sortresult operation in the meta object section.
sort_order	Sort order parameter for the meta sortresult operation. Possible value is DDN. See the description of the meta sortresult operation in the meta object section.
sorted_list	Controls whether the export data file is sorted (TRUE) or not (FALSE)
perform_read	Controls whether the meta controller is to read all attributes from the Identity store during the initial search (FALSE) or with an additional read operation (TRUE)
_localcode	The code set in which the data to be processed is encoded. Possible values are PC850 or LATIN-1.

Name

Description

home_dir

The home directory in which the synchronization profile Tcl scripts are located

debug_trace

Controls the output of source and target Tcl variables. Possible values are:*
0* - Do not output
1 - Output to standard out (the display)*
2* - Output to the meta controller trace file

trace_file

The name of the meta controller trace file

trace_level

The trace level to be used. Possible values are:*
1*-Perform an error trace (only trace failed operations)*
2*-Perform a full trace (trace all operations)*
3*-Perform a full trace only on operations that are actually performed

agent_attr_file

The name of the Identity agent attribute configuration file.

x500_attr_file

The name of the Identity store attribute configuration file.

dump_file

The name of the export data file to be created or to be appended (depends on the file_mode switch).

file_attr_list

The attributes to be synchronized in the export data file

file_format

The data format to use for the generated export data file. Possible values are TAGGED and UNTAGGED.

file_mode

The mode to write to the export data file (overwrite or append).

conn_type

The type of the connection to the Identity store (LDAP).

x500_attr_list

The attributes to be synchronized from the Identity store.

user_name

User name parameter for the obj bind operation.

user_pwd

User password parameter for the obj bind operation.

dsa_name

The name of the Identity store as defined in the directory client configuration file (dirxcl.cfg).

server_address

Identity store address (LDAP server DNS name or IP address and port number) for the obj bind operation.

protocol

The protocol to access the server for the obj bind operation. Possible values are LDAPv2 and LDAPv3. See the obj bind operation.

base_obj

Search base parameter for the obj search operation.

subset

Search scope parameter for the obj search operation.

filter

Search filter parameter for the obj search operation

sort_key

Sort key parameter for the meta sortresult operation. Possible values as ASC and DESC. See the description of the meta sortresult operation in the meta object section.

sort_order

Sort order parameter for the meta sortresult operation. Possible value is DDN. See the description of the meta sortresult operation in the meta object section.

sorted_list

Controls whether the export data file is sorted (TRUE) or not (FALSE)

perform_read

Controls whether the meta controller is to read all attributes from the Identity store during the initial search (FALSE) or with an additional read operation (TRUE)

_localcode

The code set in which the data to be processed is encoded. Possible values are PC850 or LATIN-1.

Mapping Section Procedures

For LDAP access to the Identity store, the main purpose of the mapping section of the example synchronization profile (see the file map.l-export.ldif.tcl) is to assign attribute values from objects to attribute values in LDIF records. This is a simple one-to-one mapping.

Control Logic

The control logic supplied in the example synchronization profile has the following characteristics:

Exports all entries in a Identity store subtree (subject to the specified search filter) to a flat file
Processes Identity store entries individually
Sorts the entries in the generated export data file (if the sorted_list profile switch is set to TRUE)

Customizing This Synchronization Template

Ensure that its control logic matches your export synchronization needs
Develop attribute configuration files for the source and target directory (one each). You can use the attribute configuration files supplied with DirX Identity as templates, or create your own.
Choose the specific set of attributes that you want to synchronize, for the source directory and for the target directory
Decide on the name of the export data file to be generated and supply it in the appropriate profile switch in the Variable section
Supply your credentials for binding to the Identity store in the appropriate profile switch in the Variable section
Select the search parameters that will generate an appropriate search result
Choose the file format (tagged or untagged) that represents the data to be exported. Depending on your selection, you’ll need to have additional information in the attribute configuration file (for a tagged file) or additional information supplied in the set of synchronized attributes (for an untagged file).
Create the mapping procedures by:
- defining the mapping for each attributes
- writing Tcl code to perform the mapping
Use the mapping procedure scripts supplied with DirX Identity as templates.
Decide whether you want the generated export file to be sorted or not, and set the sorted_list profile switch in the Variable section appropriately