Troubleshoot IBM Telephone Directory V5.2

Troubleshoot IBM Telephone Directory V5.2

Find troubleshooting information on the IBM^® Telephone Directory V5.2 application.
Before you begin to troubleshoot problems with the IBM Telephone Directory V5.2 application, answer the following questions to help solve some common problems when using the application:

Are all of the product prerequisites installed? See Verify the prerequisites in the IBM Welcome Page V1.1 topic for more information.

Is your LDAP server started?

Is your IBM Welcome Page application started?

Is your IBM Telephone Directory application started?

Is your application server started?

Is your HTTP server started?

Use the following information if you are still having problems with your application:

Troubleshoot setup

Problem Cause Solution

IBM Business Solutions (5722-BZ1) is not listed when the GO LICPGM command is run for a preinstalled and preconfigured iSeries™ server. IBM Telephone Directory V5.2 is not installed on your server. Install the 5722-BZ1 product.

Troubleshoot authentication

Problem Cause Solution

Log in fails In the application, user IDs and passwords must contain characters that map to the job CCSID that is used by the HTTP server. Otherwise, authentication fails. Make sure that your characters map to the job CCSID that is used by the HTTP server. To determine the job CCSID for the HTTP server, enter WRKACTJOB on a CL command line and select Display job definition attributes. The HTTP server CCSID is determined by the HTTP server defaultFSCCSID directive. For more information, see Notices and limitations.
URL fails or the application does not appear If you did not start the IBM Welcome Page application, the URL fails (http://your.server.name:port/ibm-bizApps/welcome-home.do or http://your.server.name:port/ibm-bizApps/welcome-admin.do). Problems also occur if you start the IBM Welcome Page application but do not start the IBM Telephone Directory application. If the IBM Telephone Directory application is not running, the Welcome Page application does not have links to it. Start the IBM Welcome Page application and the IBM Telephone Directory application.
Requests to the application fail If you used the internal HTTP server included with WebSphere^® Application Server to reference the IBM Telephone Directory V5.2 application, certain requests to the application fail. You must use the associated IBM HTTP server to reference the application. Security directives for LDAP server authentication are set up and required by the IBM Telephone Directory application during the creation of a new application server instance. WebSphere Application Server's internal HTTP server is not set up with the necessary security directives, and certain requests to the application fail if the internal HTTP server is used. See Interaction with IBM HTTP serveri5/OS^® for more information.

Troubleshoot usage
Problem Cause Solution
Missing link to the application The URL http://your.server.name:port/ibm-bizApps/welcome/home.do takes you to the entry point for IBM Business Solutions, including the IBM Telephone Directory V5.2 application. If the link to the IBM Telephone Directory V5.2 application is missing, check to ensure that both the IBM Welcome Page application and the IBM Telephone Directory application are started.
Administration user ID confusion It might be confusing as to which user ID you should input for authentication to the application when you (the administrator) need to update or register a user in a closed enrollment environment. The default user ID is Administrator, and the password is set up during installation. Do not enter your personal user ID and password. Application user IDs are always viewable to everyone. If you do not know the user ID for an entry, use the application's search page to find the entry. The user ID is displayed under the picture.
Internal server error during search or registration If you try to search on a user or register a user and get an HTTP 500 - Internal Server Error, this might mean that your setup files have been corrupted. The IBM Telephone Directory V5.2 application might not be able to find the associated configuration files for the application. Reinstall the IBM Telephone Directory V5.2 application.
System error during search If you try to search on a user and get the following error: A system error has occurred! Try again later, this generally means that your LDAP server has not been started. Start the LDAP server, and try your search again.
Operation failed error during registration If you try to register a user and get the following error: ERROR: Operation failed. Contact your IBM Telephone Directory application administrator, this generally means that your LDAP server has not been started. Start the LDAP server, and try your registration again.
Operation failed error during entry updates or deletes If you try to update or delete a profile and get the following error: ERROR: Operation failed. Contact your IBM Telephone Directory application administrator, you might not have the appropriate directives configured in the HTTP server. A symptom of this problem is the lack of the authentication dialog to input your user ID and password before making changes. Manually add the missing LDAP configuration directives to the HTTP server configuration or reinstall the IBM Telephone Directory V5.2 application.
Object not found error
If you receive a 404 - Object not found error in the IBM Telephone Directory application, it might be because your plugin-cfg.xml file is corrupt.
Perform the following steps to check this file and fix it, if necessary:
Open the plugin-cfg.xml file, which is located at:
/QIBM/UserData/.../config/
cells/plugin-cfg.xml
Check to see if the following virtual host specifications are in your file (assuming a virtual host of default_host and a port of 80:
<VirtualHostGroup Name=
 "default_host">
<VirtualHost Name=
 "80"/>
Check to see if the following URI affinity cookies are in your file:
<URI AffinityCookie=
 "JSESSIONID"
Name="/bizApps/*"/>

<URI AffinityCookie=
 "JSESSIONID"
Name="/itd/*">
If these specifications are not in your file, open the WebSphere Application Server administration console.

Expand Environment.

Click Update WebServer plugin.

Click OK.

Stop and restart the application server.

Stop and restart the HTTP server.
Some values were not saved If you do not have the authority to add, change, or remove a particular field, and try to do so in the application, you will receive a message that states that some values were not saved because the directory does not allow you to add them to your profile, and to contact the application administrator for details. If you receive this error, it means that authentication required has been configured on the IBM Telephone Directory V5.2 application.
Special characters (such as ", &, <, or >) not handled correctly The IBM Telephone Directory V5.2 application has been written to accept and handle all characters correctly, even those identified as special characters (or metacharacters) for HTML, JavaScript™, and LDAP filters and attribute values. There are known cases when the IBM Telephone Directory application handles special characters for LDAP attribute values correctly, according to the RFC 2253 standard. However, the iSeries Directory Services (LDAP) directory server does not fully support the standard. For these cases, there is nothing that can be done other than to avoid the use of such characters.
The quote (") character is an example of this problem. The RFC 2253 standard specifies that the character must be escaped by preceding it with a backslash (\) to be accepted as a literal character in an LDAP attribute value. Since the current version of iSeries Directory Services (LDAP) does not fully support RFC 2253, the server saves both the backslash character as well as the quote character.
Error logging and debugging

Error logs
The application server has a variety of logs to which messages are written. For example, system message, which can be written by any application server component or application are written to general purpose logs such as the JAVA Virtual Machine (JVM) logs and the IBM Service logs. Other logs are very specific in nature and are scoped to a particular component or activity. For example, the HTTP Server plugin maintains a component-specific plugin log.
The general purpose logs, such as JVM and IBM Service, are used to monitor the health of the application server and assist in troubleshooting. Troubleshooting for specific components might require additional log analysis, such as component or product specific log files.

Trace statements
Application trace statements can be enabled for the purpose of debugging problems. If problems persist, and call IBM Service for help, one of the first thing they might ask you for is a copy of the application's trace output. Trace statements are enabled by adding a line to the application's configuration file and restarting the application.
The application will read the new configuration when it is started. Application trace statement will be enabled at that time. When enabled, trace statements are written to the server's SystemOut.log file.

LDAP and HTTP server trace
See the following information for details on LDAP and HTTP server trace:

Troubleshoot Directory Server

Troubleshoot HTTP server

General troubleshooting information

These resources provide general troubleshooting assistance.

For WebSphere Application Server - Express V5, see the associated Troubleshooting topic.

For WebSphere Application Server - Express V5.1, see the associated Troubleshooting topic.

For WebSphere Application Server - Express V6, see the associated Troubleshooting topic.

For WebSphere Application Server V5, see the associated Troubleshooting topic.

For WebSphere Application Server V5.1, see the associated Troubleshooting topic.

For WebSphere Application Server V6, see the associated Troubleshooting topic.

Read the WebSphere Application Server - Express V5.1 Release Notes

Read the WebSphere Application Server - Express V5 Release Notes

Read the WebSphere Application Server V5 Release Notes

Read the WebSphere Application Server V5.1 Release Notes

Read the WebSphere Application Server V6 Release Notes

Parent topic:
IBM Telephone Directory V5.2

Problem	Cause	Solution
Log in fails	In the application, user IDs and passwords must contain characters that map to the job CCSID that is used by the HTTP server. Otherwise, authentication fails.	Make sure that your characters map to the job CCSID that is used by the HTTP server. To determine the job CCSID for the HTTP server, enter WRKACTJOB on a CL command line and select Display job definition attributes. The HTTP server CCSID is determined by the HTTP server defaultFSCCSID directive. For more information, see Notices and limitations.
URL fails or the application does not appear	If you did not start the IBM Welcome Page application, the URL fails (http://your.server.name:port/ibm-bizApps/welcome-home.do or http://your.server.name:port/ibm-bizApps/welcome-admin.do). Problems also occur if you start the IBM Welcome Page application but do not start the IBM Telephone Directory application. If the IBM Telephone Directory application is not running, the Welcome Page application does not have links to it.	Start the IBM Welcome Page application and the IBM Telephone Directory application.
Requests to the application fail	If you used the internal HTTP server included with WebSphere^® Application Server to reference the IBM Telephone Directory V5.2 application, certain requests to the application fail.	You must use the associated IBM HTTP server to reference the application. Security directives for LDAP server authentication are set up and required by the IBM Telephone Directory application during the creation of a new application server instance. WebSphere Application Server's internal HTTP server is not set up with the necessary security directives, and certain requests to the application fail if the internal HTTP server is used. See Interaction with IBM HTTP serveri5/OS^® for more information.

Problem	Cause	Solution
Missing link to the application	The URL http://your.server.name:port/ibm-bizApps/welcome/home.do takes you to the entry point for IBM Business Solutions, including the IBM Telephone Directory V5.2 application.	If the link to the IBM Telephone Directory V5.2 application is missing, check to ensure that both the IBM Welcome Page application and the IBM Telephone Directory application are started.
Administration user ID confusion	It might be confusing as to which user ID you should input for authentication to the application when you (the administrator) need to update or register a user in a closed enrollment environment.	The default user ID is Administrator, and the password is set up during installation. Do not enter your personal user ID and password. Application user IDs are always viewable to everyone. If you do not know the user ID for an entry, use the application's search page to find the entry. The user ID is displayed under the picture.
Internal server error during search or registration	If you try to search on a user or register a user and get an HTTP 500 - Internal Server Error, this might mean that your setup files have been corrupted. The IBM Telephone Directory V5.2 application might not be able to find the associated configuration files for the application.	Reinstall the IBM Telephone Directory V5.2 application.
System error during search	If you try to search on a user and get the following error: A system error has occurred! Try again later, this generally means that your LDAP server has not been started.	Start the LDAP server, and try your search again.
Operation failed error during registration	If you try to register a user and get the following error: ERROR: Operation failed. Contact your IBM Telephone Directory application administrator, this generally means that your LDAP server has not been started.	Start the LDAP server, and try your registration again.
Operation failed error during entry updates or deletes	If you try to update or delete a profile and get the following error: ERROR: Operation failed. Contact your IBM Telephone Directory application administrator, you might not have the appropriate directives configured in the HTTP server. A symptom of this problem is the lack of the authentication dialog to input your user ID and password before making changes.	Manually add the missing LDAP configuration directives to the HTTP server configuration or reinstall the IBM Telephone Directory V5.2 application.
Object not found error	If you receive a 404 - Object not found error in the IBM Telephone Directory application, it might be because your plugin-cfg.xml file is corrupt.	Perform the following steps to check this file and fix it, if necessary: Open the plugin-cfg.xml file, which is located at: /QIBM/UserData/.../config/ cells/plugin-cfg.xml Check to see if the following virtual host specifications are in your file (assuming a virtual host of default_host and a port of 80: <VirtualHostGroup Name= "default_host"> <VirtualHost Name= "80"/> Check to see if the following URI affinity cookies are in your file: <URI AffinityCookie= "JSESSIONID" Name="/bizApps/"/> <URI AffinityCookie= "JSESSIONID" Name="/itd/"> If these specifications are not in your file, open the WebSphere Application Server administration console. Expand Environment. Click Update WebServer plugin. Click OK. Stop and restart the application server. Stop and restart the HTTP server.
Some values were not saved	If you do not have the authority to add, change, or remove a particular field, and try to do so in the application, you will receive a message that states that some values were not saved because the directory does not allow you to add them to your profile, and to contact the application administrator for details.	If you receive this error, it means that authentication required has been configured on the IBM Telephone Directory V5.2 application.
Special characters (such as ", &, <, or >) not handled correctly	The IBM Telephone Directory V5.2 application has been written to accept and handle all characters correctly, even those identified as special characters (or metacharacters) for HTML, JavaScript™, and LDAP filters and attribute values.	There are known cases when the IBM Telephone Directory application handles special characters for LDAP attribute values correctly, according to the RFC 2253 standard. However, the iSeries Directory Services (LDAP) directory server does not fully support the standard. For these cases, there is nothing that can be done other than to avoid the use of such characters. The quote (") character is an example of this problem. The RFC 2253 standard specifies that the character must be escaped by preceding it with a backslash (\) to be accepted as a literal character in an LDAP attribute value. Since the current version of iSeries Directory Services (LDAP) does not fully support RFC 2253, the server saves both the backslash character as well as the quote character.