Introduction

The intent of this article is to give you an insight into the real-world scenarios occurring with IBM® Connections 3.0.1 with respect to IBM Tivoli® Directory Integrator (TDI) scripts and user population. It is assumed that the reader is familiar with basic concepts of TDI and its corresponding usage in IBM Connections Profiles population activity.

For details on setting up TDI and IBM Connections 3.0.1, refer to the IBM Connections 3.0.1 product documentation topic, “Configuring Tivoli Directory Integrator.”

Scenarios

TDI is used along with IBM Connections to populate user data from varied sources, primarily Lightweight Directory Access Protocol (LDAP). The pre-packaged scripts with IBM Connections use the properties files in the TDISOL directory.

Populating users from a Domino group

Scenario: Organization X wants to run an Idea Jam event, using IBM Connections for business focus in the upcoming quarter. The participants are generally senior management and VP’s from different organizational departments and countries. Other users are not able to use IBM Connections.

Requirements: Only a select group of people are to be populated in IBM Connections, but these people do not belong to a particular directory tree. So instead, organization X has created an IBM Lotus® Domino® group with the participants as members of this group. All members of this group must be populated to IBM Connections manually.

Solution: IBM Connections uses a combination of two scripts to populate users manually.

• collect_dns.bat/sh: This file collects the Distinguished Names (DNs) of all users who are returned from LDAP based on the search filter set in profiles_tdi.properties and writes the output as a list in collect.dns.

• populate_from_dn_file.bat: This file takes the collect.dns file as input and populates users whose DN is in the collect.dns to the Profiles database.

NOTE: Make sure to set the LDAP and database details correctly in profiles_tdi.properties before continuing with this solution.

To populate users from a Domino group we build a simple assembly line that fetches the users of a particular group and outputs their DN’s into a file that can then be used as input to run the usual populate_from_dn_file.bat task to populate the users:

1. Follow the steps in the product documentation topic, “Setting up your development environment,” to set up a TDI development environment.
2. In the TDI Configuration Editor, create a new AssemblyLine and provide a suitable name, for example, DominoMembers (see figure 1).

Figure 1. DominoMembers AssemblyLine



3. In the Feed section, add an LDAPConnector and provide the details to connect to Domino LDAP as shown in figure 2.

Figure 2. Add LDAPConnector



4. If you have multiple groups and want to populate from a particular group named demogroup, the search filter above can be set as
5. Under the Input Map tab, add the member attribute and map it to the member (see figure 4).

Figure 4. Add member attribute



6. Next we add a connector of type Attribute Value Loop. Set the attribute that contains multiple values as member, and set the temporary attribute that holds the value of the member during each loop iteration as loopmember (see figure 5).

Figure 5. Attribute Value Loop connector



7. Inside the For-EACH Attribute: AttributeValueLoop, add a file system connector that will write the list of members to an output file called collect.dns (see figure 6).

Figure 6. Specify output file



8. Under the Output Map tab, select the loopmember attribute and write it to a destination (see figure 7).

Figure 7. Write loopmember attribute to destination



Figure 8. Data flows



9. Save and Run the AssemblyLine. This fetches the members of the particular Domino group and writes them into the output file (see figure 9).

Figure 9. Output file



10. Finally, run the populate_from_dn_file.bat to then populate these users into IBM Connections.

Populating users from multiple directories

Scenario: Organization X has its users classified in LDAP according to their countries. Users from five different countries are to be populated and then synchronized periodically. If correct settings are not used in the profiles_tdi.properties file, then it may lead to deletion or inactivation or to users belonging to a particular LDAP branch.

Requirements: Users should be populated from the LDAP branch that has users under their respective country; for example, users are in the following branches:
The intent is to populate and sync all the users from the above countries periodically while avoiding any accidental deletion or inactivation of users.

Solution: Since version 3.0, IBM Connections uses a set of properties that determines what occurs when the population / sync script does not find a user who is in the Profiles database in the LDAP. For a typical scenario as mentioned above we must have the users synched from all five LDAP branches.

To populate users from five LDAP branches containing users from five countries, follow these steps:

1. In the profiles_tdi.properties file, set the properties for the LDAP and Database connectivity as mentioned in product documentation topic, “Tivoli Directory Integrator properties.”
2. For the field source_ldap_search_base, set this value to the value for the LDAP branch for the first country on the list, that is, source_ldap_search_base= o=ibm,c=IN.
3. Run the collect_dns.bat followed by populate_from_dn_file.bat scripts to populate all users under the “IN” branch of LDAP.
4. Change the source_ldap_search_base property for each LDAP branch, and run the respective population tasks.
5. Other important properties to check are:

where:

• sync_store_source_url ensures that the source URL for each user is updated in the peopleDB. This is essential for synchronizing the users.

• sync_source_url_enforce ensures that any sync operation will be performed only on those users whose source ldap url matches the value set in the profiles_tdi.properties while executing sync command.

• sync_source_url_override: Setting this property to false ensures that the source url is not overwritten in users' records when the sync script is running.

These settings ensure that users are synchronized with their respective LDAP branch and, at the same time, users from other LDAP branches are unaffected.

6. Set the sync_delete_or_inactivate property to an appropriate value based on your business requirements. For example, set it to delete/inactivate, if you want to delete users who are no longer found in the LDAP, or you want to keep the users but change their status to inactivated.

Synchronizing users from multiple directories
To synchronize the users who have been populated in the previous steps from five LDAP branches, you must run the sync_all_dns.bat five times, changing the source_ldap_search_base for each run to the appropriate base value of your LDAP branch.

The following steps explain how to use the attached sample script, SyncMultipleDN.sh, to run a synchronization task across multiple directories:

1. In the profiles_tdi.properties file, set the properties for the LDAP and Database connectivity per the Tivoli Directory Integrator properties” product documentation topic.
2. If you have populated users from five LDAP branches, as mentioned in previous section, create five copies of the profiles_tdi.properties file.
3. Name these file as profiles_tdi_1.properties, profiles_tdi_2.properties, and so on.
4. In each properties file set the value of source_ldap_search_base to the respective ldap DN that is to be synchronized.
5. Copy the attached SyncMultipleDN.sh script into the TDISOL directory.
6. Execute the script from a terminal, entering a suitable value when the script prompts for the number of iterations to be performed; for example, for this scenario, enter “5”.

The script backs up the original profile_tdi.properties file and then executes the sync_all_dns.sh task five times, to update the users from all five directory branches. The script can then be scheduled daily or weekly, per your requirements.

Loading photos from files with inconsistent data

Scenario: Organization X has its users populated from LDAP and has a repository of employee photos submitted to HR at the time of their joining the organization. Now we need to upload the photos corresponding to all employees in IBM Connections, using the load_photos_from_files.bat task.

The problem is that, since the HR repository is not updated as per updates to the corporate LDAP, the HR data also contains photos of employees who have left the organization and no longer exist in LDAP, and the load_photos_from_files.bat task fails on encountering such users and exits.

Requirement: We need to upload user photos against their profiles in IBM Connections. Since the photo repository also contains obsolete records of employees who already left the organization, we need the TDI task to populate all users who currently exist in the LDAP.

Solution: The load_photos_from_files.bat script quits if it does not find the user in the LDAP, so we must modify the logic on error to continue the operation instead of terminating the script operation.

The load_photos_from_files script when opened in the TDI Configuration Editor looks like that highlighted in red in figure 10.

Figure 10. Action on iterator error



For the iteration to continue working upon encountering an error, we must make a minor modification to the read_entries connector in the load_photos_from_files AssemblyLine, as shown in figure 11. The following code (and highlighted in red in the figure) outputs the failed user’s ID to the log file and instructs the iterator to continue iterations despite an error:


Figure 11. Modification to the read_entries connector



This modification enables you to upload photos for thousands that are provided in a folder but are not consistent with the user list in the corporate LDAP.

Population fails for secured connections to LDAP cluster

Scenario: Organization X has a load-balanced cluster of LDAP servers that are accessed uniformly by hitting a single cluster URL, for example, ldap.orgX.com . The connections to the LDAP are secured (i.e., https), and a request to the LDAP may hit any one of the multiple LDAP servers in the backend. In such a scenario, profile population succeeds for a few requests but intermittently fails for a few others.

Requirement: When multiple LDAPs are operating as a load-balanced cluster, the population of users using TDI should complete without any errors, irrespective of the servers being hit. It's important to reiterate here that the LDAP server communication is secured.

Solution: When running TDI scripts packaged with IBM Connections, it is important to determine whether the LDAP server communication is secured or not. If the server communication is secured, we need to import the SSL certificate from the LDAP server to the Java Virtual Machine (JVM) of TDI:

1. Launch the ikeyman from the directory, /<TDI INSTALL DIR>/jvm/jre/bin/ikeyman.
2. Create a new key database of type JKS.
3. Click on Signer Certificates and import the certificates that are extracted from the LDAP server, to add the certificates to the truststore.
4. Modify the JVM location in the /opt/IBM/TDI/TDISOl/TDI/solution.properties file in TDI by providing the correct location and password as shown in figure 12.

Figure 12. TDI trust store properties


where:
5. Follow the steps in the product documentation topic, “Manually populating the Profiles database,” to import user profiles using TDI scripts.

Conclusion

IBM Tivoli Directory Integrator is used extensively with IBM Connections for user profile population. In this article we've discussed some commonly occurring real-world scenarios of profile synchronization.

We have also covered simple solutions to overcome issues and ensure smooth synchronization of user data in large production environments. The attached sample script facilitates the data synchronization effort.

Resources

• developerWorks® article, “Integrating Tivoli Directory Integrator and Lotus Connections”:

http://www.ibm.com/developerworks/tivoli/library/t-tdi-lotus/
• developerWorks white paper, “Understanding IBM Tivoli Directory Integrator for IBM Lotus Connections 3.0: A getting started guide”:

http://www.ibm.com/developerworks/lotus/documentation/connectionstdi/
• developerWorks IBM Connections product page:

http://www.ibm.com/developerworks/lotus/products/connections/

• IBM Connections Forum:

http://www-10.lotus.com/ldd/lcforum.nsf?OpenDatabase

About the author

Chirag Barhate has five years of experience working on IBM Connections at IBM's India Software Labs. As a consultant on collaboration technologies, he has been involved in numerous deployments involving Connections, IBM Lotus Quickr®, IBM Sametime®, and IBM WebSphere® Portal. Chirag is also passionate about enterprise Social Software & Analytics. You can reach him at chirag.barhate@in.ibm.com.