1 Introduction
Populating an IBM Lotus Connections Profiles database with user data from a Lightweight Directory Access Protocol (LDAP) server is a key task when you are deploying the Profiles feature. To accomplish this in previous Connections releases, you had to configure property files and run scripts manually, making it one of the most painful tasks in the installation process.
Thankfully, Lotus Connections 2.0 introduces a robust new tool – the Profiles population wizard. This new wizard replaces the tedious manual steps that were required in previous releases and provides a user-friendly and convenient way to populate the Profiles database.
To get the most from this paper, you should have a good understanding of LDAP and a general understanding of databases and SSL. In addition, you should be familiar with the user data in the LDAP directory in your organization.
1.1 Architectural overview
Let’s begin with an illustration of the relevant architecture; that is, the runtime topology of the Connections Profiles population wizard (see figure 1).
Figure 1. Runtime topology
2 Preparing the population
Before running the population wizard, you must complete the following steps:
1. Prepare a database server, creating a Connections 2.0 Profiles database. Refer to
IBM Lotus Connections 2.0 information center/Creating the feature databases for more details.
2. Install IBM Tivoli® Directory Integrator (TDI) v6.1.1 + FP3 + IF0008 on a host system. For performance reasons, it’s recommended that the Profiles database resides on the same server as TDI, but it’s not necessary. The Profiles population wizard and TDI must, however, be located on the same host.
NOTE: AIX is not an offically supported platform for the Profiles population wizard, so if the database is on an AIX server, you should not install TDI on the database server.
3. Copy the Lotus Connections 2 Wizards directory to the host system on which TDI is installed.
4. Copy the correct JDBC driver to the host system. If you are using SQL Server, download the SQL Server 2005 JDBC 1.1 driver from the Microsoft® Web site.
5. Ensure that an LDAP directory with user data is available and, optionally, enable SSL on the LDAP server if you want to populate the user data with SSL enabled.
6. Ensure that the TDI host can connect to the Profiles database and to the LDAP server at the same time.
3 Using the Profiles population wizard to populate user data
In this detailed walk-through of the wizard, we use the following environment:
LDAP server: Tivoli Directory Server 6.1, with SSL enabled
Database server: DB2® Universal Database™ 9.1.4 (and where an empty Profiles database has already been created)
Host to run the wizard: Tivoli Directory Integrator 6.1.1, plus all necessary program files to run the wizard and the correct JDBC driver.
3.1 Steps to populate the Profiles database
To populate the Profiles database with user data from the LDAP server, complete the following steps:
1. Run the script file to launch the wizard under the Wizards directory, using the appropriate command:
Windows®: populationWizard.bat
Linux®: ./populationWizard.sh
2. Click Next on the Welcome page.
3. Optional: Select “Default settings” or “Last successful configuration settings” and
Click
Next.
NOTE: The panel shown in figure 2 will display if the wizard has run previously.
Figure 2. Configuration Settings
4. Specify the correct TDI install location and Click Next.
NOTE: If the TDI cannot be found at the default location, the panel in figure 3 will display.
Figure 3. Unable to locate TDI
5. Select the Profiles database type and
Click
Next. Three types of supported databases are listed:
DB2 Universal Database
Oracle Enterprise Edition
SQL Server Enterprise Edition
6. Specify the following properties of the Profiles database and
click
Next:
Host name: Host name or IP address of the system that hosts the database
Port: The communications port for connecting to the database. Add a new port number or use one of the following default port numbers:
DB2: 50000
Oracle: 1521
SQLServer: 1433
Database Name: The default name of the database is PEOPLEDB.
JDBC driver library path: The JDBC driver must be prepared on the host machine. You can input the driver’s path here, and the wizard will copy it to the correct directory.
User ID
Password
7. Specify the following LDAP server information and click Next:
LDAP server name: Host name or IP address of the LDAP server that contains the user data
LDAP server port: The default port is 389. When SSL is enabled, the default port is 636.
Use SSL communication: Select this check box if you want to populate data from the LDAP server via SSL
8. Optional: Specify keystore properties for an SSL connection and
click Next. The panel in figure 4 displays, in which you specify the following:
Trusted keystore file: The path of the keystore file that is used to store certificates for a trusted LDAP server. You must prepare the keystore file yourself. The wizard does not help to create one.
Keystore password
Keystore type (Two keystore types are now supported: JKS and PKCS12).
Figure 4. Keystore properties for SSL Connection
9. If there is no certificate for the target LDAP server in the trusted keystore file, a security warning dialog will pop up (see figure 5). Click the Accept permanently button to continue. The wizard will save the certificate to the trusted keystore file.
If you click Do not accept, the wizard cannot communicate with the LDAP server via SSL. In this case, you must go back to the previous step and deselect the Use SSL communication check box. Alternatively, you can click Cancel to cancel the population wizard.
Figure 5. Certificate security warning
10. Specify the LDAP server admin and password properties, and then click Next:
LDAP login name
LDAP login password
NOTE: The Profiles population wizard does not support anonymous binding for LDAP. To populate the Profiles database with anonymous binding, you must do it manually.
11. Specify LDAP user search base and filter properties (see figure 6):
LDAP user search base: The search scope of the wizard can only be a sub-tree of the target LDAP. The search base is the root of the sub-tree that will be searched. If multiple LDAP directories or multiple sub-trees of one LDAP directory are used, the wizard must be run multiple times.
LDAP user search filter: The search filter is used to collect only those users who satisfy certain criteria. The default value of the search filter, including objectclass, is the same for different types of LDAP. You can modify it according to your practical requirement.
Below are the filters typically used based on the native setup of the directory. It is actually Lotus Domino® and Microsoft Active Directory that have specific objectclasses to use:
Microsoft Active Directory and Active Directory Application Mode:
source_ldap_search_filter=(&(sAMAccountName=*)(objectclass=user))
IBM Lotus Domino:
source_ldap_search_filter=(&(uid=*)(objectclass=dominoPerson))
Sun Java™ System Directory Server:
source_ldap_search_filter=(&(uid=*)(objectclass=inetOrgPerson))
Novell eDirectory:
source_ldap_search_filter=(&(uid=*)(objectclass=inetOrgPerson))
IBM Tivoli Directory Server:
source_ldap_search_filter=(&(uid=*)(objectclass=inetOrgPerson))
Figure 6. LDAP user search base and filter properties
12. Map LDAP attributes to Profiles database fields (see figure 7), where
The first column lists all available database columns that are used to keep employee information.
The second column specifies which LDAP attribute or JS function is mapped to the database field in the same row.
During the data population, for each user in LDAP, TDI creates a row in the database, gets the value of the LDAP attribute or JS function, and updates the value in the corresponding column in the database. If you need to change the LDAP attribute mapping, you can choose the LDAP attribute or JS functions name from the drop-down list.
The third column lists descriptions of corresponding database fields.
The PROF_GUID field identifies the global unique ID of a user. This attribute value is created by the LDAP server and is unique, complex, and never changes. The mapping of the PROF_GUID property must be handled differently depending on the LDAP server you are using; happily, the Population Wizard provides the correct value by default according to the type of LDAP server. Refer to
Lotus Connections 2.0 information center/Mapping fields manually for more details.
Figure 7. Mapping the Profiles database
13. To choose additional LDAP attributes, click the LDAP attributes in the drop-down list in the second column; the LDAP Attributes dialog displays (see figure 8).
In general, there are so many LDAP attributes that it may be hard to find the one you want. In this case, you can manually edit the corresponding default mapping file first, according to the LDAP server you use. Then run Profiles Population Wizard, which will load the attribute you input in the default mapping file as the default mapping value.
All default mapping files are located in:
Windows: Wizards\TDIPopulation
Linux: ./ Wizards/TDIPopulation
They are named as follows
Microsoft Active Directory
defaultMapping_ad.properties
Microsoft Active Directory Application Mode
defaultMapping_adam.properties
IBM Lotus Domino
defaultMapping_domino.properties
Sun Java System Directory Server
defaultMapping_sun.properties
Novell eDirectory
defaultMapping_nds.properties
IBM Tivoli Directory Server
defaultMapping_tivoli.properties
Figure 8. Additional LDAP Attributes
14. You also can choose more JavaScript functions in the JavaScript Functions dialog by clicking JavaScript functions in the drop-down list of the second column (see figure 9); click Next.
Figure 9. Choose more JavaScript functions
15. Now choose any optional database tasks that you want to perform (see figure 10).
Figure 10. Choose optional tasks
As you can see from the figure, there are a total of six optional tasks; the first five are fields in which you must enter the corresponding .csv file with relevant information in the required format. Profiles population wizard provides an isocc.csv file for the first optional task, Countries, but the user can opt to use another isocc.csv file instead of the one provided by the wizard.
The isocc.csv files include us;United States and information of other countries. You can edit the profiles-config.xml file to specify whether you want to display the code or the value, where “us” is the country code, and United States is the value.
Fill
Countries: The isocc.csv file is located in:
Windows: Wizards\TDIPopulation\TDISOL
Linux: ./Wizards/TDIPopulation/TDISOL
This optional task adds data in isocc.csv into the table EMPINST.COUNTRY of the database PEOPLEDB.
If the LDAP server provides only the code of a country, the code will be used to get the country name from table EMPINST.COUNTRY.
Fill
Departments: You should prepare the deptinfo.csv file. This task adds data in depinfo.csv into table EMPINST.DEPARTMENT of database PEOPLEDB.
Fill
Organization: You should prepare the orginfo.csv file. This task adds data in orginfo.csv into table EMPINST.ORGANIZATION of database PEOPLEDB.
Fill
Employee types: You should prepare the emptype.csv file. This task adds data in isocc.csv into table EMPINST.EMP_TYPE of database PEOPLEDB.
Fill
Work locations: You should prepare the workloc.csv file. This task adds data in isocc.csv into table EMPINST.WORKLOC of database PEOPLEDB.
The other .csv files are in the same format.
Mark the profiles of each manager? This optional task adds manager data to relevant profiles. That data is referenced when displaying profile data and is also used to generate report-to chains for users. The Mark manager mapping task for Profiles maps this data as follows:
A “Y” or “N” attribute is assigned to an employee to indicate whether the employee is listed as a manager of other employees. The reason to run this task is if the PROF_IS_MANAGER field in an employee record cannot be determined from LDAP or by means of a function. The task iterates through all the employee records and sets the PROF_IS_MANAGER to “Y” for any referenced managers.
16. Review the configuration summary and click Next. Make sure the values that you entered on the previous panels are correct. If you want to make any changes, click Back to return to the appropriate panel. If the values on the installation summary screen are correct, click Configure to begin populating the Profiles database.
17. Finally, check the result message on the Population Completion Summary panel (see figure 11). To open the log file, click View Log. Click Finish to exit the wizard.
Figure 11. Summary result message
3.2 Check the user data in Profiles database
The Profiles population wizard cannot alert you of all problems, so after population you should check the user data in the Profiles database to detect implicit problems as early as possible. All user data is stored in table EMPINST.EMPLOYEE of database PEOPLEDB.
If you can answer “yes” to the following two questions, after you check the user data, then population is successful:
Is all necessary user data populated into the Profiles database?
Are the values of every user data correct?
4 Troubleshooting
Let’s now identify and troubleshoot some issues you may encounter with the wizard.
4.1 Using error messages to troubleshoot
Error messages explain the cause of most problems that might occur with the wizard and how to fix them. For example, in figure 12, the error message indicates that the database password is missing. Obviously, to solve the problem, simply click OK to close the message box, enter the correct password, and click Next.
Figure 12. Example error message
4.2 Using log files to troubleshoot
Since error messages cannot solve some of the more complex problems, you can use the log files to help in troubleshooting. There are four log files for the Profiles population wizard, described as follows:
4.2.1 lcwizard_0.log
This log file is located in:
Windows: C:\Documents and Settings\
\lcWizard\log\
Linux: ./home//lcWizard/log/
Historical logs are saved as lcwizard_n.log
By default the wizard log level is INFO, and you can add –Dloglevel=ALL in the script file populationWizard.bat/sh to get all available log information:
Windows: populationWizard.bat
start javaw –Dloglevel=ALL -Djava.library.path=lib/linkfile com.ibm.lconn.wizard.launcher.TDIPopulationLauncher %*
java –Dloglevel=ALL -Djava.library.path=lib/linkfile com.ibm.lconn.wizard.launcher.TDIPopulationLauncher %*
Linux: populationWizard.sh
${JAVA_CMD} –Dloglevel=ALL -Djava.library.path=lib/linkfile com.ibm.lconn.wizard.launcher.TDIPopulationLauncher $@
4.2.2 tdi_yyyymmdd_hhmmss.log
This file is located in:
Windows: C:\Documents and Settings\\lcWizard\log\tdi\
Linux: ./home//lcWizard/log/tdi/
It is named according to the following naming convention: tdi_yyyymmdd_hhmmss.log. For example, tdi_20080519_160923.log is a real name.
4.2.3 ibmdi.log
This file is located in:
Windows: Wizards\TDIPopulation\TDISOL\logs
Linux: ./ Wizards/TDIPopulation/TDISOL/logs
By default, ibmdi.log is disabled. To enable it, set source_ldap_debug=true in profiles_tdi.properties, which is located in:
Windows: Wizards\TDIPopulation\TDISOL
Linux: ./ Wizards/TDIPopulation/TDISOL
4.2.4 PopulateDBFromDNFile.log
This file is located in:
Windows: Wizards\TDIPopulation\TDISOL\logs
Linux: ./ Wizards/TDIPopulation/TDISOL/logs
If you encounter problems before clicking Configure on the Profiles Population Configuration Summary panel, you can only find useful information in the lcwizard_0.log file.
The tdi_yyyymmdd_hhmmss.log, ibmdi.log, and PopulateDBFromDNFile.log files are not created until you click Configure on the Profiles Population Configuration Summary panel. To troubleshoot problems in the configuration process, refer to these three log files.
Clicking the View Log button on the Population Completion Summary panel opens the tdi_yyyymmdd_hhmmss.log file.
For example, from the error message in figure 13, you cannot tell which is incorrect, search base or search filter, and the expression of search filter is too complex to figure out the error.
Figure 13. Example ambiguous error message
If you open lcwizard_0.log, you will find the following fragment at the end. The red bold text explains the cause; namely, that the parenthesis is unbalanced in the search filter expression:
[SEVERE] Exception while getting ObjectClass's Definition.
[06/25/08 16:42:34.171 CST] com.ibm.lconn.wizard.common.validator.SearchFilterValidator validate
[SEVERE] Cannot connect to LDAP server.
com.ibm.lconn.wizard.common.exceptions.LdapOperationException: Can not get objectclasses from LDAP server ldap://9.186.10.212:389.
at com.ibm.lconn.wizard.tdipopulate.ldap.impl.LdapControl.hasSearchResult(Unknown Source)
at com.ibm.lconn.wizard.common.validator.SearchFilterValidator.validate(Unknown Source)
at com.ibm.lconn.wizard.common.interfaces.DefaultPageController.validate(Unknown Source)
at com.ibm.lconn.wizard.common.interfaces.DefaultPageController.processNext(Unknown Source)
at com.ibm.lconn.wizard.common.interfaces.DefaultPageController.performAction(Unknown Source)
at com.ibm.lconn.wizard.common.interfaces.TDIPopulatePageController.performAction(Unknown Source)
at com.ibm.lconn.wizard.common.ui.LCWizard.getNextPage(Unknown Source)
at com.ibm.lconn.wizard.common.ui.LCWizardDialog$1.run(Unknown Source)
at org.eclipse.swt.custom.BusyIndicator.showWhile(BusyIndicator.java:67)
at com.ibm.lconn.wizard.common.ui.LCWizardDialog.nextPressed(Unknown Source)
at com.ibm.lconn.wizard.common.ui.LCWizardDialog.finishPressed(Unknown Source)
at com.ibm.lconn.wizard.common.ui.LCWizardDialog.buttonPressed(Unknown Source)
at org.eclipse.jface.dialogs.Dialog$2.widgetSelected(Dialog.java:616)
at org.eclipse.swt.widgets.TypedListener.handleEvent(TypedListener.java:227)
at org.eclipse.swt.widgets.EventTable.sendEvent(EventTable.java:66)
at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:938)
at org.eclipse.swt.widgets.Display.runDeferredEvents(Display.java:3682)
at org.eclipse.swt.widgets.Display.readAndDispatch(Display.java:3293)
at org.eclipse.jface.window.Window.runEventLoop(Window.java:820)
at org.eclipse.jface.window.Window.open(Window.java:796)
at com.ibm.lconn.wizard.launcher.TDIPopulationLauncher.main(Unknown Source)
Caused by: javax.naming.directory.InvalidSearchFilterException: Unbalanced parenthesis; remaining name 'DC=IBM,DC=COM'
at com.sun.jndi.ldap.Filter.findRightParen(Filter.java:494)
at com.sun.jndi.ldap.Filter.encodeComplexFilter(Filter.java:456)
at com.sun.jndi.ldap.Filter.encodeFilter(Filter.java:102)
at com.sun.jndi.ldap.Filter.encodeFilterString(Filter.java:70)
at com.sun.jndi.ldap.LdapClient.search(LdapClient.java:535)
at com.sun.jndi.ldap.LdapCtx.doSearch(LdapCtx.java:1959)
at com.sun.jndi.ldap.LdapCtx.searchAux(LdapCtx.java:1821)
at com.sun.jndi.ldap.LdapCtx.c_search(LdapCtx.java:1746)
at com.sun.jndi.toolkit.ctx.ComponentDirContext.p_search(ComponentDirContext.java:383)
at com.sun.jndi.toolkit.ctx.PartialCompositeDirContext.search(PartialCompositeDirContext.java:353)
at com.sun.jndi.toolkit.ctx.PartialCompositeDirContext.search(PartialCompositeDirContext.java:336)
at javax.naming.directory.InitialDirContext.search(InitialDirContext.java:259)
... 21 more
4.3 Troubleshooting the most typical (and difficult) problems
There are some common problems for which you cannot glean sufficient clues from either the error messages or log files. Here’s how to troubleshoot these issues:
Problem: Communicate error with Profiles database.
Ensure that the
Host can connect to the database server.
Target Profiles database is created on the database server.
Properties are correct.
Problem: Cannot connect to the LDAP server via SSL.
Ensure that the
Host can connect to the LDAP server.
SSL service of the target LDAP server is enabled.
Port configured on the LDAP Server Connection panel is correct.
Trusted keystore file is stored in the specified location.
Keystore password is correct.
Keystore type is JKS or PKCS12, and the correct one is chosen.
If all the above are correct, check the system time of the host. If the time is not correct, the certificate of the target LDAP server might be treated as invalid.
Problem: Population failed because of problems with JDBC connector when Microsoft SQL Server 2005 is used.
Ensure that IBM Tivoli Directory Integrator v6.1.1 + FP3 + IF0008 is installed and then retry.
Problem: Population failed because of other problems.
Here are two tips that may be helpful:
(1) Populate with a simple set of mappings before going to the complex final list. If it is successful, it means that there is something wrong with the original complex mappings.
(2) If the collect.dns file was generated and the content is as expected, the configuration on and before Base Distinguish Name and Filter for Searches panel should be correct; thus, you can look to other configuration panels for the issue. The collect.dns is located in:
Windows: Wizards\TDIPopulation\TDISOL\
Linux: ./ Wizards/TDIPopulation/TDISOL/
Problem: After population, some necessary user data cannot be found in the Profiles database.
Ensure that the
Correct LDAP server is connected.
LDAP admin user is used on the LDAP Authentication Properties panel.
LDAP search base is correct.
LDAP search filter is correct.
Also, recreate the Profiles database and then run the wizard again with the correct configuration.
Problem: After population, some values of user data in the Profiles database are incorrect.
Ensure that LDAP attributes are mapped to Profiles database fields correctly on the Profiles Database Mapping panel.
Recreate the Profiles database and then run the wizard again with the correct mapping. For example, in the WebSphere Application Server admin console, do the following:
Navigate to Users and Groups > Manage Users.
On the Manage Users page, fill in the search condition and click Search.
Values of field PROF_UID in table EMPINST.EMPLOYEE of database PEOPLEDB should be the same as values of User ID in the search result, as shown in figure 14.
Figure 14. User ID values in the search result
If there are any differences, correct the mapping between PROF_UID and LDAP attributes and run the population again.
5 Conclusion
The IBM Lotus Connections 2.0 Profiles population wizard is a new tool that replaces tedious manual steps in previous releases, providing a user-friendly and convenient way to populate the Profiles database. In this article, we demonstrated how to use the Profiles population wizard and how to troubleshoot many common errors.
6 Resources
7 About the authors
Xie Ling
Software Engineer
IBM China Software Development Lab
Shanghai, China
Xie Ling is a Software Engineer in the IBM China Software Development Lab located in Shanghai. He earned a Masters degree in Computer Application Technology from Zhejiang University. Ling has been working on Lotus Connections FVT since August 2007, before which he worked as a developer on IBM Workplace for Business Control and Reporting.
Cheng Ying Ying
Software Engineer
IBM China Software Development Lab
Shanghai, China
Cheng Ying Ying is a Software Engineer in the IBM China Software Development Lab located in Shanghai. She has been working on Lotus Connections FVT since August 2007. Previously, she worked with the Forms Central Team, where she developed and tested IBM Workplace Forms and relevant tools.
8 Acknowledgements
We want to thank Carol Zimmet for reviewing this paper and helping guide us forward with the paper’s plan; Paddy Barrett for modifying this article three times and providing good suggestions in the early phase; and Kai Wei, Staci O’Neil, Jackie Ferguson, and Xiaofeng Yu for reviewing this article and providing their valuable feedback.
Trademarks