To keep your organization's user data up-to-date, regularly synchronize the Profiles
database with your data sources. Typically, the data source is an LDAP directory. The LDAP directory
might also have extension data in a database table.
About this task
The Profiles database is the repository within IBM®
Connections for information about the users of Connections in your organization. The source of this
information is your organization's LDAP directory or other type of data repository, which is the
master copy. The synchronization process is controlled by properties in the file
profiles_tdi.properties.
Use the sync_all_dns command to transfer changes in your organization's user
data repository to the Profiles database. If you want to keep the Profiles database in a close
synchronized state with your LDAP directory, run this task nightly or at another frequency that
suits you.
During synchronization, the mapping values that are coded in
map_dbrepos_from_source.properties are evaluated to determine which records
need updating. Existing records are updated, and new records are added. Records that cannot be found
are either removed or deactivated, based on configuration settings. If you configure extension
attributes, that information is also compared and synchronized. Because the
sync_all_dns command performs a complete comparison of the search scope with the
Profiles database, be sure to allow sufficient time for it to run.
Note: In some cases you can use either the process_tds_changes command or
the process_ad_changes command instead of the sync_all_dns
command. For more information about using these alternate commands, see Synchronizing IBM
Tivoli Directory Server and Microsoft Active Directory LDAP changes
The sync_all_dns command creates temporary files that are used during the
synchronization process, so you need to have sufficient disk space. Use the
sync_updates_working_directory property to specify the location of the temporary
files. Use the sync_updates_clean_temp_files property to specify whether to
delete or retain the temporary files after synchronization. Retaining the files is useful when you
are troubleshooting a problem.
In addition to the temporary files, the following files in the TDI solution directory record the
changes that were made during synchronization:
- employee.adds
- employee.delete
- employee.error
- employee.skip
- employee.update
When the sync_updates_show_summary_only property is set to true, the files
contain only the records that need to be changed, but no changes are made. For more information
about how the sync_all_dns command works, see Understanding how the
sync_all_dns process works.
Like the other TDI tasks, the sync_all_dns command writes log information to
the log file ibmdi.log in the TDI\logs directory. You can
check the log to see whether the command finishes successfully, and look for error information if
necessary.
Procedure
To synchronize LDAP directory changes with Profiles:
- Use the properties in the following table to control the synchronization process.
Note: The only property that can be used with the process_tds_changes the
process_ad_changes commands is the
perform_deletion_or_inactivate_for_sync property.
| Option |
Description |
|---|
perform_deletion_or_inactivate_for_sync
|
Set this property to true when you want to delete or mark as inactive those
users who are no longer in the LDAP directory.
The sync_all_dns command checks the value of the property and acts using the
following logic:
- If the value is true, look at the sync_delete_or_inactivate
property to determine which action to take.
- If the value is false, perform neither the delete action nor the inactivate
action.
|
sync_delete_or_inactivate
|
Controls what happens to a user record when the delete action is performed. The value must be
either delete or inactivate and is case sensitive. By default, the
property is set to inactivate. The inactive state is propagated to all the other
Connections applications.
This property cannot be used with the process_tds_changes and
process_ad_changes commands.
For information about automating the delete user process, see Using supplied scripts to
delete inactive users based on inactivity length
|
source_ldap_iterate_with_filter
|
Set this property to the name of a JavaScript file that contains the filter code.
Use when the size of the data to be retrieved from LDAP exceeds the search limit of the LDAP or
exceeds the memory capacity of the TDI LDAP connector. For example, if your search parameters would
return 250K records but your LDAP only allows 10K to be returned at a time, you can use this
property.
For more information about how to use this property, see Populating a large user
set.
This property is not configurable when using the population wizard.
|
sync_check_if_remove
|
Specifies the name of an assembly line that verifies the delete operation or the inactivate
operation.
By default, the name of the assembly line is set to
sync_all_dns_check_if_remove. The sync_all_dns_check_if_remove
assembly line looks up the distinguished name of the about-to-be-deleted user in the LDAP directory.
If the user is found, sync_all_dns_check_if_remove returns a status that causes
the main assembly to ignore the delete or inactivate action.
This property is ignored unless the sync_updates_double_check property is set
to true.
For more information about this property, see Customizing the logic used for the delete
operation.
|
| sync_updates_clean_temp_files |
When set to true, temporary files are deleted after the synchronization process
is complete. When set to false, which is the default, the files are not deleted
until the next time that sync_all_dns is run.
|
sync_updates_double_check
|
The default value is false. When set to true, the assembly line
that is defined by the sync_check_if_remove property runs.
|
sync_updates_hash_field
|
This is a key property. This property specifies the field that is used to match a record in the
Profiles database with the corresponding record in the source. The supported fields are
uid, guid, and email. The default is
uid.
It is critical that you choose a field that will not change, so that the match will remain intact
between the source and the Profiles database.
If the value in the field in the source does change, the match will be broken and unintended
actions can occur. For example, the existing database information for this person could be deleted
if the corresponding match in the source is no longer accessible.
If the value of the hash field in the source has changed, you must set this property to a
different field that has not changed, for at least one run of sync_all_dns. For
example, if the value for uid changes in the source, you must set the property to
either guid or email. After one run of
sync_all_dns, you can change the property back to uid.
Note: If the value is guid and you change LDAP providers, you must change the value
to uid or email temporarily because guid is LDAP
specific.
|
sync_updates_hash_partitions
|
Number of partitions to divide the temporary files into. The default of 10 is
sufficient in most cases. If problems develop, you can increase the value. The typical problem is
running out of memory during the update phase.
|
sync_updates_show_summary_only
|
When set to true, this property shows only the records that need to be changed, but does not make
the changes.
|
sync_updates_working_directory
|
The directory where the working files are stored. The path can be relative to the TDI solution
directory or an absolute path. The default value is sync_updates, which is a
relative path.
|
- If you are storing data from multiple LDAP branches or multiple LDAP directories in the same
Profiles database, you must synchronize each LDAP branch or LDAP directory separately. To accomplish
this task, you can set the following properties in the profiles_tdi.properties
file:
Note: These properties can only be used with the sync_all_dns command. They
cannot be used with the process_tds_changes and
process_ad_changes commands.
| Option |
Description |
|---|
sync_source_url_enforce
|
Synchronizes only those records where the stored source URL matches the current source URL. The
current source URL is the concatenation of the source_ldap_url,
source_ldap_search_base, and source_ldap_search_filter
properties. When set to true, it limits the scope of the set of data in the
database, and skips the records that do not match the current source URL. When set to
false, the source URL is ignored if there is no update, and reset if there is an
update. The default value is false.
|
sync_source_url_override
|
This property is effective only when sync_source_url_enforce is true. When
sync_source_url_enforce is true and sync_source_url_override
is false, records where the current source URL and the stored source URL do not
match are skipped.
When sync_source_url_override is true, the records that would have been
skipped are checked for a match of the hash field in the current LDAP branch or LDAP directory. If
there is a match and at least one field needs to be updated, the record is updated, and the source
URL is set to the current value.
This property should be clearly understood before setting it to true. See the last example later
in this document to see it in action.
|
sync_store_source_url
|
Stores the source LDAP URL in the prof_source_url field in the database. Must
be either true or false. The default value is
true. The source LDAP URL is needed to determine the source of the data to
correctly synchronize it when there is more than one LDAP branch or LDAP directory. Even if there is
only one LDAP, it is best to leave this property set to true.
When storing the sync_store_source_url property in the Profiles database, the
data format of prof_source_url in the Profiles database is as follows:
ldap://{hostname}:port/ldap_search_base?ldap_search_filter
|
- Run the sync_all_dns command. The command name is either
sync_all_dns.sh or sync_all_dns.bat, depending on your
operating system.
Note: When the sync_all_dns command runs, a lock file is created in the TDI
solution directory. The lock file prevents others from starting a sync_all_dns
process in the same TDI solution directory. The name of the lock file is
sync_all_dns.lck. The lock file is deleted after the
sync_all_dns command has completed. If the command does not complete, the lock
file is not deleted. You can delete it yourself, or you can run the clearLock.sh
or the clearLock.bat script, located in the TDI solution directory.
Example employee tables
The sample EMPLOYEE table illustrates results from a scenario for the fictional Zeta Bank
company, in which you have pulled users A, B, and C from the Littleton LDAP branch and users X, Y,
and Z from the Westford LDAP branch.
Following the best practice, you have used two TDI solution directories with slightly different
profiles_tdi.properties files. In the following discussion, one of the solution
directories is called ABC, and the other is called
XYZ.
Each of the profiles_tdi.properties files include the following entries:
source_ldap_url=ldap://ldap.zetabank.com:389
source_ldap_search_filter=((objectClass=inetOrgPerson)(uid=*))
sync_store_source_url=true
sync_source_url_enforce=true
sync_source_url_override=false
The ABC/profiles_tdi.properties file, for the Littleton branch, includes the
following entry:
source_ldap_search_base=cn=users,location=littleton,dc=zetabank,dc=com
The XYZ/profiles_tdi.properties file, for the Westford branch, includes the
following entry:
source_ldap_search_base=cn=users,location=westford,dc=zetabank,dc=com
After running collect_dns and populate_from_dn_file in each
of the two TDI solution directories, the EMPLOYEE table contains the following data:
Table 1. Example employee table after running collect_dns and populate_from_dn_file in each TDI
solution directory.| uid |
PROF_SOURCE_URL |
|---|
| A |
ldap://ldap.zetabank.com:389/cn=users,location=littleton,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| B |
ldap://ldap.zetabank.com:389/cn=users,location=littleton,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| C |
ldap://ldap.zetabank.com:389/cn=users,location=littleton,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| X |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| Y |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| Z |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
Notice that the only difference between the values for PROF_SOURCE_URL is the location
parameter.
If you run sync_all_dns in the ABC TDI solution
directory, you get updates for people A, B, and C, but not for people X, Y, and Z because
sync_source_url_enforce is set to true and the PROF_SOURCE_URL for those people
does not match the concatenation of the source_ldap_url,
source_ldap_search_base, and source_ldap_search_filter
properties. Setting sync_source_url_enforce to false deletes the people X, Y, and
Z from the database because they don’t exist in the Littleton branch.
If the people A, B, and C move from Littleton to Waltham, the
ABC/profiles_tdi.properties would then have the following entry for
source_ldap_search_base:
source_ldap_search_base=cn=users,location=waltham,dc=zetabank,dc=com
An update is required because the location value in the PROF_SOURCE_URL column is different than
the location value in ABC/profiles_tdi.properties. To correctly update the
value in PROF_SOURCE_URL, in ABC/profiles_tdi.properties set
sync_source_url_override to true and then run sync_all_dns in
the ABC TDI solution directory. After the command completes, the EMPLOYEE table
contains the following data:
Table 2. Example employee table after running collect_dns in the ABC TDI solution directory.| uid |
PROF_SOURCE_URL |
|---|
| A |
ldap://ldap.zetabank.com:389/cn=users,location=waltham,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| B |
ldap://ldap.zetabank.com:389/cn=users,location=waltham,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| C |
ldap://ldap.zetabank.com:389/cn=users,location=waltham,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| X |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| Y |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |
| Z |
ldap://ldap.zetabank.com:389/cn=users,location=westford,dc=acme,dc=com?((objectClass=inetOrgPerson)(uid=*)) |